diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index f767c01b96..68479d2ffb 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,6 +18,7 @@ jobs: curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/api/source.md > docs/components/source/api.md curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/spec/v1alpha1/gitrepositories.md > docs/components/source/gitrepositories.md curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/spec/v1alpha1/helmrepositories.md > docs/components/source/helmrepositories.md + curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/spec/v1alpha1/helmcharts.md > docs/components/source/helmcharts.md # kustomize-controller CRDs curl https://raw.githubusercontent.com/fluxcd/kustomize-controller/master/docs/api/kustomize.md > docs/components/kustomize/api.md diff --git a/docs/guides/helmreleases.md b/docs/guides/helmreleases.md new file mode 100644 index 0000000000..63bba6a7f5 --- /dev/null +++ b/docs/guides/helmreleases.md @@ -0,0 +1,94 @@ +# Managing Helm releases + +The [helm-controller](../components/helm/controller.md) allows you to +declaratively manage Helm chart releases with Kubernetes manifests. +It makes use of the artifacts produced by the +[source-controller](../components/source/controller.md) from +`HelmRepository` and `HelmChart` resources. +The helm-controller is part of the default toolkit installation. + +## Prerequisites + +To follow this guide you'll need a Kubernetes cluster with the GitOps +toolkit controllers installed on it. +Please see the [get started guide](../get-started/index.md) +or the [install command docs](../cmd/tk_install.md). + +## Define a Helm repository + +To be able to deploy a Helm chart, the Helm chart repository has to be +known first to the source-controller, so that the `HelmRelease` can +reference to it. + +A cluster administrator should register trusted sources by creating +`HelmRepository` resources in the `gitops-system` namespace. +By default, the source-controller watches for sources only in the +`gitops-system` namespace, this way cluster admins can prevent +untrusted sources from being registered by users. + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: HelmRepository +metadata: + name: podinfo + namespace: gitops-system +spec: + interval: 1m + url: https://stefanprodan.github.io/podinfo +``` + +The `interval` defines at which interval the Helm repository index +is fetched, and should be at least `1m`. Setting this to a higher +value means newer chart versions will be detected at a slower pace, +a push-based fetch can be introduced using [webhook receivers](webhook-receivers.md) + +The `url` can be any HTTP/S Helm repository URL. + +!!! hint "Authentication" + HTTP/S basic and TLS authentication can be configured for private + Helm repositories. See the [`HelmRepository` CRD docs](../components/source/helmrepositories.md) + for more details. + +## Define a Helm release + +With the `HelmRepository` created, define a new `HelmRelease` to deploy +the Helm chart from the repository: + +```yaml +apiVersion: helm.fluxcd.io/v2alpha1 +kind: HelmRelease +metadata: + name: podinfo + namespace: default +spec: + interval: 5m + chart: + name: podinfo + version: '^4.0.0' + sourceRef: + kind: HelmRepository + name: podinfo + namespace: gitops-system + interval: 1m + values: + replicaCount: 2 +``` + +The `chart.name` is the name of the chart as made available by the Helm +repository, and may not include any aliases. + +The `chart.version` can be a fixed semver, or any semver range (i.e. +`>=4.0.0 <4.0.2`). + +The `chart` values are used by the helm-controller as a template to +create a new `HelmChart` resource in the same namespace as the +`sourceRef`. The source-controller will then lookup the chart in the +artifact of the referenced `HelmRepository`, fetch the chart, and make +it available as a `HelmChart` artifact to be used by the +helm-controller. + +!!! Note + The `HelmRelease` offers an extensive set of configurable flags + for finer grain control over how Helm actions are performed. + See the [`HelmRelease` CRD docs](../components/helm/helmreleases.md) + for more details. diff --git a/docs/index.md b/docs/index.md index 2c4e496468..53fda189b8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,6 +39,7 @@ Components: - [Source Controller](components/source/controller.md) - [GitRepository CRD](components/source/gitrepositories.md) - [HelmRepository CRD](components/source/helmrepositories.md) + - [HelmChart CRD](components/source/helmcharts.md) - [Kustomize Controller](components/kustomize/controller.md) - [Kustomization CRD](components/kustomize/kustomization.md) - [Helm Controller](components/helm/controller.md) diff --git a/mkdocs.yml b/mkdocs.yml index a536311cf5..aca3c816a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,7 @@ nav: - Overview: components/source/controller.md - GitRepository CRD: components/source/gitrepositories.md - HelmRepository CRD: components/source/helmrepositories.md + - HelmChart CRD: components/source/helmcharts.md - Source API Reference: components/source/api.md - Kustomize Controller: - Overview: components/kustomize/controller.md