diff --git a/docs-v2/content/en/docs/pipeline-stages/deployers/helm.md b/docs-v2/content/en/docs/pipeline-stages/deployers/helm.md index 7791b8e9a37..9a5d9731c64 100644 --- a/docs-v2/content/en/docs/pipeline-stages/deployers/helm.md +++ b/docs-v2/content/en/docs/pipeline-stages/deployers/helm.md @@ -16,12 +16,26 @@ To use `helm` with Skaffold, the `helm` binary must be installed on your machine # Configuring your Helm Project with Skaffold -Skaffold supports projects set up to deploy with Helm, but certain aspects of the project need to be configured correctly in order for Skaffold to work properly. This guide should demystify some of the nuance around using Skaffold with Helm to help you get started quickly. +Skaffold supports projects set up to render and/or deploy with Helm, but certain aspects of the project need to be configured correctly in order for Skaffold to work properly. This guide should demystify some of the nuance around using Skaffold with Helm to help you get started quickly. -{{< alert title="No more `artifactOverrides`" >}} -Skaffold no longer requires the intricate configuring of `artifactOverrides` and image naming strategies. +{{< alert title="No more `artifactOverrides` or `imageStrategy`" >}} +Skaffold no longer requires the intricate configuring of `artifactOverrides` or `imageStrategy` fields. See docs [here]({{< relref "#image-reference-strategies" >}}) on how old `artifactOverrides` and `imageStrategy` values translate to `setValues` entires in the latest Skaffold schemas (`apiVersion: skaffold/v3alpha1` or skaffold binary version `v2.0.0` onwards) {{< /alert >}} +{{< alert title="In Skaffold `v2` the primary difference between the helm renderer (`manifest.helm.*`) and the helm deployer `deploy.helm.*` is the use of `helm template` vs `helm install` +{{< /alert >}} + +## How `helm` deploy support works in Skaffold +In the latest version of Skaffold, the primary methods of using `helm` templating with Skaffold involve the `manifests.helm.setValues` and the `manifests.helm.setValueTemplates` fields. `manifests.helm.setValues` supplies the key:value pair to substitute from a users `values.yaml` file (a standard `helm` file for rendering). `manifests.helm.setValueTemplates` does a similar thing only the key:value value comes from an environment variable instead of a given value. The thing to note here is that when using a value that is the same name as an artifact name, that value will be replaced by the fully qualified artifact name (eg: `image: gcr.io/example-repo/skaffold-helm-image:latest@sha256:`) for the current build (or the specified value from additional configuration eg: CLI flags or config from `skaffold.yaml`). Depending on how a user's `values.yaml` and charts specify `image: $IMAGE_TEMPLATE`, the docs [here]({{< relref "#image-reference-strategies" >}}) explain the proper `setValues` to use. When migrating from schema version `v2beta29` or less, Skaffold will automatically configure these values to continue to work. + + +`helm` render support in Skaffold is accomplished by calling `helm install ...` and using the `skaffold` binary as a `helm` `--post-renderer`. This works by having Skaffold run `helm install ...` taking into consideration all of the supplied flags, skaffold.yaml configuration, etc. and creating an intermediate yaml manifest with all helm replacements except that the fully qualified image from the current run is NOT added but instead a placeholder with the artifact name - eg: `skaffold-helm-image`. Then the skaffold post-renderer is called to convert `image: skaffold-helm-image` -> `image: gcr.io/example-repo/skaffold-helm-image:latest@sha256:` in specified locations (specific allowlisted k8s objects and/or k8s object fields). This above replacement is nearly identical to how it works for values.yaml files using only the `image` key in `values.yaml` - eg: +`image: "{{.Values.image}}"` + +When using `image.repoistory` + `image.tag` or `image.registry` + `image.repository` + `image.tag` - eg: +`image: "{{.Values.image.repository}}:{{.Values.image.tag}}"` +`image: "{{.Values.image.registry}}/{{.Values.image.repository}}:{{.Values.image.tag}}"` +there is some specialized logic that the skaffold `post-renderer` uses to properly handling these cases. See the docs [here]({{< relref "#image-reference-strategies" >}}) on the correct way to specify these for Skaffold using `setValues` ## Image Configuration The normal Helm convention for defining image references is through the `values.yaml` file. Often, image information is configured through an `image` stanza in the values file, which might look something like this: @@ -55,7 +69,7 @@ Associating the Helm image key allows Skaffold to track the image being built, a build: artifacts: - image: gcr.io/my-project/my-image # must match in setValues -deploy: +manifests: helm: releases: - name: my-release @@ -69,7 +83,7 @@ The `setValues` configuration binds a Helm key to the specified value. The `ima ### Multiple image overrides -To override multiple images (ie a Pod with a side car) you can simply add additional variables. For example, the following helm template: +To override multiple images (ie a Pod with a side car) you can simply add additional variables. For example, the following helm install: ```yaml spec: @@ -85,7 +99,7 @@ spec: can be overriden with: ``` -deploy: +manifests: helm: releases: - name: my-release @@ -96,6 +110,129 @@ deploy: helm: {} ``` +### Image reference strategies + +Skaffold supports three _image reference strategies_ for Helm: + +1. `fqn`: provides a fully-qualified image reference (default); +2. `helm`: provides separate repository and tag portions (shown above); +3. `helm+explicitRegistry`: provides separate registry, repository, and tag portions. + +#### `fqn` strategy: single fully-qualified name (default) + +With the fully-qualified name strategy, Skaffold configures Helm by setting a key to the fully-tagged image reference. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image # must match in setValues +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + setValues: + image: gcr.io/my-project/my-image +``` +The `values.yaml` (note that Skaffold overrides this value): +``` +image: gcr.io/other-project/other-image:latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image}}" +``` + +Skaffold will invoke +``` +helm install --set-string image= --post-renderer= +``` + +#### `helm` strategy: split repository and tag + +Skaffold can be configured to provide Helm with a separate repository and tag. The key used in the `artifactOverrides` is used as base portion producing two keys `{key}.repository` and `{key}.tag`. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + artifactOverrides: + repository: gcr.io/my-project/my-image + tag: gcr.io/my-project/my-image +``` + +The `values.yaml` (note that Skaffold overrides these values): +``` +image: + repository: gcr.io/other-project/other-image + tag: latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image.repository}}:{{.Values.image.tag}}" +``` + +Skaffold will invoke +``` +helm install --set-string image.repository=,tag= --post-renderer= +``` + +#### `helm`+`explicitRegistry` strategy: split registry, repository, and tag + +Skaffold can also be configured to provide Helm with a separate repository and tag. The key used in the `artifactOverrides` is used as base portion producing three keys: `{key}.registry`, `{key}.repository`, and `{key}.tag`. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + artifactOverrides: + registry: gcr.io/my-project/my-image + repository: gcr.io/my-project/my-image + tag: gcr.io/my-project/my-image +``` + +The `values.yaml` (note that Skaffold overrides these values): +``` +image: + registry: gcr.io + repository: other-project/other-image + tag: latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image.registry}}/{{.Values.image.repository}}:{{.Values.image.tag}}" +``` + +Skaffold will invoke +``` +helm install --set-string image.registry=,image.repository=,tag= --post-renderer= +``` + ### Helm Build Dependencies The `skipBuildDependencies` flag toggles whether dependencies of the Helm chart are built with the `helm dep build` command. This command manipulates files inside the `charts` subfolder of the specified Helm chart. diff --git a/docs-v2/content/en/docs/pipeline-stages/renderers/helm.md b/docs-v2/content/en/docs/pipeline-stages/renderers/helm.md index e28b9152c00..2439f07ad90 100644 --- a/docs-v2/content/en/docs/pipeline-stages/renderers/helm.md +++ b/docs-v2/content/en/docs/pipeline-stages/renderers/helm.md @@ -1,6 +1,6 @@ --- -title: "Helm" -linkTitle: "Helm" +title: "Helm [UPDATED]" +linkTitle: "Helm [UPDATED]" weight: 40 featureId: render --- @@ -13,36 +13,240 @@ for projects configured to use helm. To use `helm` with Skaffold, the `helm` binary must be installed on your machine. Skaffold will not install it for you. {{< /alert >}} -# Rendering with helm -[`helm template`](https://helm.sh/docs/helm/helm_template/) allows Kubernetes -developers to locally render templates. Skaffold relies on `helm template --post-renderer` functionality to substitute the images -in the rendered charts with Skaffold built images. +# Configuring your Helm Project with Skaffold -{{< alert title="Note" >}} -If you wish to deploy using helm, please see [Configuring Helm Deployer Section]({{< relref "/docs/pipeline-stages/deployers/helm.md" >}}) -{{< /alert >}} - -### Configuration - -To use render using helm but deploy via kubectl deployer define your helm charts under -`helm` in `manifests` section of `skaffold.yaml`. +Skaffold supports projects set up to render and/or deploy with Helm, but certain aspects of the project need to be configured correctly in order for Skaffold to work properly. This guide should demystify some of the nuance around using Skaffold with Helm to help you get started quickly. +{{< alert title="No more `artifactOverrides` or `imageStrategy`" >}} +Skaffold no longer requires the intricate configuring of `artifactOverrides` or `imageStrategy` fields. See docs [here]({{< relref "#image-reference-strategies" >}}) on how old `artifactOverrides` and `imageStrategy` values translate to `setValues` entires in the latest Skaffold schemas (`apiVersion: skaffold/v3alpha1` or skaffold binary version `v2.0.0` onwards) +{{< /alert >}} -### Example -The following `manifests` section instructs Skaffold to render -artifacts using helm. - -{{% readfile file="samples/renderers/helm.yaml" %}} +{{< alert title="In Skaffold `v2` the primary difference between the helm renderer (`manifest.helm.*`) and the helm deployer `deploy.helm.*` is the use of `helm template` vs `helm install` +{{< /alert >}} +## How `helm` render support works in Skaffold +In the latest version of Skaffold, the primary methods of using `helm` templating with Skaffold involve the `manifests.helm.setValues` and the `manifests.helm.setValueTemplates` fields. `manifests.helm.setValues` supplies the key:value pair to substitute from a users `values.yaml` file (a standard `helm` file for rendering). `manifests.helm.setValueTemplates` does a similar thing only the key:value value comes from an environment variable instead of a given value. The thing to note here is that when using a value that is the same name as an artifact name, that value will be replaced by the fully qualified artifact name (eg: `image: gcr.io/example-repo/skaffold-helm-image:latest@sha256:`) for the current build (or the specified value from additional configuration eg: CLI flags or config from `skaffold.yaml`). Depending on how a user's `values.yaml` and charts specify `image: $IMAGE_TEMPLATE`, the docs [here]({{< relref "#image-reference-strategies" >}}) explain the proper `setValues` to use. When migrating from schema version `v2beta29` or less, Skaffold will automatically configure these values to continue to work. + + +`helm` render support in Skaffold is accomplished by calling `helm template ...` and using the `skaffold` binary as a `helm` `--post-renderer`. This works by having Skaffold run `helm template ...` taking into consideration all of the supplied flags, skaffold.yaml configuration, etc. and creating an intermediate yaml manifest with all helm replacements except that the fully qualified image from the current run is NOT added but instead a placeholder with the artifact name - eg: `skaffold-helm-image`. Then the skaffold post-renderer is called to convert `image: skaffold-helm-image` -> `image: gcr.io/example-repo/skaffold-helm-image:latest@sha256:` in specified locations (specific allowlisted k8s objects and/or k8s object fields). This above replacement is nearly identical to how it works for values.yaml files using only the `image` key in `values.yaml` - eg: +`image: "{{.Values.image}}"` + +When using `image.repoistory` + `image.tag` or `image.registry` + `image.repository` + `image.tag` - eg: +`image: "{{.Values.image.repository}}:{{.Values.image.tag}}"` +`image: "{{.Values.image.registry}}/{{.Values.image.repository}}:{{.Values.image.tag}}"` +there is some specialized logic that the skaffold `post-renderer` uses to properly handling these cases. See the docs [here]({{< relref "#image-reference-strategies" >}}) on the correct way to specify these for Skaffold using `setValues` + +## Image Configuration +The normal Helm convention for defining image references is through the `values.yaml` file. Often, image information is configured through an `image` stanza in the values file, which might look something like this: + +```project_root/values.yaml``` +```yaml +image: + repository: gcr.io/my-project/my-image + tag: v1.2.0 + pullPolicy: IfNotPresent +``` + +This image would then be referenced in a templated resource file, maybe like this: + +```project_root/templates/deployment.yaml:``` +```yaml +spec: + template: + spec: + containers: + - name: {{ .Chart.Name }} + image: {{ .Values.image.repository }}:{{ .Values.image.tag}} + imagePullPolicy: {{ .Values.image.pullPolicy }} +``` + +**IMPORTANT: To get Skaffold to work with Helm, the `image` key must be configured in the skaffold.yaml.** + +Associating the Helm image key allows Skaffold to track the image being built, and then configure Helm to substitute it in the proper resource definitions to be deployed to your cluster. In practice, this looks something like this: + +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image # must match in setValues +manifests: + helm: + releases: + - name: my-release + setValues: + image: gcr.io/my-project/my-image # no tag present! + imageStrategy: + helm: {} +``` + +The `setValues` configuration binds a Helm key to the specified value. The `imageStrategy` configures the image reference strategy for informing Helm of the image reference to a newly built artifact. + +### Multiple image overrides + +To override multiple images (ie a Pod with a side car) you can simply add additional variables. For example, the following helm template: + +```yaml +spec: + containers: + - name: firstContainer + image: "{{.Values.firstContainerImage}}" + .... + - name: secondContainer + image: "{{.Values.secondContainerImage}}" + ... +``` + +can be overriden with: + +``` +manifests: + helm: + releases: + - name: my-release + setValues: + firstContainerImage: gcr.io/my-project/first-image # no tag present! + secondContainerImage: gcr.io/my-project/second-image # no tag present! + imageStrategy: + helm: {} +``` + +### Image reference strategies + +Skaffold supports three _image reference strategies_ for Helm: + +1. `fqn`: provides a fully-qualified image reference (default); +2. `helm`: provides separate repository and tag portions (shown above); +3. `helm+explicitRegistry`: provides separate registry, repository, and tag portions. + +#### `fqn` strategy: single fully-qualified name (default) + +With the fully-qualified name strategy, Skaffold configures Helm by setting a key to the fully-tagged image reference. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image # must match in setValues +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + setValues: + image: gcr.io/my-project/my-image +``` +The `values.yaml` (note that Skaffold overrides this value): +``` +image: gcr.io/other-project/other-image:latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image}}" +``` + +Skaffold will invoke +``` +helm template --set-string image= --post-renderer= +``` + +#### `helm` strategy: split repository and tag + +Skaffold can be configured to provide Helm with a separate repository and tag. The key used in the `artifactOverrides` is used as base portion producing two keys `{key}.repository` and `{key}.tag`. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + artifactOverrides: + repository: gcr.io/my-project/my-image + tag: gcr.io/my-project/my-image +``` + +The `values.yaml` (note that Skaffold overrides these values): +``` +image: + repository: gcr.io/other-project/other-image + tag: latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image.repository}}:{{.Values.image.tag}}" +``` + +Skaffold will invoke +``` +helm template --set-string image.repository=,tag= --post-renderer= +``` + +#### `helm`+`explicitRegistry` strategy: split registry, repository, and tag + +Skaffold can also be configured to provide Helm with a separate repository and tag. The key used in the `artifactOverrides` is used as base portion producing three keys: `{key}.registry`, `{key}.repository`, and `{key}.tag`. + +The `skaffold.yaml` setup: +```yaml +build: + artifacts: + - image: gcr.io/my-project/my-image +manifests: + helm: + releases: + - name: my-chart + chartPath: helm + artifactOverrides: + registry: gcr.io/my-project/my-image + repository: gcr.io/my-project/my-image + tag: gcr.io/my-project/my-image +``` + +The `values.yaml` (note that Skaffold overrides these values): +``` +image: + registry: gcr.io + repository: other-project/other-image + tag: latest +``` + +The chart template: +```yaml +spec: + containers: + - name: {{ .Chart.Name }} + image: "{{.Values.image.registry}}/{{.Values.image.repository}}:{{.Values.image.tag}}" +``` + +Skaffold will invoke +``` +helm template --set-string image.registry=,image.repository=,tag= --post-renderer= +``` + +### Helm Build Dependencies + +The `skipBuildDependencies` flag toggles whether dependencies of the Helm chart are built with the `helm dep build` command. This command manipulates files inside the `charts` subfolder of the specified Helm chart. + +If `skipBuildDependencies` is `false` then `skaffold dev` does **not** watch the `charts` subfolder of the Helm chart, in order to prevent a build loop - the actions of `helm dep build` always trigger another build. + +If `skipBuildDependencies` is `true` then `skaffold dev` watches all files inside the Helm chart. ### `skaffold.yaml` Configuration The `helm` type offers the following options: -{{< schema root="manifests-helm" >}} +{{< schema root="HelmDeploy" >}} Each `release` includes the following fields: {{< schema root="HelmRelease" >}} - diff --git a/docs-v2/content/en/docs/upgrading/_index.md b/docs-v2/content/en/docs/upgrading/_index.md index 4d727617f95..46b5205ee1b 100644 --- a/docs-v2/content/en/docs/upgrading/_index.md +++ b/docs-v2/content/en/docs/upgrading/_index.md @@ -37,6 +37,7 @@ Outside of the above, there are currently no known other regressions when migrat - `helm` renderer/deployer usage (see [helm docs]({{< relref "/docs/pipeline-stages/renderers/helm" >}}) for more details) - v1 `kpt` deployer usage - `skaffold render` flags usage (see [render docs]({{< relref "/docs/pipeline-stages/renderers" >}}) and [render schema]({{< relref "/docs/references/yaml#manifests" >}}) for more details) +- `helm` hooks support is currently not available in the latest version of skaffold due to helm not supporting hooks when using a `--post-renderer` [Skaffold Helm hook issue](https://github.com/GoogleContainerTools/skaffold/issues/7989), [Helm post-renderer hook issue](https://github.com/helm/helm/issues/7891) If you encounter any issues using skaffold `v2.0.0-beta3`, particularly any regressions that used to work differently or succeed in `v1`, please file an issue at[GoogleContainerTools/skaffold](https://github.com/GoogleContainerTools/skaffold/issues).