Skip to content

Commit

Permalink
doc(next-release): Add Documentation and Release Notes for Helm API v…
Browse files Browse the repository at this point in the history 
…ersions (#390)

* doc(next-release): Add Spinnaker Release Notes for Helm API versions

*doc(helm-charts): Update documentation guides with Helm options API versions and Kubernetes version configuration notes

* doc(next-release): Update next release preview with Helm options API versions release notes

* apply style guide and clean up a few things

* add ### heading for api and k8s version section

* a few more fixes not in the original PR but on the same page

---------

Co-authored-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
  • Loading branch information
@ciurescuraul @aimeeu
ciurescuraul and aimeeu committed Oct 31, 2023
1 parent de8342c commit f467046
Show file tree
Hide file tree
Showing 3 changed files with 72 additions and 57 deletions.
Binary file added content/en/docs/guides/user/kubernetes-v2/deploy-helm/api-versions.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
118 changes: 61 additions & 57 deletions content/en/docs/guides/user/kubernetes-v2/deploy-helm/index.md
View file
Expand Up @@ -5,89 +5,97 @@ description: >
Use Spinnaker to create Helm charts for your applications.
---

Spinnaker surfaces a "Bake (Manifest)" stage to turn templates into manifests
Spinnaker surfaces a **Bake (Manifest)** stage to turn templates into manifests
with the help of a templating engine. [Helm](https://helm.sh/) relies on the `helm template` command.
For more details, see `helm template --help`.

> Note: This stage is intended to help you package and deploy applications
> that you own, and are actively developing and redeploying frequently.
> It is not intended to serve as a one-time installation method for
> third-party packages. If that is your goal, it's arguably better to call
> `helm install` once when
> bootstrapping your Kubernetes cluster.
{{< alert color="warning" >}}
>This stage is intended to help you package and deploy applications that you own, one that are actively developing and redeploying frequently. It is not intended to serve as a one-time installation method for third-party packages. If that is your goal, it's better to call `helm install` once when bootstrapping your Kubernetes cluster.
> Note: Make sure that you have configured [artifact support](/docs/setup/other_config/artifacts/)
> in Spinnaker first. All Helm charts are fetched/stored as artifacts in
> Spinnaker. Read more in the [reference pages](/docs/reference/artifacts).
Make sure that you have configured [artifact support](/docs/setup/other_config/artifacts/) in Spinnaker first. All Helm charts are fetched/stored as artifacts in Spinnaker. Read more in the [reference pages](/docs/reference/artifacts).
{{< /alert >}}

## Configure the "Bake (Manifest)" stage
## Configure the Bake (Manifest) stage

When configuring the "Bake (Manifest)" stage using a Helm (Helm2 or Helm3) render engine,
you can specify the following:
When configuring the **Bake (Manifest)** stage using a Helm (Helm 2 or Helm 3) render engine, you can specify the following:

* __The release name__ (required)

The Helm release name for this chart. This determines the name of the
artifact produced by this stage.
The Helm release name for this chart. This determines the name of the artifact produced by this stage.

> Note: this name will override any changes you make to the name
> in the Produces Artifacts section.
*Note*: this name overrides any changes you make to the name in the Produces Artifacts section.

* __The template artifact__ (required)

The Helm chart that you will be deploying, stored remotely as a
`.tar.gz` archive. You can produce this by running `helm package
The Helm chart that you deploy, stored remotely as a `.tar.gz` archive. You can produce this by running `helm package
/path/to/chart`. For more details, `helm package --help`.

### Configure API versions and a Kubernetes version

To begin, you must set `API_VERSIONS_ENABLED` to `true`. This is an essential Deck environment variable that enables the functionality necessary to work with API versions and a Kubernetes version in your CD pipeline.

* __The capabilities apiVersions__ (optional)

The `apiVersions` field in the `Capabilities` object represents a set of API versions that are dependent
on the Kubernetes version. You can pass these API versions as an argument to the `--api-versions` parameter in the `helm template` command.
This enables you to specify which Kubernetes API versions should be used when rendering your Helm templates.

* __The release kubeVersion__ (optional)

The `kubeVersion` field in the `Capabilities` object signifies the Kubernetes version itself. You can pass this Kubernetes version as argument to the `--kube-version` parameter in the `helm template` command. It specifies the exact Kubernetes version you want to use when rendering your Helm templates.

**Note**: Not all Helm charts contain apiVersions and kubeVersion definitions in their manifests. Make sure that your manifests contain the following code:

```yaml
data:
apiVersions: {{ .Capabilities.ApiVersions }}
kubeVersion: {{ .Capabilities.KubeVersion }}
```

In this example, you have a fully configured **Bake (Manifest)** stage, including the **ApiVersions** and **KubeVersion** fields:

{{< figure src="api-versions.png" >}}

* __The release namespace__ (optional)

The Kubernetes namespace to install release into. If parameter is not
specified default namespace will be used.
The Kubernetes namespace to install release into. If parameter is not specified, Spinnaker uses the default namespace.

> Note: Not all Helm charts contain namespace definitions in their manifests.
> Make sure that your manifests contain the following code:
**Note**: Not all Helm charts contain namespace definitions in their manifests. Make sure that your manifests contain the following code:


```yaml
metadata:
namespace: {{ .Release.Namespace }}
```
```yaml
metadata:
namespace: {{ .Release.Namespace }}
```

* __Helm chart file path__ (optional)

Helm chart file path is only relevant (and visible) when the template artifact
is a git/repo artifact. It specifies the directory path to Chart.yaml in the git repo.
If absent, spinnaker looks for Chart.yaml in the root directory of the git
repo.
Helm chart file path is only relevant (and visible) when the template artifact is a git/repo artifact. It specifies the directory path to Chart.yaml in the git repo. If absent, Spinnaker looks for Chart.yaml in the root directory of the git repo.

Given: A git repo where your `Chart.yaml` is in: `sub/folder/Chart.yml` \
Then: `helmChartFilePath: "sub/folder/"`
Given: A git repo where your `Chart.yaml` is in: `sub/folder/Chart.yml` \
Then: `helmChartFilePath: "sub/folder/"`

> Note: Leading slashes will not work in `helmChartFilePath`.
**Note**: Leading slashes do not work in `helmChartFilePath`.

* __Zero or more override artifacts__ (optional)

The files passed to `--values` parameter in the `helm
template` command. Each is a
remotely stored artifact representing a [Helm Value
File](https://helm.sh/docs/chart_template_guide/values_files/).
The files passed to `--values` parameter in the `helm template` command. Each is a remotely stored artifact representing a [Helm Value File](https://helm.sh/docs/chart_template_guide/values_files/).

* __Statically specified overrides__

The set of static key/value pairs that are passed as `--set` parameters to
the `helm template` command.
The set of static key/value pairs that are passed as `--set` parameters to the `helm template` command.

### Configuration example

As an example, we have a fully configured Bake (Manifest) stage below:
In this example, you have a fully configured **Bake (Manifest)** stage:

{{< figure src="./bake-manifest-stage.png" >}}

Notice that in the "Produces Artifacts" section, Spinnaker has automatically
created an `embedded/base64` artifact that is bound when the stage
completes, representing the fully baked manifest set to be deployed downstream.
Notice that in the **Produces Artifacts** section, Spinnaker has automatically created an `embedded/base64` artifact that is bound when the stage completes, representing the fully baked manifest set to be deployed downstream.

{{< figure src="./produces.png" >}}

If you are programatically generating stages, here is the JSON representation
of the same stage from above:
If you are programatically generating stages, here is the JSON representation of the same stage:

```json
{
Expand Down Expand Up @@ -125,35 +133,31 @@ of the same stage from above:

### Helmfile

In addition to standard helm deployments, Spinnaker supports [Helmfile](https://helmfile.readthedocs.io/) as a templating engine. Current supported version can be found [here](https://github.com/spinnaker/rosco/blob/master/Dockerfile.slim#L7).
In addition to standard Helm deployments, Spinnaker supports [Helmfile](https://helmfile.readthedocs.io/) as a templating engine. You can find the supported version in [Rosco's Dockerfile](https://github.com/spinnaker/rosco/blob/master/Dockerfile.slim#L7).

Configuring a Helmfile deployment follows the specification for standard helm chart deployments (defined above) with one exception - `helmChartFilePath` is substituted for `helmfileFilePath` and is specified as follows:

* __helmfile file path (optional)__

helmfile file path is only relevant (and visible) when the template artifact is a git/repo artifact. It specifies the directory path to helmfile.yaml in the git repo. If absent, spinnaker looks for helmfile.yaml in the root directory of the git repo.

Given: A git repo where your `helmfile.yaml` is in: `sub/folder/helmfile.yml` \
Then: `helmfileFilePath: "sub/folder/"`
`helmfile` file path is only relevant (and visible) when the template artifact is a git/repo artifact. It specifies the directory path to helmfile.yaml in the git repo. If absent, spinnaker looks for helmfile.yaml in the root directory of the git repo.

> Note: Leading slashes will not work in `helmfileFilePath`.
Given: A git repo where your `helmfile.yaml` is in: `sub/folder/helmfile.yml` \
Then: `helmfileFilePath: "sub/folder/"`

Note: Leading slashes do not work in `helmfileFilePath`.

## Configure a downstream deployment

Now that your manifest set has been baked by Helm, configure a downstream stage
(in the same pipeline or in one triggered by this pipeline) your "Deploy
(Manifest)" stage to deploy the artifact produced by the "Bake (Manifest)"
stage as shown here:
(in the same pipeline or in one triggered by this pipeline) your **Deploy (Manifest)** stage to deploy the artifact produced by the **Bake (Manifest)** stage:

{{< figure src="./expected-artifact.png" >}}

> Note: Make sure to select "embedded-artifact" as the artifact account for
> your base64 manifest set. This is required to translate the manifest set into
> the format required by the deploy stage.
When this stage runs, you can see every resource in your Helm chart get
deployed at once:
When this stage runs, you can see every resource in your Helm chart get deployed at once:

{{< figure src="./result.png" >}}

Expand Down
11 changes: 11 additions & 0 deletions content/en/docs/releases/next-release-preview/index.md
View file
Expand Up @@ -10,3 +10,14 @@ in the next release of Spinnaker. These notes will be prepended to the release
changelog.

## Coming Soon in Release 1.33

### Deck

- https://github.com/spinnaker/deck/pull/10036 adds support to deploy different versions of artifacts based on the target cluster API and Kubernetes version, significantly improving the user experience when deploying Helm charts.
- To enable this feature, you must set `API_VERSIONS_ENABLED` to `true` in Deck.

For configuration, see [Deploy Helm Charts]({{< ref "docs/guides/user/kubernetes-v2/deploy-helm" >}}).

Other related PRs are:
https://github.com/spinnaker/orca/pull/4546
https://github.com/spinnaker/rosco/pull/1020

0 comments on commit f467046

Please sign in to comment.