Merge pull request #1875 from paigecalvert/add-v4-placeholder

Copy v3 versioned_docs to v4 docs

Author: paigecalvert

docs/_v4-in-progress.mdx

@@ -0,0 +1,3 @@
+:::warning
+This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see [Helm 4 Overview](/overview.md).
+:::

docs/changelog.md

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 2
-sidebar_label: Full Changelog
+sidebar_label: Helm 4 Full Changelog
 ---
 
 # Helm 4 Full Changelog

docs/chart_best_practices/conventions.md

@@ -0,0 +1,49 @@
+---
+title: General Conventions
+description: General conventions for charts.
+sidebar_position: 1
+---
+
+This part of the Best Practices Guide explains general conventions.
+
+## Chart Names
+
+Chart names must be lower case letters and numbers. Words _may_ be separated
+with dashes (-):
+
+Examples:
+
+```
+drupal
+nginx-lego
+aws-cluster-autoscaler
+```
+
+Neither uppercase letters nor underscores can be used in chart names. Dots
+should not be used in chart names.
+
+## Version Numbers
+
+Wherever possible, Helm uses [SemVer 2](https://semver.org) to represent version
+numbers. (Note that Docker image tags do not necessarily follow SemVer, and are
+thus considered an unfortunate exception to the rule.)
+
+When SemVer versions are stored in Kubernetes labels, we conventionally alter
+the `+` character to an `_` character, as labels do not allow the `+` sign as a
+value.
+
+## Formatting YAML
+
+YAML files should be indented using _two spaces_ (and never tabs).
+
+## Usage of the Words Helm and Chart
+
+There are a few conventions for using the words _Helm_ and _helm_.
+
+- _Helm_ refers to the project as a whole
+- `helm` refers to the client-side command
+- The term `chart` does not need to be capitalized, as it is not a proper noun
+- However, `Chart.yaml` does need to be capitalized because the file name is
+  case sensitive
+
+When in doubt, use _Helm_ (with an uppercase 'H').

docs/chart_best_practices/custom_resource_definitions.md

@@ -0,0 +1,71 @@
+---
+title: Custom Resource Definitions
+description: How to handle creating and using CRDs.
+sidebar_position: 7
+---
+
+This section of the Best Practices Guide deals with creating and using Custom
+Resource Definition objects.
+
+When working with Custom Resource Definitions (CRDs), it is important to
+distinguish two different pieces:
+
+- There is a declaration of a CRD. This is the YAML file that has the kind
+  `CustomResourceDefinition`
+- Then there are resources that _use_ the CRD. Say a CRD defines
+  `foo.example.com/v1`. Any resource that has `apiVersion: example.com/v1` and
+  kind `Foo` is a resource that uses the CRD.
+
+## Install a CRD Declaration Before Using the Resource
+
+Helm is optimized to load as many resources into Kubernetes as fast as possible.
+By design, Kubernetes can take an entire set of manifests and bring them all
+online (this is called the reconciliation loop).
+
+But there's a difference with CRDs.
+
+For a CRD, the declaration must be registered before any resources of that CRDs
+kind(s) can be used. And the registration process sometimes takes a few seconds.
+
+### Method 1: Let `helm` Do It For You
+
+With the arrival of Helm 3, we removed the old `crd-install` hooks for a more
+simple methodology. There is now a special directory called `crds` that you can
+create in your chart to hold your CRDs. These CRDs are not templated, but will
+be installed by default when running a `helm install` for the chart. If the CRD
+already exists, it will be skipped with a warning. If you wish to skip the CRD
+installation step, you can pass the `--skip-crds` flag.
+
+#### Some caveats (and explanations)
+
+There is no support at this time for upgrading or deleting CRDs using Helm. This
+was an explicit decision after much community discussion due to the danger for
+unintentional data loss. Furthermore, there is currently no community consensus
+around how to handle CRDs and their lifecycle. As this evolves, Helm will add
+support for those use cases.
+
+The `--dry-run` flag of `helm install` and `helm upgrade` is not currently
+supported for CRDs. The purpose of "Dry Run" is to validate that the output of
+the chart will actually work if sent to the server. But CRDs are a modification
+of the server's behavior. Helm cannot install the CRD on a dry run, so the
+discovery client will not know about that Custom Resource (CR), and validation
+will fail. You can alternatively move the CRDs to their own chart or use `helm
+template` instead.
+
+Another important point to consider in the discussion around CRD support is how
+the rendering of templates is handled. One of the distinct disadvantages of the
+`crd-install` method used in Helm 2 was the inability to properly validate
+charts due to changing API availability (a CRD is actually adding another
+available API to your Kubernetes cluster). If a chart installed a CRD, `helm` no
+longer had a valid set of API versions to work against. This is also the reason
+behind removing templating support from CRDs. With the new `crds` method of CRD
+installation, we now ensure that `helm` has completely valid information about
+the current state of the cluster.
+
+### Method 2: Separate Charts
+
+Another way to do this is to put the CRD definition in one chart, and then put
+any resources that use that CRD in _another_ chart.
+
+In this method, each chart must be installed separately. However, this workflow
+may be more useful for cluster operators who have admin access to a cluster

docs/chart_best_practices/dependencies.mdx

@@ -0,0 +1,85 @@
+---
+title: Dependencies
+description: Covers best practices for Chart dependencies.
+sidebar_position: 4
+---
+
+import Helm4 from "../_v4-in-progress.mdx" 
+
+<Helm4/>
+
+This section of the guide covers best practices for `dependencies` declared in
+`Chart.yaml`.
+
+## Versions
+
+Where possible, use version ranges instead of pinning to an exact version. The
+suggested default is to use a patch-level version match:
+
+```yaml
+version: ~1.2.3
+```
+
+This will match version `1.2.3` and any patches to that release.  In other
+words, `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0`
+
+For the complete version matching syntax, please see the [semver
+documentation](https://github.com/Masterminds/semver#checking-version-constraints).
+
+### Prerelease versions
+
+The above versioning constraints will not match on pre-release versions.
+For example `version: ~1.2.3` will match `version: ~1.2.4` but not `version: ~1.2.3-1`.
+The following provides a pre-release as well as patch-level matching:
+
+```yaml
+version: ~1.2.3-0
+```
+
+### Repository URLs
+
+Where possible, use `https://` repository URLs, followed by `http://` URLs.
+
+If the repository has been added to the repository index file, the repository
+name can be used as an alias of URL. Use `alias:` or `@` followed by repository
+names.
+
+File URLs (`file://...`) are considered a "special case" for charts that are
+assembled by a fixed deployment pipeline.
+
+When using [downloader plugins](/topics/plugins.mdx#downloader-plugins)
+the URL scheme will be specific to the plugin. Note, a user of the chart will
+need to have a plugin supporting the scheme installed to update or build the
+dependency.
+
+Helm cannot perform dependency management operations on the dependency when the
+`repository` field is left blank. In that case Helm will assume the dependency
+is in a sub-directory of the `charts` folder with the name being the same as the
+`name` property for the dependency.
+
+## Conditions and Tags
+
+Conditions or tags should be added to any dependencies that _are optional_. Note that by default a `condition` is `true`.
+
+The preferred form of a condition is:
+
+```yaml
+condition: somechart.enabled
+```
+
+Where `somechart` is the chart name of the dependency.
+
+When multiple subcharts (dependencies) together provide an optional or swappable
+feature, those charts should share the same tags.
+
+For example, if both `nginx` and `memcached` together provide performance
+optimizations for the main app in the chart, and are required to both be present
+when that feature is enabled, then they should both have a tags section like
+this:
+
+```yaml
+tags:
+  - webaccelerator
+```
+
+This allows a user to turn that feature on and off with one tag.

docs/chart_best_practices/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Best Practices
+sidebar: true
+sidebar_position: 4
+---
+
+# The Chart Best Practices Guide
+
+This guide covers the Helm Team's considered best practices for creating charts.
+It focuses on how charts should be structured.
+
+We focus primarily on best practices for charts that may be publicly deployed.
+We know that many charts are for internal-use only, and authors of such charts
+may find that their internal interests override our suggestions here.
+
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

docs/chart_best_practices/labels.md

@@ -0,0 +1,46 @@
+---
+title: Labels and Annotations
+description: Covers best practices for using labels and annotations in your Chart.
+sidebar_position: 5
+---
+
+This part of the Best Practices Guide discusses the best practices for using
+labels and annotations in your chart.
+
+## Is it a Label or an Annotation?
+
+An item of metadata should be a label under the following conditions:
+
+- It is used by Kubernetes to identify this resource
+- It is useful to expose to operators for the purpose of querying the system.
+
+For example, we suggest using `helm.sh/chart: NAME-VERSION` as a label so that
+operators can conveniently find all of the instances of a particular chart to
+use.
+
+If an item of metadata is not used for querying, it should be set as an
+annotation instead.
+
+Helm hooks are always annotations.
+
+## Standard Labels
+
+The following table defines common labels that Helm charts use. Helm itself
+never requires that a particular label be present. Labels that are marked REC
+are recommended, and _should_ be placed onto a chart for global consistency.
+Those marked OPT are optional. These are idiomatic or commonly in use, but are
+not relied upon frequently for operational purposes.
+
+Name|Status|Description
+-----|------|----------
+`app.kubernetes.io/name` | REC | This should be the app name, reflecting the entire app. Usually `{{ template "name" . }}` is used for this. This is used by many Kubernetes manifests, and is not Helm-specific.
+`helm.sh/chart` | REC | This should be the chart name and version: `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`.
+`app.kubernetes.io/managed-by` | REC | This should always be set to `{{ .Release.Service }}`. It is for finding all things managed by Helm.
+`app.kubernetes.io/instance` | REC | This should be the `{{ .Release.Name }}`. It aids in differentiating between different instances of the same application.
+`app.kubernetes.io/version` | OPT | The version of the app and can be set to `{{ .Chart.AppVersion }}`.
+`app.kubernetes.io/component` | OPT | This is a common label for marking the different roles that pieces may play in an application. For example, `app.kubernetes.io/component: frontend`.
+`app.kubernetes.io/part-of` | OPT | When multiple charts or pieces of software are used together to make one application. For example, application software and a database to produce a website. This can be set to the top level application being supported.
+
+You can find more information on the Kubernetes labels, prefixed with
+`app.kubernetes.io`, in the [Kubernetes
+documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/).

docs/chart_best_practices/pods.md

@@ -0,0 +1,78 @@
+---
+title: Pods and PodTemplates
+description: Discusses formatting the Pod and PodTemplate portions in Chart manifests.
+sidebar_position: 6
+---
+
+This part of the Best Practices Guide discusses formatting the Pod and
+PodTemplate portions in chart manifests.
+
+The following (non-exhaustive) list of resources use PodTemplates:
+
+- Deployment
+- ReplicationController
+- ReplicaSet
+- DaemonSet
+- StatefulSet
+
+## Images
+
+A container image should use a fixed tag or the SHA of the image. It should not
+use the tags `latest`, `head`, `canary`, or other tags that are designed to be
+"floating".
+
+
+Images _may_ be defined in the `values.yaml` file to make it easy to swap out
+images.
+
+```yaml
+image: {{ .Values.redisImage | quote }}
+```
+
+An image and a tag _may_ be defined in `values.yaml` as two separate fields:
+
+```yaml
+image: "{{ .Values.redisImage }}:{{ .Values.redisTag }}"
+```
+
+## ImagePullPolicy
+
+`helm create` sets the `imagePullPolicy` to `IfNotPresent` by default by doing
+the following in your `deployment.yaml`:
+
+```yaml
+imagePullPolicy: {{ .Values.image.pullPolicy }}
+```
+
+And `values.yaml`:
+
+```yaml
+image:
+  pullPolicy: IfNotPresent
+```
+
+Similarly, Kubernetes defaults the `imagePullPolicy` to `IfNotPresent` if it is
+not defined at all. If you want a value other than `IfNotPresent`, simply update
+the value in `values.yaml` to your desired value.
+
+
+## PodTemplates Should Declare Selectors
+
+All PodTemplate sections should specify a selector. For example:
+
+```yaml
+selector:
+  matchLabels:
+      app.kubernetes.io/name: MyName
+template:
+  metadata:
+    labels:
+      app.kubernetes.io/name: MyName
+```
+
+This is a good practice because it makes the relationship between the set and
+the pod.
+
+But this is even more important for sets like Deployment. Without this, the
+_entire_ set of labels is used to select matching pods, and this will break if
+you use labels that change, like version or release date.