diff --git a/.circleci/config.yml b/.circleci/config.yml index d33ac6539..62ee2ffef 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -66,7 +66,6 @@ jobs: - run: make check-generated - run: make test TEST_FLAGS="-race -timeout 5m" - run: make all - - run: make test-docs - e2e_tests: helm_version: v2 - e2e_tests: diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 1cdb25548..c68fbd1c0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Create a report to help us improve the Flux Helm operator +about: Create a report to help us improve the Helm Operator title: '' labels: blocked needs validation, bug assignees: '' @@ -14,7 +14,7 @@ A clear and concise description of what the bug is. **To Reproduce** Steps to reproduce the behaviour: -1. Provide the Helm operator install instructions +1. Provide the Helm Operator install instructions 2. Provide a HelmRelease example 3. Post the HelmRelease status, you can get this by running `kubectl describe helmrelease ` @@ -28,7 +28,7 @@ If applicable, please provide logs. In a standard stand-alone installation, you' **Additional context** -- Helm operator version: +- Helm Operator version: - Kubernetes version: - Git provider: - Helm repository provider: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 0294ff903..ca546a261 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Suggest a new feature for the Flux Helm operator +about: Suggest a new feature for the Helm Operator title: '' labels: blocked needs validation, enhancement assignees: '' @@ -11,7 +11,7 @@ assignees: '' A clear and concise description of the feature. **What would the new user story look like?** -How would the new interaction with the Flux Helm operator look like? E.g. +How would the new interaction with the Helm Operator look like? E.g. 0. What are the prerequisites for this? 1. User starts up the operator using the --add-frobnication flag 2. A new `HelmRelease` is applied diff --git a/.github/ISSUE_TEMPLATE/helm_v3_bug_report.md b/.github/ISSUE_TEMPLATE/helm_v3_bug_report.md index 93d8b4645..44c0be8bd 100644 --- a/.github/ISSUE_TEMPLATE/helm_v3_bug_report.md +++ b/.github/ISSUE_TEMPLATE/helm_v3_bug_report.md @@ -1,6 +1,6 @@ --- name: Helm v3 bug report -about: Create a bug report for Flux Helm operator with Helm v3 +about: Create a bug report for Helm Operator with Helm v3 title: '' labels: blocked needs validation, bug, helm-v3 assignees: '' @@ -26,7 +26,7 @@ If applicable, please provide logs. In a standard stand-alone installation, you' **Additional context** Add any other context about the problem here, e.g -- Helm operator version: +- Helm Operator version: - Targeted Helm version: - Kubernetes version: - Git provider: diff --git a/.github/workflows/check-links.yaml b/.github/workflows/check-links.yaml new file mode 100644 index 000000000..5638aaf2f --- /dev/null +++ b/.github/workflows/check-links.yaml @@ -0,0 +1,27 @@ +on: [push, pull_request] +name: Check links +jobs: + linkChecker: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: [3.8] + steps: + - uses: actions/checkout@v2 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v1 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + - name: Build docs for link check + run: mkdocs build + - name: Link Checker + id: lc + uses: peter-evans/link-checker@v1 + with: + args: -r -d site/ -v site/index.html + - name: Fail if there were link errors + run: exit ${{ steps.lc.outputs.exit_code }} diff --git a/.gitignore b/.gitignore index de8ae5c74..e81b0a9a1 100644 --- a/.gitignore +++ b/.gitignore @@ -52,4 +52,4 @@ test/bin/ test/e2e/bats # Docs -docs/_build +site/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 39d81bd05..7ebc12432 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,13 +4,9 @@ # Required version: 2 -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: docs/conf.py - # Build documentation with MkDocs -#mkdocs: -# configuration: mkdocs.yml +mkdocs: + configuration: mkdocs.yml # Optionally build your docs in additional formats such as PDF and ePub formats: all diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a7af150a..e2885ef84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). > **Notice:** due to the multiple added fields, you need to > re-apply the `HelmRelease` CRD. @@ -86,7 +86,7 @@ release, feedback, and reporting issues. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). > **Notice:** due to the multiple added fields, you need to > re-apply the `HelmRelease` CRD. @@ -179,7 +179,7 @@ this release, feedback, and reporting issues. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). ### Bug fixes @@ -221,7 +221,7 @@ to this release, feedback, and reporting issues. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). This release fixes some (but not all) of the more critical bugs reported since Helm v3 was introduced in the last release. @@ -265,7 +265,7 @@ issues. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). > **Notice:** due to the added `helmVersion` field, you need > to re-apply the `HelmRelease` CRD. @@ -347,7 +347,7 @@ v3 support, notably @gsf, @dminca, @rowecharles, @eschereisin, > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). ### Improvements @@ -379,7 +379,7 @@ and @stefanprodan for contributions to this release. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). This is the third release candidate. @@ -412,7 +412,7 @@ for contributions to this release. > **Notice:** upgrading to this version from `<=0.10.x` by just > updating your Helm Operator image tag is not possible as the > CRD domain and version have changed. An upgrade guide can be -> found [here](./docs/guides/upgrading-to-ga.md). +> found [here](./docs/how-to/upgrading-to-ga.md). This is the second release candidate. @@ -467,7 +467,7 @@ for contributions to this release. > **Notice:** upgrading to this version by just updating your Helm > Operator image tag is not possible as the CRD domain and version -> have changed. An upgrade guide can be found [here](./docs/guides/upgrading-to-ga.md). +> have changed. An upgrade guide can be found [here](./docs/how-to/upgrading-to-ga.md). This is the first `1.0.0` release candidate, there is no rule about the amount of published release candidates before it is officially diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0dfcfaa30..c4723a9ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # How to Contribute -The Flux Helm operator is [Apache 2.0 licensed](LICENSE) and accepts contributions +The Helm Operator is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub pull requests. This document outlines some of the conventions on development workflow, commit message formatting, contact points and other resources to make it easier to get your contribution accepted. diff --git a/Makefile b/Makefile index 17d5234b4..fb7644a58 100644 --- a/Makefile +++ b/Makefile @@ -32,8 +32,6 @@ IMAGE_TAG:=$(shell ./docker/image-tag) VCS_REF:=$(shell git rev-parse HEAD) BUILD_DATE:=$(shell date -u +'%Y-%m-%dT%H:%M:%SZ') -DOCS_PORT:=8000 - all: $(GOBIN)/bin/helm-operator build/.helm-operator.done clean: @@ -150,13 +148,3 @@ generate-deploy: generate-crds pkg/install/generated_templates.gogen.go check-generated: generate-deploy pkg/install/generated_templates.gogen.go git diff --exit-code -- pkg/install/generated_templates.gogen.go ./hack/update/verify.sh - -build-docs: - @cd docs && docker build -t flux-docs . - -test-docs: build-docs - @docker run -it flux-docs /usr/bin/linkchecker _build/html/index.html - -serve-docs: build-docs - @echo Stating docs website on http://localhost:${DOCS_PORT}/_build/html/index.html - @docker run -i -p ${DOCS_PORT}:8000 -e USER_ID=$$UID flux-docs diff --git a/README.md b/README.md index 92e256878..559394b01 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,17 @@ [![GoDoc](https://godoc.org/github.com/fluxcd/helm-operator?status.svg)](https://godoc.org/github.com/fluxcd/helm-operator) [![Documentation](https://img.shields.io/badge/latest-documentation-informational)](https://docs.fluxcd.io/projects/helm-operator/en/latest/) -The Helm operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), +The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), allowing one to declaratively manage Helm chart releases. Combined with -[Flux](https://github.com/fluxcd/flux) this can be utilized to automate -releases in a GitOps manner, but the usage of Flux is not a strict -requirement. +[Flux](https://github.com/fluxcd/flux) it can to automate releases in a +GitOps manner, but the use of Flux is not a strict requirement. The desired state of a Helm release is described through a Kubernetes Custom Resource named `HelmRelease`. Based on the creation, mutation or removal of a `HelmRelease` resource in the cluster, Helm actions are performed by the operator. -![GitOps Helm Operator](docs/_files/fluxcd-helm-operator-diagram.png) +![Helm Operator](docs/_files/fluxcd-helm-operator-diagram.png) ## Helm Operator features @@ -31,7 +30,7 @@ performed by the operator. or a (local) URL * Automated purging on release install failures * Automated (optional) rollback on upgrade failures -* Automated image upgrades [using Flux](https://docs.fluxcd.io/en/latest/references/helm-operator-integration.html) +* Automated image upgrades [using Flux](https://docs.fluxcd.io/en/stable/references/helm-operator-integration.html) * Automated (configurable) chart dependency updates for Helm charts from Git sources on install or upgrade * Detection and recovery from Helm storage mutations @@ -43,25 +42,26 @@ performed by the operator. ## Get started with the Helm Operator -Get started [installing the Helm operator](/chart/helm-operator/README.md) -or just [browse through the documentation](https://docs.fluxcd.io/projects/helm-operator/en/latest/). +Get started [installing the Helm Operator](/chart/helm-operator/README.md) +or just [browse through the documentation](https://docs.fluxcd.io/projects/helm-operator/en/stable/). ### Integrations -As Flux Helm Operator is Open Source, integrations are very straight-forward. Here are -a few popular ones you might want to check out: +As the Helm Operator is Open Source, integrations are very straight-forward. Here +are a few popular ones you might want to check out: -- [Progressive Delivery workshop (Helm v3 alpha)](https://helm.workshop.flagger.dev/) +- [Progressive Delivery workshop](https://helm.workshop.flagger.dev/) - [Managing Helm releases the GitOps way](https://github.com/fluxcd/helm-operator-get-started) - [GitOps for Istio Canary deployments](https://github.com/stefanprodan/gitops-istio) ## Community & Developer information -We welcome all kinds of contributions to Helm Operator, be it code, issues you found, -documentation, external tools, help and support or anything else really. +We welcome all kinds of contributions to the Helm Operator, be it code, issues +you found, documentation, external tools, help and support or anything else +really. -The FluxCD projects adheres to the [CNCF Code of -Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). +The Helm Operator and other projects in the FluxCD umbrella adhere to the [CNCF +Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a _Flux_ project maintainer, or the CNCF @@ -71,17 +71,17 @@ To familiarise yourself with the project and how things work, you might be interested in the following: - [Our contributions guidelines](CONTRIBUTING.md) -- [Build documentation](https://docs.fluxcd.io/en/latest/contributing/building.html) +- [Build documentation](https://docs.fluxcd.io/en/stable/contributing/building.html) - [Release documentation](/internal_docs/releasing.md) ## Getting Help -If you have any questions about Helm Operator and continuous delivery: +If you have any questions about the Helm Operator and continuous delivery: - Read [the Helm Operator docs](https://docs.fluxcd.io/projects/helm-operator/). -- Invite yourself to the CNCF community - slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/) - channel. +- Invite yourself to the CNCF + community slack and ask a question on the + [#flux](https://cloud-native.slack.com/messages/flux/) channel. - To be part of the conversation about Helm Operator's development, join the [flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev). - [File an issue.](https://github.com/fluxcd/helm-operator/issues/new) diff --git a/chart/helm-operator/README.md b/chart/helm-operator/README.md index af5cb9f67..bdb24103e 100755 --- a/chart/helm-operator/README.md +++ b/chart/helm-operator/README.md @@ -1,127 +1,216 @@ -# Flux Helm Operator +# Helm Operator chart -This chart bootstraps Flux [Helm Operator](https://github.com/fluxcd/helm-operator) on -a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. +The [Helm operator chart](https://github.com/fluxcd/helm-operator/tree/master/chart/helm-operator) +bootstraps the Helm Operator on a [Kubernetes](http://kubernetes.io) cluster +using the [Helm](https://helm.sh) package manager. ## Prerequisites -* Kubernetes >= v1.11 +* Kubernetes **>=v1.13** ## Installation -Add the fluxcd repo: +Add the Flux CD Helm repository: ```sh helm repo add fluxcd https://charts.fluxcd.io ``` -Install the HelmRelease CRD: +Install the `HelmRelease` Custom Resource Definition. By adding this +CRD it will be possible to define `HelmRelease` resources on the +cluster: ```sh -kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/master/deploy/crds.yaml +kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/crds.yaml ``` -Install Helm Operator for Tiller in the fluxcd namespace: +Install the Helm operator using the chart: -```sh +```sh tab="Default (Helm 2 and 3)" +# Default with support for Helm 2 and 3 enabled +# NB: the presence of Tiller is a requirement when +# Helm 2 is enabled. helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd + --namespace flux ``` -Install Helm Operator for Helm v3 only: +```sh tab="Helm 3" +# Only Helm 3 support enabled using helm.versions +helm upgrade -i helm-operator fluxcd/helm-operator \ + --namespace flux \ + --set helm.versions=v3 +``` -```sh +```sh tab="Helm 2" +# Only Helm 2 support enabled using helm.versions +# NB: the presence of Tiller is a requirement when +# Helm 2 is enabled. helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd \ ---set helm.versions=v3 + --namespace flux \ + --set helm.versions=v2 ``` -By default the `helm.versions` is set to `v2,v3`, in this mode Tiller is required. +## Configuration + +The following tables lists the configurable parameters of the Helm Operator +chart and their default values. + +| Parameter | Default | Description +| ----------------------------------------------- | ---------------------------------------------------- | --- +| `image.repository` | `docker.io/fluxcd/helm-operator` | Image repository +| `image.tag` | `{{ version }}` | Image tag +| `replicaCount` | `1` | Number of Helm Operator pods to deploy, more than one is not desirable. +| `image.pullPolicy` | `IfNotPresent` | Image pull policy +| `image.pullSecret` | `None` | Image pull secret +| `resources.requests.cpu` | `50m` | CPU resource requests for the deployment +| `resources.requests.memory` | `64Mi` | Memory resource requests for the deployment +| `resources.limits` | `None` | CPU/memory resource limits for the deployment +| `nodeSelector` | `{}` | Node Selector properties for the deployment +| `tolerations` | `[]` | Tolerations properties for the deployment +| `affinity` | `{}` | Affinity properties for the deployment +| `extraEnvs` | `[]` | Extra environment variables for the Helm Operator pod(s) +| `podAnnotations` | `{}` | Additional pod annotations +| `podLabels` | `{}` | Additional pod labels +| `rbac.create` | `true` | If `true`, create and use RBAC resources +| `rbac.pspEnabled` | `false` | If `true`, create and use a restricted pod security policy for Helm Operator pod(s) +| `serviceAccount.create` | `true` | If `true`, create a new service account +| `serviceAccount.annotations` | `{}` | Additional Service Account annotations +| `serviceAccount.name` | `flux` | Service account to be used +| `clusterRole.create` | `true` | If `false`, Helm Operator will be restricted to the namespace where is deployed +| `createCRD` | `false` | Create the HelmRelease CRD +| `service.type` | `ClusterIP` | Service type to be used (exposing the Helm Operator API outside of the cluster is not advised) +| `service.port` | `3030` | Service port to be used +| `updateChartDeps` | `true` | Update dependencies for charts +| `git.pollInterval` | `git.pollInterval` | Period on which to poll git chart sources for changes +| `git.timeout` | `git.timeout` | Duration after which git operations time out +| `git.defaultRef` | `master` | Ref to clone chart from if ref is unspecified in a HelmRelease +| `git.ssh.secretName` | `None` | The name of the kubernetes secret with the SSH private key, supercedes `git.secretName` +| `git.ssh.known_hosts` | `None` | The contents of an SSH `known_hosts` file, if you need to supply host key(s) +| `git.ssh.configMapName` | `None` | The name of a kubernetes config map containing the ssh config +| `git.ssh.configMapKey` | `config` | The name of the key in the kubernetes config map specified above +| `chartsSyncInterval` | `3m` | Period on which to reconcile the Helm releases with `HelmRelease` resources +| `statusUpdateInterval` | `None` | Period on which to update the Helm release status in `HelmRelease` resources +| `workers` | `None` | Number of workers processing releases +| `logFormat` | `fmt` | Log format (fmt or json) +| `logReleaseDiffs` | `false` | Helm Operator should log the diff when a chart release diverges (possibly insecure) +| `allowNamespace` | `None` | If set, this limits the scope to a single namespace. If not specified, all namespaces will be watched +| `helm.versions` | `v2,v3` | Helm versions supported by this operator instance, if v2 is specified then Tiller is required +| `tillerNamespace` | `kube-system` | Namespace in which the Tiller server can be found +| `tillerSidecar.enabled` | `false` | Whether to deploy Tiller as a sidecar (and listening on `localhost` only). +| `tillerSidecar.image.repository` | `gcr.io/kubernetes-helm/tiller` | Image repository to use for the Tiller sidecar. +| `tillerSidecar.image.tag` | `v2.16.1` | Image tag to use for the Tiller sidecar. +| `tillerSidecar.storage` | `secret` | Storage engine to use for the Tiller sidecar. +| `tls.enable` | `false` | Enable TLS for communicating with Tiller +| `tls.verify` | `false` | Verify the Tiller certificate, also enables TLS when set to true +| `tls.secretName` | `helm-client-certs` | Name of the secret containing the TLS client certificates for communicating with Tiller +| `tls.keyFile` | `tls.key` | Name of the key file within the k8s secret +| `tls.certFile` | `tls.crt` | Name of the certificate file within the k8s secret +| `tls.caContent` | `None` | Certificate Authority content used to validate the Tiller server certificate +| `tls.hostname` | `None` | The server name used to verify the hostname on the returned certificates from the Tiller server +| `configureRepositories.enable` | `false` | Enable volume mount for a `repositories.yaml` configuration file and repository cache +| `configureRepositories.volumeName` | `repositories-yaml` | Name of the volume for the `repositories.yaml` file +| `configureRepositories.secretName` | `flux-helm-repositories` | Name of the secret containing the contents of the `repositories.yaml` file +| `configureRepositories.cacheName` | `repositories-cache` | Name for the repository cache volume +| `configureRepositories.repositories` | `None` | List of custom Helm repositories to add. If non empty, the corresponding secret with a `repositories.yaml` will be created +| `initPlugins.enable` | `false` | Enable the initialization of Helm plugins using init containers +| `initPlugins.cacheVolumeName` | `plugins-cache` | Name for the plugins cache volume +| `initPlugins.plugins` | `None` | List of Helm plugins to initialize before starting the operator. If non empty, an init container will be added for every entry. +| `kube.config` | `None` | Override for kubectl default config in the Helm Operator pod(s). +| `prometheus.enabled` | `false` | If enabled, adds prometheus annotations to Helm Operator pod(s) +| `prometheus.serviceMonitor.create` | `false` | Set to true if using the Prometheus Operator +| `prometheus.serviceMonitor.interval` | `None` | Interval at which metrics should be scraped +| `prometheus.serviceMonitor.namespace` | `None` | The namespace where the ServiceMonitor is deployed +| `prometheus.serviceMonitor.additionalLabels` | `{}` | Additional labels to add to the ServiceMonitor +| `initContainers` | `[]` | Init containers and their specs +| `hostAliases` | `{}` | Host aliases allow the modification of the hosts file (`/etc/hosts`) inside Helm Operator container. See + +## How-to + +### Use a custom Helm repository + +Public Helm chart repositories that do not require any authentication do +not have to be configured and can just be referenced by their URL in a +`HelmRelease` resource. However, for Helm chart repositories that do +require authentication repository entries with the credentials need to be +added so the Helm Operator is able to authenticate against the repository. + +Helm chart repository entries can be added with the chart using the +`configureRepositories.repositories` value, which accepts an array +of objects with the following keys: + +| Key | Description +|-----|------------ +| `name` | The name (alias) for the Helm chart repository +| `url` | The URL of the Helm chart repository +| `username` | Helm chart repository username +| `password` | Helm chart repository password +| `certFile` | The path to a SSL certificate file used to identify the HTTPS client +| `keyFile` | The path to a SSL key file used to identify the HTTPS client +| `caFile` | The path to a CA bundle used to verify HTTPS enabled servers -## Use a custom Helm repository +--- -You can add Helm repositories using the `configureRepositories` settings: +For example, to add an Helm chart repository with username and password +protection: ```sh helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd \ ---set configureRepositories.enable=true \ ---set 'configureRepositories.repositories[0].name=stable' \ ---set 'configureRepositories.repositories[0].url=https://kubernetes-charts.storage.googleapis.com' \ ---set 'configureRepositories.repositories[1].name=podinfo' \ ---set 'configureRepositories.repositories[1].url=https://stefanprodan.github.io/podinfo' + --namespace flux \ + --set configureRepositories.enable=true \ + --set 'configureRepositories.repositories[0].name='example' \ + --set 'configureRepositories.repositories[0].url='https://charts.example.com' \ + --set 'configureRepositories.repositories[0].username='john' \ + --set 'configureRepositories.repositories[0].password='s3cr3t!' ``` -Install podinfo by referring to its Helm repository: +After adding the entry, the Helm chart in the repository can then be referred +to by the URL of the repository as usual: -```sh -cat < +ssh-keyscan > /tmp/flux_known_hosts ``` -* Copy the known hosts keys into a temporary file `/tmp/flux_known_hosts`. - -* Generate a SSH key named `identity` and create a secret with it: +Generate a SSH key named `identity` and create a secret with it: ```sh ssh-keygen -q -N "" -f /tmp/identity -kubectl -n fluxcd create secret generic helm-operator-ssh --from-file=/tmp/identity +kubectl create secret generic helm-operator-ssh \ + --from-file=/tmp/identity + --namespace flux ``` -Add `identity.pub` as a read-only deployment key in your Git repo and install Helm Operator: +Add `identity.pub` as a read-only deployment key in your Git repo and install +the Helm Operator: ```sh helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd \ ---set git.ssh.secretName=helm-operator-ssh \ ---set-file git.ssh.known_hosts=/tmp/flux_known_hosts +--namespace flux \ + --set git.ssh.secretName=helm-operator-ssh \ + --set-file git.ssh.known_hosts=/tmp/flux_known_hosts ``` You can refer to a chart from your private Git with: @@ -142,29 +231,31 @@ spec: replicaCount: 1 ``` -## Use Flux's Git deploy key +### Use Flux's Git deploy key -You can configure the Helm Operator to use the Git SSH key generated by Flux. +You can configure the Helm Operator to use the Git SSH key generated by +[Flux](https://github.com/fluxcd/flux). -Assuming you've installed Flux with: +Assuming you have installed Flux with: ```sh helm upgrade -i flux fluxcd/flux \ ---namespace fluxcd \ ---set git.url=git@github.com:org/repo + --namespace flux \ + --set git.url=git@github.com:org/repo ``` -when installing Helm Operator, you can refer the Flux deploy key by its Kubernetes Secret name: +When installing Helm Operator, you can refer to the Flux deploy key by the name +of the Kubernetes Secret: ```sh helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd \ ---set git.ssh.secretName=flux-git-deploy + --namespace flux \ + --set git.ssh.secretName=flux-git-deploy ``` The deploy key naming convention is `-git-deploy`. -## Use Helm downloader plugins +### Use Helm downloader plugins Helm downloader plugins like [`hypnoglow/helm-s3`](https://github.com/hypnoglow/helm-s3) and [`hayorov/helm-gcs`](https://github.com/hayorov/helm-gcs) make it possible @@ -175,16 +266,16 @@ using init containers: ```sh helm upgrade -i helm-operator fluxcd/helm-operator \ ---namespace fluxcd \ ---set initPlugins.enable=true \ ---set 'initPlugins.plugins[0].plugin=https://github.com/hypnoglow/helm-s3.git' \ ---set 'initPlugins.plugins[0].version=0.9.2' \ ---set 'initPlugins.plugins[0].helmVersion=v3' \ + --namespace flux \ + --set initPlugins.enable=true \ + --set 'initPlugins.plugins[0].plugin=https://github.com/hypnoglow/helm-s3.git' \ + --set 'initPlugins.plugins[0].version=0.9.2' \ + --set 'initPlugins.plugins[0].helmVersion=v3' ``` -> **Note:** most plugins assume credentials are available on the system they run on, -> make sure those are available at the expected paths using e.g. `extraVolumes` and -> `extraVolumeMounts`. +> **Note:** Most plugins assume credentials are available on the system they +> run on, make sure those are available at the expected paths using e.g. +> `extraVolumes` and `extraVolumeMounts`. You should now be able to make use of the protocol added by the plugin: @@ -205,88 +296,16 @@ spec: EOF ``` -## Uninstall +### Uninstall -To uninstall/delete the `helm-operator` deployment: +To uninstall/delete the `helm-operator` Helm release: ```sh helm delete --purge helm-operator ``` -The command removes all the Kubernetes components associated with the chart and deletes the release. - -Note that `helm delete` will not remove the `HelmRelease` CRD. -Deleting the CRD will trigger a cascade delete of all Helm release objects. - -## Configuration +The command removes all the Kubernetes components associated with the chart and +deletes the release. -The following tables lists the configurable parameters of the Flux chart and their default values. - -| Parameter | Default | Description -| ----------------------------------------------- | ---------------------------------------------------- | --- -| `image.repository` | `docker.io/fluxcd/helm-operator` | Image repository -| `image.tag` | `` | Image tag -| `replicaCount` | `1` | Number of Helm Operator pods to deploy, more than one is not desirable. -| `image.pullPolicy` | `IfNotPresent` | Image pull policy -| `image.pullSecret` | `None` | Image pull secret -| `resources.requests.cpu` | `50m` | CPU resource requests for the deployment -| `resources.requests.memory` | `64Mi` | Memory resource requests for the deployment -| `resources.limits` | `None` | CPU/memory resource limits for the deployment -| `nodeSelector` | `{}` | Node Selector properties for the deployment -| `tolerations` | `[]` | Tolerations properties for the deployment -| `affinity` | `{}` | Affinity properties for the deployment -| `extraEnvs` | `[]` | Extra environment variables for the Helm Operator pod(s) -| `podAnnotations` | `{}` | Additional pod annotations -| `podLabels` | `{}` | Additional pod labels -| `rbac.create` | `true` | If `true`, create and use RBAC resources -| `rbac.pspEnabled` | `false` | If `true`, create and use a restricted pod security policy for Helm Operator pod(s) -| `serviceAccount.create` | `true` | If `true`, create a new service account -| `serviceAccount.annotations` | `` | Additional Service Account annotations -| `serviceAccount.name` | `flux` | Service account to be used -| `clusterRole.create` | `true` | If `false`, Helm Operator will be restricted to the namespace where is deployed -| `createCRD` | `false` | Create the HelmRelease CRD -| `service.type` | `ClusterIP` | Service type to be used (exposing the Helm operator API outside of the cluster is not advised) -| `service.port` | `3030` | Service port to be used -| `updateChartDeps` | `true` | Update dependencies for charts -| `git.pollInterval` | `git.pollInterval` | Period on which to poll git chart sources for changes -| `git.timeout` | `git.timeout` | Duration after which git operations time out -| `git.defaultRef` | `master` | Ref to clone chart from if ref is unspecified in a HelmRelease -| `git.ssh.secretName` | `None` | The name of the kubernetes secret with the SSH private key, supercedes `git.secretName` -| `git.ssh.known_hosts` | `None` | The contents of an SSH `known_hosts` file, if you need to supply host key(s) -| `git.ssh.configMapName` | `None` | The name of a kubernetes config map containing the ssh config -| `git.ssh.configMapKey` | `config` | The name of the key in the kubernetes config map specified above -| `chartsSyncInterval` | `3m` | Period on which to reconcile the Helm releases with `HelmRelease` resources -| `statusUpdateInterval` | `None` | Period on which to update the Helm release status in `HelmRelease` resources -| `workers` | `None` | Amount of workers processing releases -| `logFormat` | `fmt` | Log format (fmt or json) -| `logReleaseDiffs` | `false` | Helm operator should log the diff when a chart release diverges (possibly insecure) -| `allowNamespace` | `None` | If set, this limits the scope to a single namespace. If not specified, all namespaces will be watched -| `helm.versions` | `v2,v3` | Helm versions supported by this operator instance, if v2 is specified then Tiller is required -| `tillerNamespace` | `kube-system` | Namespace in which the Tiller server can be found -| `tillerSidecar.enabled` | `false` | Whether to deploy Tiller as a sidecar (and listening on `localhost` only). -| `tillerSidecar.image.repository` | `gcr.io/kubernetes-helm/tiller` | Image repository to use for the Tiller sidecar. -| `tillerSidecar.image.tag` | `v2.16.1` | Image tag to use for the Tiller sidecar. -| `tillerSidecar.storage` | `secret` | Storage engine to use for the Tiller sidecar. -| `tls.enable` | `false` | Enable TLS for communicating with Tiller -| `tls.verify` | `false` | Verify the Tiller certificate, also enables TLS when set to true -| `tls.secretName` | `helm-client-certs` | Name of the secret containing the TLS client certificates for communicating with Tiller -| `tls.keyFile` | `tls.key` | Name of the key file within the k8s secret -| `tls.certFile` | `tls.crt` | Name of the certificate file within the k8s secret -| `tls.caContent` | `None` | Certificate Authority content used to validate the Tiller server certificate -| `tls.hostname` | `None` | The server name used to verify the hostname on the returned certificates from the Tiller server -| `configureRepositories.enable` | `false` | Enable volume mount for a `repositories.yaml` configuration file and repository cache -| `configureRepositories.volumeName` | `repositories-yaml` | Name of the volume for the `repositories.yaml` file -| `configureRepositories.secretName` | `flux-helm-repositories` | Name of the secret containing the contents of the `repositories.yaml` file -| `configureRepositories.cacheName` | `repositories-cache` | Name for the repository cache volume -| `configureRepositories.repositories` | `None` | List of custom Helm repositories to add. If non empty, the corresponding secret with a `repositories.yaml` will be created -| `initPlugins.enable` | `false` | Enable the initialization of Helm plugins using init containers -| `initPlugins.cacheVolumeName` | `plugins-cache` | Name for the plugins cache volume -| `initPlugins.plugins` | `None` | List of Helm plugins to initialize before starting the operator. If non empty, an init container will be added for every entry. -| `kube.config` | `None` | Override for kubectl default config in the Helm Operator pod(s). -| `prometheus.enabled` | `false` | If enabled, adds prometheus annotations to Helm Operator pod(s) -| `prometheus.serviceMonitor.create` | `false` | Set to true if using the Prometheus Operator -| `prometheus.serviceMonitor.interval` | `` | Interval at which metrics should be scraped -| `prometheus.serviceMonitor.namespace` | `` | The namespace where the ServiceMonitor is deployed -| `prometheus.serviceMonitor.additionalLabels` | `{}` | Additional labels to add to the ServiceMonitor -| `initContainers` | `[]` | Init containers and their specs -| `hostAliases` | `{}` | Host aliases allow the modification of the hosts file (/etc/hosts) inside Helm Operator container. See +> **Note:** `helm delete` will not remove the `HelmRelease` CRD. +> Deleting the CRD will trigger a cascade delete of all Helm release objects. diff --git a/deploy/deployment.yaml b/deploy/deployment.yaml index 1fd1c19ac..098fb2146 100644 --- a/deploy/deployment.yaml +++ b/deploy/deployment.yaml @@ -22,26 +22,28 @@ spec: volumes: # # You will need these two volumes if you want to establish validated TLS - # connections against Tiller + # connections against Tiller. # - # - name: helm-tls-ca + # - name: tiller-tls-ca # configMap: - # name: flux-helm-tls-ca-config + # name: tiller-tls-ca-config # defaultMode: 0600 - # Secret type kubernetes.io/tls - # - name: flux-helm-tls-cert + # + # Secret of type `kubernetes.io/tls`: + # + # - name: tiller-tls-cert # secret: # secretName: tiller-tls-cert # defaultMode: 0400 # - # The following volume is for using a customised known_hosts file, - # which you will need to do if you host your own git repo rather - # than using github or the like. You'll also need to mount it + # The following volume is for using a customised `known_hosts` file, + # which you will need to do if you host your own git repository rather + # than using GitHub or the like. You will also need to mount it # into the container, below. # - # You may also wish to provide an ssh_config file, - # mentioning more than one `IdentityFile`; for instance, if you're - # using more than one GitHub repo. NB the entry key should be + # You may also wish to provide an `ssh_config` file, + # mentioning more than one `IdentityFile`; for instance, if you are + # using more than one GitHub repository. NB: the entry key should be # "config" rather than "ssh_config" if mounted in ~/.ssh/. # # - name: sshdir @@ -49,12 +51,12 @@ spec: # name: flux-ssh-config # defaultMode: 0400 # - # You will need this volume if you're using a git repo that + # You will need this volume if you are using a git repository that # needs an SSH key for access; e.g., a GitHub deploy key. If - # you're using just one such repo, the default ssh_config - # already points at /etc/fluxd/ssh/identity as a key. If you - # want to use more than one key, you'll need to provide your own - # ssh_config above, with an `IdentityFile` entry matching each + # you are using just one such repository, the default `ssh_config` + # already points at `/etc/fluxd/ssh/identity` as a key. If you + # want to use more than one key, you will need to provide your own + # `ssh_config` above, with an `IdentityFile` entry matching each # key in the secret mentioned here. # # - name: git-key @@ -62,20 +64,19 @@ spec: # secretName: flux-git-deploy # defaultMode: 0400 # when mounted read-only, we won't be able to chmod # - # These two volumes are for mounting a repositories.yaml file, - # and providing a cache directory. The latter is needed because - # mounting the former will make the cache/ directory read-only. + # You will need this volume to import any custom Helm repositories + # and their credentials and/or certificate configurations. You will also + # need to mount it into the container and set the `--helm-repository-import` + # argument, below. # # - name: repositories-yaml # secret: # secretName: flux-helm-repositories - # - name: repositories-cache - # emptyDir: {} - + # defaultMode: 0400 containers: - name: helm-operator # There are no ":latest" images for helm-operator. Find the most recent - # release or image version at https://hub.docker.com/r/weaveworks/helm-operator/tags + # release or image version at https://hub.docker.com/r/fluxcd/helm-operator/tags # and replace the tag here. image: docker.io/fluxcd/helm-operator:1.0.0-rc9 imagePullPolicy: IfNotPresent @@ -99,31 +100,59 @@ spec: cpu: 50m memory: 64Mi volumeMounts: - # Include this if you need to mount a customised known_hosts or ssh_config - # file; you'll also need the volume declared above. + # + # Include this if you need to mount a customised `known_hosts` or `ssh_config` + # file; you will also need the `sshdir` volume above. + # # - name: sshdir # mountPath: /root/.ssh # readOnly: true + # + # Include this if you are using a git repository that needs an SSH + # private key for access; you will also need the `git-key` volume above. + # # - name: git-key # mountPath: /etc/fluxd/ssh + # + # Include this if you want to import any Helm repositories and their + # credentials and/or certificate configurations; you will also need the + # `repositories-yaml` volume above, and the `--helm-repository-import` + # argument below. + # # - name: repositories-yaml - # mountPath: /var/fluxd/helm/repository - # - name: repositories-cache - # mountPath: /var/fluxd/helm/repository/cache - # - name: helm-tls-certs + # mountPath: /root/.helm/repository/repositories.yaml + # + # Include these if you want to establish validated TLS connections + # against Tiller; you will also need the `tiller-tls-cert` and + # `tiller-tls-ca` volumes declared above, and the `--tiller-tls-*` + # arguments below. + # + # - name: tiller-tls-cert # mountPath: /etc/fluxd/helm # readOnly: true - # - name: helm-tls-ca + # - name: tiller-tls-ca # mountPath: /etc/fluxd/helm-ca # readOnly: true args: - # How to find Tiller + # In what namespace Tiller can be found. - --tiller-namespace=kube-system - # Comment out to to establish validated TLS connections against Tiller + # + # Comment out to to establish validated TLS connections against Tiller. + # # - --tiller-tls-ca-cert-path=/etc/fluxd/helm-ca/ca.crt # - --tiller-tls-enable=true # - --tiller-tls-key-path=/etc/fluxd/helm/tls.key # - --tiller-tls-cert-path=/etc/fluxd/helm/tls.crt # - --tiller-tls-verify=true # - --tiller-tls-ca-cert-path=/etc/fluxd/helm-ca/ca.crt - + # + # Include this if you want to import any Helm repositories and their + # credential and/or certificate configurations; you will also need the + # `repositories-yaml` volume and volume mount, above. + # + # - --helm-repository-import=v2:/root/.helm/repository/repositories.yaml,v3:/root/.helm/repository/repositories.yaml + # + # Comment out to enable a single Helm version that can be targeted + # by a `HelmRelease`; defaults to `--enabled-helm-versions=v2,v3`. + # + # - --enabled-helm-versions=v3 diff --git a/docker/Dockerfile.helm-operator b/docker/Dockerfile.helm-operator index f73ece87d..bf55529db 100644 --- a/docker/Dockerfile.helm-operator +++ b/docker/Dockerfile.helm-operator @@ -20,13 +20,13 @@ COPY ./helm3 /usr/local/bin/ # These are pretty static LABEL maintainer="Flux CD " \ - org.opencontainers.image.title="flux-helm-operator" \ + org.opencontainers.image.title="helm-operator" \ org.opencontainers.image.description="The Helm operator for Kubernetes" \ org.opencontainers.image.url="https://github.com/fluxcd/helm-operator" \ org.opencontainers.image.source="git@github.com:fluxcd/helm-operator" \ org.opencontainers.image.vendor="Flux CD" \ org.label-schema.schema-version="1.0" \ - org.label-schema.name="flux-helm-operator" \ + org.label-schema.name="helm-operator" \ org.label-schema.description="The Helm operator for Kubernetes" \ org.label-schema.url="https://github.com/fluxcd/helm-operator" \ org.label-schema.vcs-url="git@github.com:fluxcd/helm-operator" \ diff --git a/docs/Dockerfile b/docs/Dockerfile deleted file mode 100644 index dab83daaa..000000000 --- a/docs/Dockerfile +++ /dev/null @@ -1,17 +0,0 @@ -FROM ddidier/sphinx-doc - -COPY requirements.txt . - -RUN apt update && apt install -y linkchecker && \ - pip install -r requirements.txt - -WORKDIR /doc - -COPY . . - -RUN make html && \ - cd /doc/_build/html/_static/fonts/RobotoSlab && \ - ln -s roboto-slab-v7-regular.eot roboto-slab.eot - -CMD ["python", "-m", "http.server", "8000"] - diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 298ea9e21..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css index faa300bc1..0c7edb7a6 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,15 +1,24 @@ @import url("https://fonts.googleapis.com/css?family=Montserrat&display=swap"); -@import url("https://fonts.googleapis.com/css?family=Roboto+Mono&display=swap"); body { font-family: "Montserrat", sans-serif; } -.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { - font-family: "Roboto Mono", monospace; +.md-logo { + width: 40px; + height: 40px; + padding-bottom: 2px; + padding-top: 2px; +} +.md-logo img { + width: 40px; + height: 40px; } -code { - font-family: "Roboto Mono", monospace; +.md-header, .md-footer-nav { + background-image: linear-gradient(45deg, rgb(0, 150, 225) 0%, rgb(27, 141, 226) 24%, rgb(42, 125, 227) 53%, rgb(53, 112, 227) 78%, rgb(53, 112, 227) 100%); } +.md-header-nav__title { + font-size: .85rem; +} diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index a84437eee..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,177 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys -sys.path.insert(0, os.path.abspath('.')) - -# -- Project information ----------------------------------------------------- - -project = 'Flux Helm Operator' -copyright = '2019, Flux development team' -author = 'Flux development team' - -# The short X.Y version -version = '' -# The full version, including alpha/beta/rc tags -release = '' - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'recommonmark', - 'sphinx_markdown_tables', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = ['.rst', '.md'] - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'HelmOperatordoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'flux-helm-operator.tex', 'Flux Helm Operator Documentation', - 'Flux development team', 'manual'), -] - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'flux helm operator', 'Flux Helm Operator Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'Flux Helm Operator', 'Flux Helm Operator Documentation', - author, 'Flux Helm Operator', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - -def setup(app): - app.add_stylesheet('custom.css') diff --git a/docs/faq.md b/docs/faq.md index f66f2e0c0..79e759f60 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,62 +1,103 @@ # Frequently asked questions -### I'm using SSL between Helm and Tiller. How can I configure the operator to use the certificate? - -When installing Flux, you can supply the CA and client-side certificate using the `helmOperator.tls` options, -more details [here](./tutorials/get-started.md). - -### I've deleted a HelmRelease file from Git. Why is the Helm release still running on my cluster? - -Flux doesn't delete resources by default, you can enable Flux garbage collection feature -by passing the command-line flag `--sync-garbage-collection` to `fluxd`. - -With Flux garbage collection enabled, Helm operator will receive the delete event and will purge the Helm release. - -### I've manually deleted a Helm release. Why is Flux not able to restore it? - -If you are using Helm 3+ the default behaviour is to purge - enabling flux to restore the release. -For Helm<=2, if you delete a Helm release with `helm delete my-release`, the release name can't be reused. -You need to use the `helm delete --purge` option only then Flux will be able reinstall a release. - -### It takes a long time before the operator processes an update to a `HelmRelease` resource. How can I speed up the processing of releases? - -The operator watches for changes of Custom Resources of kind `HelmRelease`. It receives Kubernetes -Events and queues these to be processed, all resources will also be re-queued every -`--charts-sync-interval` (default `3m`) for a dry-run to detect and revert manual changes made to a +### A `HelmRelease` is stuck in a `failed` release state. How do I force it through? + +You need to manually perform a `helm rollback` or `helm upgrade` to get it in +a healthy `deployed` state again before the Helm Operator will continue. +Read more about this in [the `HelmRelease` +guide](helmrelease-guide/reconciliation-and-upgrades.md#upgrade-failures). + +### A `HelmRelease` reports a `deployed` release status but also an error. What is going on? + +The release status recorded in the `status` sub-resource of the `HelmRelease` +is the status as given by Helm for the release. It is polled from Helm on a +interval (see +[`--status-update-interval`](references/operator.md#reconciliation-configuration)). + +The message is the error reported during the latest release failure. When this +failure was for example due to a validation error, the upgrade has not been +completed, and the status of the release will thus still be `deployed`. + +### I want to automate chart releases from Helm chart repositories. Is this possible? + +This is possible by wrapping the chart from the Helm chart repository in +an umbrella chart sourced from a Git source, [read more about this +here](helmrelease-guide/automation.md#helm-repository-chart-updates). + +### It takes a long time before the operator processes an update to a resource. How can I speed up the processing of releases? + +The operator watches for changes of Custom Resources of kind `HelmRelease`. It +receives Kubernetes Events and queues these to be processed. All resources will +also be re-queued every [`--charts-sync-interval` +(default `3m`)](references/operator.md#reconciliation-configuration) for a +dry-run to detect and revert manual changes made to a release. + +Depending on how many resources the operator is watching and the complexity of +the charts (umbrella charts for example generally take a longer time to +process), the default number of workers may not be sufficient to instantly +process a release the moment it enters the queue as the queue works on a +[FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) basis, +and other releases may have to be processed first. + +The solution is to increase the number of workers processing the releases using +the `--workers` flag (default `2`), i.e. by steps of `2` until the releases are +processed within a time frame that feels right to you. + +If this does not give the desired effect, or if the number of workers required +is unacceptably high, there are two other tweaks possible: + +1. increasing the `--charts-sync-interval`; this causes the queue to be less + heavy occupied at the cost of detecting mutations less rapidly +1. using multiple Helm Operator instances, i.e. by having one operator per + namespace; namespace scoping is possible by configuring the + `--allow-namespace` flag + +### The Helm Operator is taking up too many resources. How can I limit the resource usage? + +When you are running the Helm Operator on an edge, home lab, or other resource +constrained cluster it may take up too many resources for your liking. + +1. In case of a high number of `HelmRelease` resources, think about a namespace + restricted multi-tenant setup as an option to spread the load and have finer + grain control over configuration. +1. Increase the [various polling intervals](references/operator.md) based on + what your environment really needs: + + - `--status-update-interval`: The interval at which Helm is polled for + the current state of the release, generally safe to increase. + - `--charts-sync-interval`: The interval at which `HelmRelease` resources + are re-queued for reconciliation. Increasing this interval will result + in mutations to a chart release being detected slower. + - `--git-poll-interval`: The interval at which Git repositories are + polled for changes for charts from Git sources. + +### I have manually deleted a Helm release using `helm`. Why is the operator not able to restore it? + +When you delete a Helm release with `helm delete ` using Helm 2, the +release name can not be re-used as the history of the old release is still +stored in the Helm storage under the same name. You need to use the +`helm delete --purge` option, only then the release history will be removed +from the Helm storage and the Helm Operator will then be able to reinstall the release. -Depending on how many resources the operator is watching and the complexity of the charts (umbrella -charts for example generally take a longer time to process); the default amount of workers may not -be sufficient to instantly process a release the moment it enters the queue as the queue works on -a [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) basis, and other releases -may have to be processed first. - -The solution is to increase the amount of workers processing the releases using the `--workers` -flag (default `2`), i.e. by steps of `2` until the releases are processed within a time frame that -feels right to you. - -If this does not give the desired effect, or if the amount of workers required is incredible high, -there are two other tweaks possible: +### I am using SSL between Helm and Tiller. How can I configure the operator to use the certificate? -1. increasing the `--charts-sync-interval`; this causes the queue to be less heavy occupied at the - cost of detecting mutations less rapidly -1. using multiple Helm operator instances, i.e. by having one operator per namespace; namespace - scoping is possible by configuring the `--allow-namespace` flag +When installing the Helm Operator, you can supply the CA and client-side +certificate using the `tls` options on the chart. More details about this +on: -### I have a dedicated Kubernetes cluster per environment and I want to use the same Git repo for all. How can I do that? +- [Get started using Helm](get-started/using-helm.md#with-tiller-helm-2) +- [Get started using Kustomize](get-started/using-kustomize.md#prepare-the-manifests-for-installation) +- [Get started using YAMLs](get-started/using-yamls.md#helm-2) -*Option 1* -For each cluster create a directory in your config repo. -When installing Flux Helm chart set the Git path using `--set git.path=k8s/cluster-name` -and set a unique label for each cluster `--set git.label=cluster-name`. +### I am using Flux and have deleted a `HelmRelease` file from Git. Why is the Helm release still running on my cluster? -You can have one or more shared dirs between clusters. Assuming your shared dir is located -at `k8s/common` set the Git path as `--set git.path="k8s/common\,k8s/cluster-name"`. +Flux does not delete resources by default; you can enable Flux garbage +collection feature by passing the command-line flag +`--sync-garbage-collection` to `fluxd`. -*Option 2* -For each cluster create a Git branch in your config repo. -When installing Flux Helm chart set the Git branch using `--set git.branch=cluster-name` -and set a unique label for each cluster `--set git.label=cluster-name`. +With Flux garbage collection enabled, the Helm Operator will receive the delete +event and will purge the Helm release. ### Are there prerelease builds I can run? diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md new file mode 100644 index 000000000..31f986cad --- /dev/null +++ b/docs/get-started/quickstart.md @@ -0,0 +1,281 @@ +# Quickstart + +This guide walks you through to all steps required to quickly get +started with the Helm Operator. + +## Prerequisites + +- Kubernetes cluster **>=1.13.0** +- Up-to-date **Helm 2 or 3** [`helm` binary](https://github.com/helm/helm/releases) +- `kubectl` + +## Install the Helm Operator + +First, install the `HelmRelease` Custom Resource Definition. By adding +this CRD it will be possible to define `HelmRelease` resources on the +cluster: + +```sh +kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/crds.yaml +``` + +Create a new namespace: + +```sh +kubectl create ns flux +``` + +Using `helm`, first add the Flux CD Helm repository: + +```sh +helm repo add fluxcd https://charts.fluxcd.io +``` + +Next, install the Helm Operator using the available Helm chart: + +```sh +helm upgrade -i helm-operator fluxcd/helm-operator \ + --namespace flux \ + --set helm.versions=v3 +``` + +This installs the Helm Operator with default settings and support for +Helm 3 enabled. + +!!! hint + See the [operator reference](../references/operator.md) and [chart + documentation](../references/chart.md#configuration) + for detailed configuration options. + +## Create your first `HelmRelease` + +To install a Helm chart using the Helm Operator, create a `HelmRelease` +resource on the cluster: + +```sh +cat < +Annotations: kubectl.kubernetes.io/last-applied-configuration: + {"apiVersion":"helm.fluxcd.io/v1","kind":"HelmRelease","metadata":{"annotations":{},"name":"podinfo","namespace":"default"},"spec":{"chart... +API Version: helm.fluxcd.io/v1 +Kind: HelmRelease +Metadata: + Creation Timestamp: 2020-01-01T12:00:00Z + Generation: 1 + Resource Version: 9017 + Self Link: /apis/helm.fluxcd.io/v1/namespaces/default/helmreleases/podinfo + UID: e9c11dc8-5ba6-4ee7-9226-cb0f9cab04ff +Spec: + Chart: + Name: podinfo + Repository: https://stefanprodan.github.io/podinfo + Version: 3.2.0 +Status: + Conditions: + Last Transition Time: 2020-01-01T12:00:00Z + Last Update Time: 2020-01-01T12:00:00Z + Message: chart fetched: podinfo-3.2.0.tgz + Reason: RepoChartInCache + Status: True + Type: ChartFetched + Last Transition Time: 2020-01-01T12:00:01Z + Last Update Time: 2020-01-01T12:00:01Z + Message: Helm release sync succeeded + Reason: HelmSuccess + Status: True + Type: Released + Observed Generation: 1 + Release Name: default-podinfo + Release Status: deployed + Revision: 3.2.0 +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal ChartSynced 35s helm-operator Chart managed by HelmRelease processed +``` + +Confirm the `default-podinfo` pod has been deployed: + +```console +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +default-podinfo-7f9759cc66-bslsl 1/1 Running 0 59s +``` + +!!! tip + The available shorthand for `kubectl` operations on `helmrelease` + resources is `hr`, i.e: + + ```console + $ kubectl get hr + NAME RELEASE STATUS MESSAGE AGE + podinfo default-podinfo deployed Helm release sync succeeded 59s + ``` + +## Make a modification + +The Helm Operator ensures that the Helm release in the cluster matches +the defined state in the `HelmRelease` resource. This means that an +upgrade will be performed when the resource is modified. To demonstrate +this, we are going to increase the number of `podinfo` replicas: + +```sh +kubectl edit helmrelease/podinfo +``` + +[Helm values](https://helm.sh/docs/chart_best_practices/values/#helm) +can be defined on the `HelmRelease` resources under the `spec.values` +key: + +```yaml +... +spec: + chart: + name: podinfo + repository: https://stefanprodan.github.io/podinfo + version: 3.2.0 + values: + replicaCount: 2 +``` + +Save the modification and watch the new pod enroll: + +```console +$ kubectl get pods -w +NAME READY STATUS RESTARTS AGE +default-podinfo-7f9759cc66-lk45t 1/1 Running 0 59s +default-podinfo-7f9759cc66-w7fj7 0/1 ContainerCreating 0 1s +default-podinfo-7f9759cc66-w7fj7 0/1 Running 0 1s +default-podinfo-7f9759cc66-w7fj7 1/1 Running 0 1s +``` + +!!! hint + See the [values](../helmrelease-guide/values.md) and [release + configuration](../helmrelease-guide/release-configuration.md) + sections in the `HelmRelease` guide for more details. + +## Reconciliation + +All `HelmRelease` resources in the cluster watched by a Helm Operator +instance are rescheduled to synchronize every 3 minutes (or configured +`--charts-sync-interval`); this is also known as the reconciliation +loop. + +During reconciliation the result of a dry-run upgrade made with the +`HelmRelease` resource is compared to the current deployed Helm +release, and if they differ an upgrade is performed to ensure the defined +and in-cluster state match again. + +You can experience this with your own eyes by rolling back the +modification we just made using `helm`, the Helm Operator created +the release with a name composed of the namespace and name of the +`HelmRelease`: + +```console +$ helm rollback podinfo +Rollback was a success! Happy Helming! +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +default-podinfo-7f9759cc66-w7fj7 1/1 Terminating 0 1m1s +default-podinfo-7f9759cc66-lk45t 1/1 Running 0 2m1s +``` + +Watch the Helm Operator reverting the unauthorized modification (this +can take a while, but no longer than 3 minutes): + +```console +$ kubectl get pods -w +NAME READY STATUS RESTARTS AGE +default-podinfo-7f9759cc66-lk45t 1/1 Running 0 2m19s +default-podinfo-7f9759cc66-kd5rk 0/1 Pending 0 0s +default-podinfo-7f9759cc66-kd5rk 0/1 Pending 0 0s +default-podinfo-7f9759cc66-kd5rk 0/1 ContainerCreating 0 0s +default-podinfo-7f9759cc66-kd5rk 0/1 Running 0 1s +default-podinfo-7f9759cc66-kd5rk 1/1 Running 0 7s +``` + +!!! hint + Read more about [reconciliation and + upgrades](../helmrelease-guide/reconciliation-and-upgrades.md) in + the `HelmRelease` guide. + +## Uninstalling the chart + +To uninstall the chart and clean up the release, simply run `kubectl +delete` for the resource: + +```sh +kubectl delete helmrelease podinfo +``` + +```console +$ kubectl get pods -w +NAME READY STATUS RESTARTS AGE +default-podinfo-7f9759cc66-fr4vb 1/1 Terminating 0 3m30s +default-podinfo-7f9759cc66-kd5rk 1/1 Terminating 0 1m6s +default-podinfo-7f9759cc66-kd5rk 0/1 Terminating 0 1m8s +default-podinfo-7f9759cc66-fr4vb 0/1 Terminating 0 3m32s +``` + +Delete the Helm Operator by removing the `fluxcd` namespace: + +```sh +kubectl delete namespace flux +``` + +## Next steps + +Want to continue testing the Helm Operator or install it in a cluster +environment? Take a look at the available get started guides for more +sophisticated setup options: + +- [Get started using Helm](using-helm.md) +- [Get started using Kustomize](using-kustomize.md) +- [Get started using YAMLs](using-yamls.md) + +Want to take a deeper dive in the available features and the +`HelmRelease` resource? +**Continue with the [`HelmRelease` guide](../helmrelease-guide/introduction.md).** \ No newline at end of file diff --git a/docs/get-started/using-helm.md b/docs/get-started/using-helm.md new file mode 100644 index 000000000..e7342bba1 --- /dev/null +++ b/docs/get-started/using-helm.md @@ -0,0 +1,110 @@ +# Get started using Helm + +This guide walks you through setting up the Helm Operator using the +available [Helm chart](https://github.com/fluxcd/helm-operator/tree/master/chart/helm-operator). + +## Prerequisites + +- Kubernetes cluster **>=1.13.0** +- Up-to-date **Helm 2 or 3** [`helm` binary](https://github.com/helm/helm/releases) +- _(Optional)_ + Tiller [(secure setup)](https://v2.helm.sh/docs/securing_installation/) + +## Install the Helm Operator chart + +Install the `HelmRelease` Custom Resource Definition. By adding this +CRD it will be possible to define `HelmRelease` resources on the +cluster: + +```sh +kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/crds.yaml +``` + +Using `helm`, add the Flux CD Helm repository: + +```sh +helm repo add fluxcd https://charts.fluxcd.io +``` + +Install the Helm Operator using the available Helm chart: + +```sh +helm upgrade -i helm-operator fluxcd/helm-operator \ + --set helm.versions=v3 +``` + +Confirm the Helm Operator deployed successfully: + +```console +$ helm status helm-operator +NAME: helm-operator +LAST DEPLOYED: Wed Jan 01 12:00:00 2020 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +... +``` + +```console +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +helm-operator-6985656995-dpmdl 1/1 Running 0 31s +``` + +!!! note + This installs the Helm Operator with only support for Helm 3 + enabled, to also enable support for Helm 2 and connect to Tiller, read + [with Tiller](#with-tiller-helm-2) below. + +### With Tiller (Helm 2) + +Make sure [your Tiller installation is +secure](https://v2.helm.sh/docs/securing_installation/), and create a +secret for the client certificates: + +```sh +kubectl create secret tls helm-client-certs \ + --cert=cert.pem \ + --key=key.pem +``` + +Install (or upgrade) the Helm Operator with the [Tiller +configuration](../references/operator.md#tiller-configuration) +while also enabling Helm 2 support: + +```sh +helm upgrade -i helm-operator fluxcd/helm-operator \ + --set tillerNamespace=kube-system \ + --set tls.enable=true \ + --set helm.versions="v2\,v3" +``` + +Confirm the Helm Operator deployed successfully and connected to +Tiller: + +```console +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +helm-operator-7cc7c798cc-kn26w 1/1 Running 0 18s +``` + +```console +$ kubectl logs -f deploy/helm-operator +... +ts=2020-01-01T12:00:00.556712443Z caller=helm.go:71 component=helm version=v2 info="connected to Tiller" version="sem_ver:\"v2.16.3\" git_commit:\"1ee0254c86d4ed6887327dabed7aa7da29d7eb0d\" git_tree_state:\"clean\" " host=tiller-deploy.kube-system:44134 options="{Host: Port: Namespace:kube-system TLSVerify:false TLSEnable:true TLSKey:/etc/fluxd/helm/tls.key TLSCert:/etc/fluxd/helm/tls.crt TLSCACert: TLSHostname:}" +``` + +!!! tip + Targeting a specific Helm version in a `HelmRelease` is possible by + defining the `spec.helmVersion`, e.g: `helmVersion: v3` to target + Helm 3. Read more about this in '[targeting a Helm + version](../helmrelease-guide/release-configuration.md#targeting-a-helm-version)' + in the `HelmRelease` guide. + +## Next + +- Learn all about the available configuration options in the [chart + documentation](../references/chart.md#configuration) + and [operator reference](../references/operator.md). +- Continue learning about `HelmRelease` resources [in the + guide](../helmrelease-guide/introduction.md). \ No newline at end of file diff --git a/docs/get-started/using-kustomize.md b/docs/get-started/using-kustomize.md new file mode 100644 index 000000000..2dd14a434 --- /dev/null +++ b/docs/get-started/using-kustomize.md @@ -0,0 +1,325 @@ +# Get started using Kustomize + +This guide walks you through setting up the Helm Operator using +[Kustomize](https://kustomize.io). + +## Prerequisites + +- Kubernetes cluster **>=1.13.0** +- `kustomize` **>=3.2.0** +- Some knowledge of Kustomize +- _(Optional)_ + Tiller [(secure setup)](https://v2.helm.sh/docs/securing_installation/) + +## Prepare the manifests for installation + +Create a directory called `helm-operator`: + +```sh +mkdir helm-operator +``` + +Create a `kustomization.yaml` file and use the [Helm Operator +deployment YAMLs](https://github.com/fluxcd/helm-operator/tree/{{ version }}/deploy) +as a base: + +```sh +cat > helm-operator/kustomization.yaml < helm-operator/patch-tiller-tls.yaml < helm-operator/namespace.yaml < helm-operator/patch-default-ns.yaml < helm-operator/repositories.yaml < helm-operator/patch-repositories-mount.yaml <=1.1.3.0** +- `kubectl` +- _(Optional)_ + Tiller [(secure setup)](https://v2.helm.sh/docs/securing_installation/) + +## Install the Helm Operator + +First, install the `HelmRelease` Custom Resource Definition. By adding this CRD +it will be possible to define `HelmRelease` resources on the cluster: + +```sh +kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/crds.yaml +``` + +Proceed to create the `flux` namespace, this is the namespace the Helm Operator +will be deployed to: + +```sh +kubectl create namespace flux +``` + +Apply the `ServiceAccount`, `ClusterRole` and `ClusterRoleBinding` so that the +Helm Operator can access cluster resources: + +```sh +kubectl apply -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/rbac.yaml +``` + +Apply the Helm Operator deployment itself: + +```sh +kubectl deploy -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/deployment.yaml +``` + +### Helm 3 + +The default deployment of the Helm Operator comes with support for Helm 2 and 3 +enabled. To disable support for Helm 2 (and recover from the Tiller connection +failure), patch the resource to set `--enabled-helm-versions=v3`: + +``` +kubectl deploy -f https://raw.githubusercontent.com/fluxcd/helm-operator/{{ version }}/deploy/deployment.yaml \ + --type='json' \ + -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value":"--enabled-helm-versions=v3"}]' +``` + +### Helm 2 + +The default deployment of the Helm Operator does enable support for Helm 2 but +does not take any custom configurations like Tiller TLS settings into account. +If your Tiller is e.g. in a different namespace than `kube-system` or +[securely setup](https://v2.helm.sh/docs/securing_installation/), take a look +at the available [Tiller configuration flags](../references/operator.md#tiller-configuration) +and [commented out sections](https://github.com/fluxcd/helm-operator/blob/{{ version }}/deploy/deployment.yaml) +in the example deployment to further tweak your Helm Operator installation. + +## Next + +- Learn all about the available configuration options in the [operator + reference](../references/operator.md). +- Continue learning about `HelmRelease` resources [in the + guide](../helmrelease-guide/introduction.md). diff --git a/docs/guides/index.rst b/docs/guides/index.rst deleted file mode 100644 index 088967cdd..000000000 --- a/docs/guides/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Guides -====== - -.. toctree:: - :maxdepth: 1 - - upgrading-to-ga - upgrading-to-beta diff --git a/docs/guides/upgrading-to-beta.md b/docs/guides/upgrading-to-beta.md index 794094380..84dd6d0db 100644 --- a/docs/guides/upgrading-to-beta.md +++ b/docs/guides/upgrading-to-beta.md @@ -1,153 +1 @@ -# Upgrading from Helm operator alpha (<=0.4.0) to beta - -The Helm operator has undergone changes that necessitate some changes -to custom resources, and the deployment of the operator itself. - -The central difference is that the Helm operator now works with -resources of the kind `HelmRelease` in the API version -`flux.weave.works/v1beta1`, which have a different format to the -custom resources used by the old Helm operator (`FluxHelmRelease`). - -Here are some things to know: - -- The new operator will ignore the old custom resources (and the old - operator will ignore the new resources). -- Deleting a resource while the corresponding operator is running - will result in the Helm release also being deleted -- Deleting a `CustomResourceDefinition` will also delete all - custom resources of that kind. -- If both operators are running and both new and old custom resources - defining a release, the operators will fight over the release. - -The safest way to upgrade is to avoid deletions and fights by stopping -the old operator. Replacing it with the new one (e.g., by changing the -deployment, or re-releasing the Flux chart with the new version) will -have that effect. - -Once the old operator is not running, it is safe to deploy the new -operator, and start replacing the old resources with new -resources. You can keep the old resources around during this process, -since the new operator will ignore them. - -## Upgrading the operator deployment - -### Using the Flux chart - -The chart (from v0.5.0, or from this git repo) provides the -correct arguments to the operator; to upgrade, do - -```sh -helm repo update - -helm upgrade flux --reuse-values \ ---set image.tag=1.8.1 \ ---set helmOperator.tag=0.5.1 \ ---namespace=flux \ -fluxcd/flux --version 0.5.1 -``` - -The chart will leave the old custom resource definition and custom -resources in place. You will need to replace the individual resources, -as described below. - -### Using manifests - -You will need to adapt any existing manifest that you use to run the -Helm operator. The arguments to the operator executable have changed, -since it no longer needs the git repo to be specified (and in some -cases, just to tidy up): - -- the new operator does not use the `--git-url`, `--git-charts-path`, - or `--git-branch` arguments, since the git repo and so on are - provided in each custom resource. -- the `--queue-worker-count` argument has been removed -- the `--chart-sync-timeout` argument has been removed -- other arguments stay the same - -It is entirely valid to run the operator with no arguments, which you -may end up with after removing those mentioned above. It will work -with the secrets mounted as for the old operator, to start off with, -since it expects the SSH key for the git repo to be in the same place. - -Once you want to use the new capabilities of the operator -- e.g., -releasing charts from Helm repos -- you will probably need to adapt -the manifest further. The [`HelmRelease` Custom Resource](./../references/helmrelease-custom-resource.md) -and [operator](./../references/operator.md) references explain all -the details. - -## Updating custom resources - -The main differences between the old resource format and the new are: - -- the API version and kind have changed -- you can now specify a chart to release either as a path in a git - repo, or a named, versioned chart from a Helm repo - -Here is how to change an old resource to a new resource: - -- change the `apiVersion` field to `flux.weave.works/v1beta1` -- change the `kind` field to `HelmRelease` -- you can remove the label `chart:` from the labels, if it's still - there, just to tidy up (it doesn't matter if it's there or not) -- replace the field `chartGitPath`, with the structure: - -```yaml -chart: - git: - ref: - path: -``` - -- the `values`, `releaseName`, and `valueFileSecrets` can stay as - they are. - -Note that you now give the git repo URL and branch and full path in -each custom resource, rather than supplying arguments to the Helm -operator. (As you've been using the old operator, you'll only have one -git repo for all charts -- but now you can use different repos for -charts!) - -As a full example, this is an old resource: - -```yaml ---- -apiVersion: helm.integrations.flux.weave.works/v1alpha2 -kind: FluxHelmRelease -metadata: - name: foobar - namespace: foo-ns -spec: - chartGitPath: foobar - values: - image: - repository: foobar - tag: v1 -``` - -Say the arguments given to the old Helm operator were - -```yaml -args: - - --git-url=git@example.com:user/repo - - --git-charts-path=charts - - --git-branch=master -``` - -Then the new custom resource would be: - -```yaml ---- -apiVersion: flux.weave.works/v1beta1 # <- change API version -kind: HelmRelease # <- change kind -metadata: - name: foobar - namespace: foo-ns -spec: - chart: - git: git@example.com:user/repo # <- --git-url from operator args - path: charts/foobar # <- join --git-chart-path and chartGitPath - values: - image: - repository: foobar - tag: v1 -``` +The contents of this document have been moved to [`how-to`](../how-to/upgrade-to-beta.md). diff --git a/docs/guides/upgrading-to-ga.md b/docs/guides/upgrading-to-ga.md index ca30cb2b6..a7547ad2d 100644 --- a/docs/guides/upgrading-to-ga.md +++ b/docs/guides/upgrading-to-ga.md @@ -1,99 +1 @@ -# Upgrading from Helm operator beta (`>=0.5.0`) to stable (`>=1.0.0`) - -Due to the Flux CD project joining the CNCF Sandbox and the API -becoming stable, the Helm operator has undergone changes that -necessitate some changes to your `HelmRelease` resources. - -The central difference is that the Helm operator now works with -resources of the kind `HelmRelease` in the API version -`helm.fluxcd.io/v1`, the format of the resource is backwards -compatible. - -Here are some things to know: - -- The new operator will ignore the old custom resources (and the old - operator will ignore the new resources). -- Deleting a resource while the corresponding operator is running - will result in the Helm release also being deleted -- Deleting a `CustomResourceDefinition` will also delete all - custom resources of that kind. -- If both operators are running and both new and old custom resources - defining a release, the operators will fight over the release. - -The safest way to upgrade is to avoid deletions and fights by stopping -the old operator. Replacing it with the new one (e.g., by changing the -deployment, or re-releasing the Flux chart with the new version) will -have that effect. - -Once the old operator is not running, it is safe to deploy the new -operator, and start replacing the old resources with new -resources. You can keep the old resources around during this process, -since the new operator will ignore them. - -## Updating custom resources - -> **Note:** once the new CRD is applied it is no longer possible -> to list your old and new `HelmRelease` resources with just `kubectl -> get `, due to them sharing the same names. It is -> however still possible to list them by their full name. -> -> ```bash -> # Old `HelmRelease` resources -> $ kubectl get helmreleases.flux.weave.works -> # New `HelmRelease` resources -> $ kubectl get helmreleases.helm.fluxcd.io -> ``` - -The only difference between the old resource format and the new is -the changed API version. - -Changing an old resource to a new resource is thus as simple as -changing the `apiVersion` field to `helm.fluxcd.io/v1`. - -As a full example, this is an old resource: - -```yaml ---- -apiVersion: flux.weave.works/v1beta1 -kind: HelmRelease -metadata: - name: foobar - namespace: foo-ns -spec: - chart: - git: git@example.com:user/repo - path: charts/foobar - values: - image: - repository: foobar - tag: v1 -``` - -The new custom resource would be: - -```yaml ---- -apiVersion: helm.fluxcd.io/v1 # <- change API version -kind: HelmRelease -metadata: - name: foobar - namespace: foo-ns -spec: - chart: - git: git@example.com:user/repo - path: charts/foobar - values: - image: - repository: foobar - tag: v1 -``` - -## Deleting the old resources - -Once you have migrated all your `HelmRelease` resources to the new API -version and domain. You can remove all of the old resources by removing -the old Custom Resource Definition. - -```sh -$ kubectl delete crd helmreleases.flux.weave.works -``` +The contents of this document have been moved to [`how-to`](../how-to/upgrade-to-ga.md). diff --git a/docs/helmrelease-guide/automation.md b/docs/helmrelease-guide/automation.md new file mode 100644 index 000000000..4e2ba83d8 --- /dev/null +++ b/docs/helmrelease-guide/automation.md @@ -0,0 +1,44 @@ +# Automation + +This section of the guide is mostly a clarification of some common +misconceptions about (non-existent) automation features of the Helm Operator. + +## Image updates + +Because the Helm Operator is a [Flux umbrella project](https://fluxcd.io), +occasionally people assume it is capable of updating image references in +the `HelmRelease` and/or associated charts. This feature is however baked +in to [Flux](https://github.com/fluxcd/flux), and not the Helm Operator +itself due to it having no knowledge of available images or the origin of the +`HelmRelease`. + +For more details about this Flux feature, please refer to the [documentation +for the `HelmRelease` integration](https://docs.fluxcd.io/en/stable/references/helm-operator-integration.html). + +## Helm repository chart updates + +Another much requested feature is automated updates for charts from [Helm +repository chart sources](chart-sources.md#helm-repositories). The +development of this feature is currently blocked until the automation logic +has been untangled from Flux. To keep up-to-date about new developments of +this feature you can subscribe to +[fluxcd/helm-operator#12](https://github.com/fluxcd/helm-operator/issues/12). + +It is possible to get a similar functionality by making use of an +[umbrella chart](https://helm.sh/docs/howto/charts_tips_and_tricks/#complex-charts-with-many-dependencies) +from a [Git repository chart source](chart-sources.md#git-repositories) with +a [version range set](https://helm.sh/docs/topics/chart_best_practices/dependencies/#versions), +as for charts from Git repository sources, a [dependency update is performed by +default](chart-sources.md#dependency-updates), and that will download the +latest available version within the defined range. + +For example, to make the Helm Operator install the latest `1.2.x` patch release +for `foo-chart`, you would define the following in the `dependencies` of your +(dummy) umbrella chart in Git: + +```yaml +dependencies: +- name: + version: ~1.2.0 + repository: https://charts.example.com +``` diff --git a/docs/helmrelease-guide/chart-sources.md b/docs/helmrelease-guide/chart-sources.md new file mode 100644 index 000000000..c705aff36 --- /dev/null +++ b/docs/helmrelease-guide/chart-sources.md @@ -0,0 +1,525 @@ +# Chart sources + +In the introduction we created a simple `HelmRelease` that made use of a chart +from a Helm repository, but the Helm Operator does support multiple chart +sources, and virtually any protocol and/or source that can be shelled-in +through a [Helm downloader plugin](#extending-the-supported-helm-repository-protocols). + +In this section of the guide we will take a deeper dive into the available +chart sources, and the unique features they have. + +## Comparison + +The following are short lists of the major characteristics of the different +chart sources. Keep these in mind when you have to make a decision about what +type of chart source to use for your `HelmRelease`, as they result in quite +different behaviour. + +### Charts from [Helm repositories](#helm-repositories) + +- Are immutable and non-moving (i.e. no updates for the chart itself are + received unless the `.chart.version` is changed). +- Are cached for the lifetime duration of the Helm Operator pod. +- Are shared between `HelmRelease` resources making use of the same chart + and version. +- Require a custom `repositories.yaml` to be [mounted and imported](#authentication-and-certificates) + when authentication is required. +- [Are not just limited to HTTP/S](#extending-the-supported-helm-repository-protocols). +- _Do not support_ chart dependency updates (but instead use the dependencies + bundled with the chart). +- _Do not support_ `valuesFrom.chartFileRef`. + +### Charts from [Git repositories](#git-repositories) + +- Move by mirroring the Git repository and fetching the latest `HEAD` for the + configured `.chart.ref` on an interval (i.e. when a change is detected in + Git under the `.chart.path`, a release will be scheduled for an upgrade). +- Share their Git repository mirror with `HelmRelease` resources making use + of the same `.chart.git`, `.chart.ref` and `.chart.secretKeyRef`. +- Require a [private key to be mounted for Git over SSH](#ssh). +- Support credentials from a secret or a global `.netrc` file for [Git over + HTTPS](#https). +- _Do support_ [chart dependency updates](#dependency-updates) +- _Do support_ [`valuesFrom.chartFileRef`](values.md#chart-files) to make use + of alternative value files present in the `.chart.path`. + +## Helm repositories + +The Helm repository chart source is defined as follows in the `.spec` of a +`HelmRelease`. All listed fields are mandatory: + +```yaml +spec: + chart: + repository: https://stefanprodan.github.io/podinfo + name: podinfo + version: 3.2.0 +``` + +The definition of the listed keys is as follows: + +* `repository`: The URL of the Helm repository, e.g. `https://kubernetes-charts.storage.googleapis.com` + or `https://charts.example.com`. + + Putting `/index.yaml` behind the URL it should return an index file with all + available charts for the Helm repository. +* `name`: The name of the Helm chart _without_ an alias, e.g. `podinfo` + (instead of `/podinfo`). + + Having doubts about what to put here? Use the `name` as listed in the + `Chart.yaml` of the Helm chart you want to use. +* `version`: The targeted Helm chart version, e.g. `3.2.0`. + +In the [introduction](introduction.md) you already had a brief exposure to this +chart source, and in essence Helm repositories are the simplest way to make use +of a Helm chart in a `HelmRelease`. + +To be able to perform releases with them the Helm Operator only makes use of +native Helm features and a tiny bit of glue to wire things together: + +It will first attempt a reverse lookup for a repository alias in the local +`repositories.yaml` for the defined `repository` URL, if an alias is found it +will use this alias with the given `name` and `version` to instruct Helm to +fetch the chart to a cache path defined by the Helm Operator. + +If the reverse lookup failed and no alias was found for the given URL it will +fallback to attempting to retrieve the absolute URL of the chart from the index +of the given `repository` URL, this URL is then used to instruct Helm to fetch +the chart to a cache path defined by the Helm Operator. + +When this does not succeed either a status condition of type `ChartFetched` +will be recorded on the `HelmRelease` resource with the returned error. + +### Authentication and certificates + +Some Helm repositories require authentication or certificates before you are +able to make use of any charts they hold. At present, per-resource +authentication is not implemented for Helm repositories. The `HelmRelease` +Custom Resource does include a field `chartPullSecret` for attaching a +`repositories.yaml` file, but this has not been actually implemented. + +As a workaround, you can mount a `repositories.yaml` file with authentication +already configured (and any required certificates) into the Helm Operator +container, and import it using the `--helm-repository-import` flag. + +First, create a new empty `repositories.yaml` file _locally_: + +```sh +touch repositories.yaml +``` + +You can now use `helm` to write the repository entry to this new file. Using +Helm 3 for this is the best option as it offers a `--repository-config` flag +and the generated output works for both versions: + +```sh +helm repo add \ + --repository-config $PWD/repositories.yaml \ + --username \ + --password \ + +``` + +!!! note + For Azure ACR repositories, you will need to [create a service + principal](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal#create-a-service-principal) + and use the plain text ID and password this gives you. + +If you need to define any certificates, edit the respective `caFile`, `certFile` +and `keyFile` values of the entry you just added to the mount paths you will +later add to the Helm Operator _container_ (example path used here is +`/var/certs/*`): + +```yaml +- caFile: /var/certs/ca.crt + certFile: /var/certs/cert.crt + keyFile: /var/certs/auth.key + name: +``` + +Now you can create a secret in the same namespace as you are running the Helm +operator, from the repositories file: + +```sh +kubectl create secret generic flux-helm-repositories \ + --from-file=$PWD/repositories.yaml +``` + +In case you defined any certificate entries, also create a secret for those +files in the same namespace as you are running the Helm Operator: + +```sh +kubectl create secret generic flux-helm-repository-certs \ + --from-file=$PWD/ca.crt \ + --from-file=$PWD/cert.crt \ + --from-file=$PWD/auth.key +``` + +Mount the created secret(s) by adding to `volumes` in the pod spec of the Helm +operator deployment, and `volumeMounts` of the Helm Operator container. A good +mount path for the `repositories.yaml` file that does not give conflicts with +any Helm paths is `/root/.helm/repository/repositories.yaml`. Examples of this +can be found in the commented-out sections of the [example +deployment](https://github.com/fluxcd/helm-operator/blob/{{ version }}/deploy/deployment.yaml). + +Lastly, configure the `--helm-repository-import` argument on the Helm Operator +container for your enabled Helm versions: + +```yaml + args: + - --helm-repository-import=v2:/root/.helm/repository/repositories.yaml,v3:/root/.helm/repository/repositories.yaml +``` + +!!! note + There is no limit to the amount of repository files that can be imported + as the `--helm-repository-import` flag accepts a comma separated string + slice of `:`, e.g. `v3:/my/path.yaml`. + Adding all entries to the same file and/or secret is thus not a requirement. + +!!! hint + For the [Helm chart](../references/chart.md), this all can be done by setting + `configureRepositories.enable` to `true`, it will automatically pick up the + `flux-helm-reposities` secret created earlier in this guide and configure the + `--helm-repository-import` flag for the enabled Helm versions. The certificate + secret can be mounted by configuring the `extraVolumes` and `extraVolumeMounts` + values. + +### Extending the supported Helm repository protocols + +By default, the Helm Operator is able to pull charts from repositories using +HTTP/S. It is however possible to extend the supported protocols by making use +of a [Helm downloader plugin](https://helm.sh/docs/topics/plugins/#downloader-plugins), +this allows you for example to use charts hosted on [Amazon S3](https://github.com/hypnoglow/helm-s3) +or [Google Cloud Storage](https://github.com/hayorov/helm-gcs). + +#### Installing a Helm downloader plugin + +The easiest way to install a plugin so that it becomes accessible to the Helm +operator to use an [init container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) +and one of the available `helm` binaries in the Helm Operator's image and a +volume mount. For the Helm chart, +[refer to the chart the documentation](../references/chart.md#use-helm-downloader-plugins). + +**Plugin folder paths per Helm version:** + + +| Version | Plugins | Config | +|---------|---------------------------------|-----------------------------------| +| Helm 2 | `/var/fluxd/helm/cache/plugins` | `/var/fluxd/helm/plugins` | +| Helm 3 | `/root/.cache/helm/plugins` | `/root/.local/share/helm/plugins` | + +Add a volume entry of [type `emptyDir`](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) +to the deployment of your Helm Operator, this is where the plugins will be +stored for the lifetime duration of the pod: + +```yaml +spec: + volumes: + - name: helm-plugins-cache + emptyDir: {} +``` + +Next, add a new init container that uses the same image as the Helm +operator's container, and makes use of the earlier mentioned volume, with +correct volume mounts for the Helm version you are making use of. The +available `helm2` and `helm3` binaries can then be used to install the plugin: + +```yaml +spec: + initContainers: + - name: helm-3-downloader-plugin + image: docker.io/fluxcd/helm-operator: + imagePullPolicy: IfNotPresent + command: + - 'sh' + - '-c' + # Replace '' and '' with the respective + # values of the plugin you want to install + - 'helm3 plugin install --version ' + volumeMounts: + - name: helm-plugins-cache + # See: 'plugin folder paths per Helm version' + mountPath: /root/.cache/helm/plugins + subPath: v3 + - name: helm-plugins-cache + # See: 'plugin folder paths per Helm version' + mountPath: /root/.local/share/helm/plugins + subPath: v3-config +``` + +Last, add the same volume mounts to the Helm Operator container so that the +downloaded plugin becomes available: + +```yaml +spec: + containers: + - name: flux-helm-operator + image: docker.io/fluxcd/helm-operator: + ... + volumeMounts: + - name: helm-plugins-cache + # See: 'plugin folder paths per Helm version' + mountPath: /root/.cache/helm/plugins + subPath: v3 + - name: helm-plugins-cache + # See: 'plugin folder paths per Helm version' + mountPath: /root/.local/share/helm/plugins + subPath: v3-config +``` + +#### Using an installed protocol in your HelmRelease + +Once a Helm downloader plugin has been successfully installed, the newly added +protocol can be used in the `.chart.repository` value of a `HelmRelease`: + +```yaml +spec: + chart: + repository: s3://bucket-name/charts + name: chart-name + version: 1.0.0 +``` + +!!! caution + Most downloader plugins expect some form of credentials to be present to be + able to download a chart, make sure those are available in the Helm + operator's container before attempting to make use of the newly added + protocol. + +## Git repositories + +Besides the extensive support for Helm repositories, the Helm Operator also +offers support for charts from Git repository sources. You can refer to a chart +from a _Git_ repository, rather than a Helm repository, with a `.chart` section +like this: + +```yaml +spec: + chart: + git: git@github.com:org/repo + ref: master + path: charts/podinfo +``` + +The definition of the listed keys is as follows: + +* `git`: The URL of the Git repository, e.g. `git@github.com:org/repo` or + `https://github.com/org/repo.git`. + + **Note:** specifying a custom port only works when the protocol is specified, + e.g. `ssh://git@github.com:2222/org/repo.git` and not `git@github.com:2222/org/repo`. +* `ref` _(Optional)_: The Git reference, e.g. a branch, tag, or (short) commit + hash. When omitted, defaults to `master` or the configured `--git-default-ref`. +* `path`: The path of the chart relative to the root of the Git repository. + +In this case, the Helm Operator will start a mirror for the Git repository, and +a temporary working clone at the current `HEAD` of the defined `ref` of the +mirror will be created, before performing a release with the `path` given. + +Mirrored Git repositories are polled for changes by fetching from the upstream +on the configured `--git-poll-interval` (defaults to 5 minutes). When a change +is detected the Helm Operator will collect all `HelmRelease` resources making +use of the mirror, and inspect if the change updates the chart at the `path` +given. When this is true, it will schedule a new release and an upgrade will +follow. + +When a temporary working clone cannot be created due to e.g. the mirror not +being available yet or a cloning failure because of missing [credentials](#authentication), +a status condition of type `ChartFetched` will be recorded on the `HelmRelease` resource with the +returned error. + +!!! note + You can pin a chart to a specific version by changing the `.ref` to a tag + or commit hash. + +### Authentication + +Unauthenticated cloning from Git repositories is possible for public Git +repositories by making the Helm Operator fetch them over HTTP/S. It is +however likely that most of the time you will be using a Git repository +chart source, some form of authentication is required before the repository +can be accessed by the Helm Operator. + +!!! tip + Because the Helm Operator does not perform any write operations on the Git + repository, credentials with read permissions are always sufficient. + +#### SSH + +For Git over SSH the Helm Operator makes use of private keys available in the +container. Because of this, any `HelmRelease` under the management of a +Helm Operator instance has access to the same repositories once a private key +has been provided and no additional configuration is required for the resource +itself other than defining the Git repository in the `.chart.repo`. + +To provide a private key to be used for Git operations over SSH, put the key in +a secret under the entry `identity`: + +```sh +kubectl create secret generic flux-git-deploy \ + --from-file=identity= +``` + +Next, mount it into the Helm Operator container as shown in the +[example deployment](https://github.com/fluxcd/helm-operator/blob/{{ version }}/deploy/deployment.yaml). + +The default `ssh_config` that ships with the Helm Operator's Docker image +expects an identity file at `/etc/fluxd/ssh/identity`, which is where it will +be if you just uncomment the blocks from the example. + +##### Providing multiple private keys + +If you are using more than one repository, you may need to provide more than +one private key. In that case, you can create a secret with an entry for each +key and mount that _as well as_ an `ssh_config` file mentioning each key as an +`IdentityFile` in `/root/.ssh`. + +For example, to provide different credentials for `github.com` and +`bitbucket.org` you would create a `ssh_config` file looking like this: + +```text +Host github.com + HostName github.com + User git + IdentityFile + IdentitiesOnly yes + +Host bitbucket.org + HostName bitbucket.org + User git + IdentityFile + IdentitiesOnly yes +``` + +!!! note + The `IdentitiesOnly` ensures that only the `IdentityFile` for the + `Host` is used and any other identity files known are ignored. + +###### Multiple private keys for Git repositories on the same host + +There is one caveat to the example illustrated above; due to the fact that +permissions are being handled by the Git server and not SSH itself, any public +key known to the Git server will result in a successful login while the private +counterpart it belongs to may not actually have access to the Git repository +that is targeted. This poses a problem when you have multiple repositories on +the same Git server with a dedicated private key per repository. + +The workaround is to use an alias for the `Host` value, and then use this as a +replacement for the hostname in the defined Git repository URL of the +`HelmRelease`: + +```text +Host github-repository1 + HostName github.com + User git + IdentityFile + IdentitiesOnly yes +``` + +```yaml +spec: + chart: + git: git@github-repository1:org/repo + ref: master + path: charts/podinfo +``` + +#### HTTPS + +For Git over HTTPS the Helm Operator offers two ways of providing credentials. + +##### Per-resource credentials using .chart.secretRef + +To provide HTTPS credentials per `HelmRelease` resource you can make use of +a `secretRef` in the `.chart` and a secret with a username and password. +The defined secret is retrieved from Kubernetes and appended to the +`.chart.git` URL before starting the Git mirror. + +First, create a secret with the `username` and `password` that give access +to the Git repository: + +```sh +kubectl create secret generic git-https-credentials \ + --from-literal=username= \ + --from-literal=password= +``` + +Now, add the reference to the secret to the `.chart`: + +```yaml +spec: + chart: + git: https://github.com/org/repo + ref: master + path: charts/podinfo + secretRef: + name: git-https-credentials +``` + +##### Global credentials using .netrc + +It is also possible to provide `HelmRelease` resources access to global +credentials via a +[`.netrc` file](https://ec.haxx.se/usingcurl/usingcurl-netrc) mounted in the +`/root/` directory of the Helm Operator container. + +!!! caution + This approach suffers essentially from [the same caveat as mentioned for + Git over SSH](#multiple-private-keys-for-git-repositories-on-the-same-host). + +To provide credentials for `github.com`, you would create a `.netrc` file like +this: + +```text +machine github.com +login +password +``` + +After mounting the file from a secret, you can then define the plain HTTPS URL +of the Git repository in your `HelmRelease`: + +```yaml +spec: + chart: + git: https://github.com/org/repo.git + ref: master + path: charts/podinfo +``` + +### Dependency updates + +For a chart from a Git repository the Helm Operator runs a dependency update +by default, this is done through an action that equals to `helm dep update`. +You may want to disable this behaviour, for example because your dependencies +are already in git, to do so set `skipDepUpdate` to `true` in `.chart`: + +```yaml +spec: + chart: + git: git@github.com:org/repo + ref: master + path: charts/podinfo + skipDepUpdate: true +``` + +### Notifying the Helm Operator about Git changes + +As earlier laid out in this guide the Helm Operator fetches the upstream of +mirrored Git repositories on the configured `--git-poll-interval` (defaults +to 5 minutes). In some scenarios (think CI/CD), you may not want to wait for +this interval to pass. + +To help you with this the Helm Operator serves a HTTP API endpoint to +instruct it to immediately refresh all Git mirrors: + +```console +$ kubectl port-forward deployment/flux-helm-operator 3030:3030 & +$ curl -XPOST http://localhost:3030/api/v1/sync-git +OK +``` + +!!! warning + The HTTP API has no built-in authentication, this means you either need to + port forward before making the request or put something in front of it to + serve as a gatekeeper. diff --git a/docs/helmrelease-guide/debugging.md b/docs/helmrelease-guide/debugging.md new file mode 100644 index 000000000..39c43690e --- /dev/null +++ b/docs/helmrelease-guide/debugging.md @@ -0,0 +1,54 @@ +# Debugging + +Even after having read everything this guide has to offer it is possible that a +`HelmRelease` fails and you want to debug it to get to the cause. This may be +a bit harder at first than you were used to while working with just `helm` +because you are no longer in direct control but the Helm Operator is doing the +work for you. + +This last section of the guide will give you some pointers on how to debug a +failing `HelmRelease` resource. + +## Getting the reason of failure + +If a release fails the reason of failure will be logged in the Helm Operator's +logs _and_ recorded as a condition on the `HelmRelease` resource. You can view +this condition by describing the `HelmRelease` resource using `kubectl`: + +```console +kubectl describe -n helmrelease/ +``` + +In case of a release upgrade failure, the error as returned by Helm will be +recorded in the message of `HelmUpgradeFailed`. If this does not give a +conclusive answer the logs will likely contain more information about what +happened during the release process: + +```console +kubectl logs deploy/flux-helm-operator +``` + +## Manually performing a release to debug + +When describing the `HelmRelease` and the logs did not give any clues, it may +help to perform the release manually using the same values as specified in the +`HelmRelease` resource. When no `.valuesFrom` are defined, this can be done +by making use of [`yq`](https://github.com/kislyuk/yq) (an extension to `jq`) +and `kubectl`: + +```console +kubectl get helmrelease/ -n -o yaml | yq .spec.values -y | helm upgrade -i -f - +``` + +## Getting Help + +If you still have any questions about the Helm Operator: + +- Invite yourself to the CNCF community + slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/) + channel. +- To be part of the conversation about Helm Operator's development, join the + [flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev). +- [File an issue.](https://github.com/fluxcd/helm-operator/issues/new) + +Your feedback is always welcome! \ No newline at end of file diff --git a/docs/helmrelease-guide/introduction.md b/docs/helmrelease-guide/introduction.md new file mode 100644 index 000000000..726c54860 --- /dev/null +++ b/docs/helmrelease-guide/introduction.md @@ -0,0 +1,102 @@ +# Introduction + +The intention of this guide is to give you more detailed information on various +elements of the `HelmRelease` Custom Resource. You can follow it in one take, +use it as a more explanatory reference, or a combination of both. + +It assumes you have the Helm Operator already installed in your cluster. If +you have not done this yet, [follow the installation instructions from the +quickstart](../get-started/quickstart.md#install-the-helm-operator) + +The guide tries not to presume a specific enabled Helm version but for the sake +of simplicity it was written while making use of Helm 3. + +## A minimal HelmRelease + +To get started, we will first create the most minimal `HelmRelease` possible. +We will use (parts) of this minimal `HelmRelease` as an example throughout the +rest of this guide. + +```yaml +# podinfo.yaml +--- +apiVersion: helm.fluxcd.io/v1 +kind: HelmRelease +metadata: + name: podinfo + namespace: default +spec: + chart: + repository: https://stefanprodan.github.io/podinfo + name: podinfo + version: 3.2.0 +``` + +The `spec.chart` object is the only mandatory property of the `HelmRelease` +and defines the Helm chart that should be installed by the Helm Operator. This +`HelmRelease` will manage [`stefanprodan/podinfo`](https://github.com/stefanprodan/podinfo) + +> a tiny web application made with Go that showcases best practices of running +> microservices in Kubernetes + +from a [Helm repository chart source](chart-sources.md#helm-repositories). + +Applying this to the cluster and making the Helm Operator do the release is +equivalent to equals to a human running the following `helm` commands: + +```console +$ helm repo add podinfo https://stefanprodan.github.io/podinfo +$ helm upgrade -i default-podinfo podinfo/podinfo --version '3.2.0' +``` + +A couple of differences between the `HelmRelease` resource and listed `helm` +commands should stand out: + +1. The `HelmRelease` does not make use of a repository alias, instead the + absolute URL of the Helm repository is used.

+ This is to ensure the `HelmRelease` is able to stand on its own. If we used + names in the spec, which were resolved to URLs elsewhere (e.g., in a + `repositories.yaml` supplied to the operator), it would be possible to + change the meaning of a `HelmRelease` without altering it. This is + undesirable because it makes it hard to specify exactly what you want, in + the one place; or to read exactly what is being specified, in the one place. +1. The `spec.chart.version` is mandatory.

+ The reasoning behind this is the same as the explanation given above. +1. The default release name used by the Helm Operator is composed from the + `metadata.namespace` and the `metadata.name` of the `HelmRelease` resource + (`-`).

+ This to ensure it does not collide with other `HelmRelease` resources that + may have the same `.metadata.name` but different namespace definitions. + +Having absorbed this information, you can now go ahead and apply the resource +using `kubectl`: + +```console +$ kubectl apply -f podinfo.yaml +``` + +Take a look at the logs of the Helm Operator deployment and you will see the +Helm installation was performed almost instantly after applying the resource: + +```console +$ kubectl logs deploy/flux-helm-operator +... +ts=2020-01-01T12:00:00.000000000Z caller=release.go:335 component=release release=default-podinfo targetNamespace=default resource=default:helmrelease/podinfo helmVersion=v3 info="no existing release" action=install +ts=2020-01-01T12:00:00.000000000Z caller=helm.go:69 component=helm version=v3 info="creating 2 +resource(s)" targetNamespace=default release=default-podinfo +ts=2020-01-01T12:00:00.000000000Z caller=release.go:266 component=release release=default-podinfo targetNamespace=default resource=default:helmrelease/podinfo helmVersion=v3 info="Helm release sync succeeded" revision=3.2.0 +$ kubectl get helmrelease +NAME RELEASE STATUS MESSAGE AGE +podinfo default-podinfo deployed Helm release sync succeeded 10s +``` + +As expected, the release will now also show up for e.g. `helm list`: + +```console +$ helm list +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +default-podinfo default 1 2020-01-01 12:00:00.000000000 +0000 UTC deployed podinfo-3.2.0 3.2.0 +``` + +Congratulations! You made your first Helm release using a `HelmRelease` +resource. diff --git a/docs/helmrelease-guide/reconciliation-and-upgrades.md b/docs/helmrelease-guide/reconciliation-and-upgrades.md new file mode 100644 index 000000000..259c3466a --- /dev/null +++ b/docs/helmrelease-guide/reconciliation-and-upgrades.md @@ -0,0 +1,73 @@ +# Reconciliation and upgrades + +Now that you know the ins and outs of configuring a release, we are going to +have a better look at how the Helm Operator performs the actual Helm release. + +## Reconciliation + +On the creation and update of a `HelmRelease` the resource is queued for +reconciliation. Besides this all `HelmRelease` resources handled by the Helm +operator instance are also queued for reconciliation every +[`--charts-sync-interval`](../references/operator.md) (defaults to 3 +minutes). + +Once the queued resource has been picked up by a worker, the Helm Operator +attempts to receive the chart for the resource and performs several [safe guard +checks](#what-triggers-an-upgrade); if those do not result in an error or +instruct to return early, the Helm installation or upgrade is performed. + +## What triggers an upgrade + +To prevent spurious upgrades from happening the Helm Operator performs several +safe guard checks before performing the actual upgrade. Bellow you will find an +overview of the checks it performs, and what effect they have. + +If any of the following equals to `false`, the sync process will exit with an +error and no upgrade will be performed: + +1. The values composed of the merged `.valuesFrom` and `.values` are valid + YAML. +1. The resources of the Helm release are [marked as being managed by the + `HelmRelease`](#the-antecedent-annotation). +1. The current state of the Helm release is `deployed`. + +The first of the following that equals to `true` will result in an upgrade +being performed, otherwise no action is taken: + +1. No Helm release exists in the Helm storage for the `HelmRelease`. +1. This generation of the `HelmRelease` has not been processed before — + the generation changes for example when the `.spec` is edited. +1. The result of a dry-run upgrade for the `HelmRelease` differs from the + latest release in the Helm storage. + +!!! note + Mutations to live cluster-state are not detected and thus not + reverted. This will however be added in the foreseeable future. + +## Upgrade failures + +When an upgrade fails, the Helm Operator will stop performing upgrades for the +release as it cannot assume this is a safe procedure, nor does it +automatically perform [a rollback](rollbacks.md). Instead it will start logging +warnings about the `failed` status of the release. + +Recovering from this is possible, after having inspected the state of the +release, by getting the Helm release manually in a `deployed` state, for +example by performing a rollback or upgrade for the release using `helm`: + +```console +helm rollback +``` + +## The antecedent annotation + +Right after the Helm Operator performs a Helm release for the +`HelmRelease` resource, all resources that were the result of this release +are annotated with the antecedent annotation `helm.fluxcd.io/antecedent`, +the value of the annotation equals to `:helmrelease/`. + +The purpose of this annotation is to indicate that the cause of that resource +is a `HelmRelease`. It also functions as a safe guard during reconciliation +to ensure the release is only managed by a single `HelmRelease`, as it is +possible that due to a misconfiguration multiple `HelmRelease` resources exist +with the same `.releaseName` set. diff --git a/docs/helmrelease-guide/release-configuration.md b/docs/helmrelease-guide/release-configuration.md new file mode 100644 index 000000000..47818f162 --- /dev/null +++ b/docs/helmrelease-guide/release-configuration.md @@ -0,0 +1,134 @@ +# Release configuration + +When making use of the `helm` binary you can pass along various flags while +making a release that influence how a release is performed. Most of these flags +are also available as parameters in the `spec` of the `HelmRelease` resource, +others are not available for `helm` but fine-tune how the Helm Operator itself +functions. + +This section of the guide documents the parameters, and the effect they have +when the Helm Operator performs a release for the `HelmRelease` they are +configured on. + +## Targeting a Helm version + +When you install the Helm Operator with multiple Helm versions enabled, the +lowest enabled version is targeted by default. To target another version or to +ensure it does not accidentally target the wrong version due to a configuration +mistake, you can set the `.helmVersion`: + +```yaml +spec: + helmVersion: v3 +``` + +## Configuring a target namespace + +It is possible to target a different namespace for the release than the +`HelmRelease` lives in using `.targetNamespace`. This can come in handy when +you have to deploy releases into a namespace that is also managed by another +team running their own namespace-restricted Helm Operator in this same +namespace: + +```yaml +spec: + targetNamespace: team-a +``` + +## Specifying a release name + +The default release name used by the Helm Operator is a composition of the +following values: + +```text +-[-] +``` +This format was invented for Helm 2 to ensure release names from +`HelmRelease` resources in different namespaces would never accidentally +collide with each if they would have the same name, as release names +[were not scoped in this version like they are in Helm 3]( +https://helm.sh/docs/faq/#release-names-are-now-scoped-to-the-namespace), +and it still serves this purpose when a target namespace is defined. + +In some situations you may want to overwrite this generated release name, for +example because you want to take over a release made with `helm`. This is +possible by declaring a `.releaseName` which will replace the generated format: + +```yaml +spec: + releaseName: podinfo +``` + +## Forcing resource updates + +When a chart contains a breaking upgrade, you may need to force resource updates +through the replacement strategy of Helm, this is possible by setting +`.forceUpgrade`: + +```yaml +spec: + forceUpgrade: true +``` + +## Resetting values during upgrade + +To ignore any previous used values for a release and make Helm use the values +as they are in the `values.yaml` file of the Helm chart used, you can set +`.resetValue`. You will likely want to use this when you have removed +overriding `.values` from your `HelmRelease`: + +```yaml +spec: + resetValues: true +``` + +## Configuring the timeout + +To configure how many seconds Helm should wait for any individual Kubernetes operations +you can set `.timeout`, the default is `300`: + +```yaml +spec: + timeout: 300 +``` + +!!! warning + When your chart requires a high non-default `timeout` value it is advised + to increase the `teriminationGracePeriod` on the Helm Operator pod to not + end up with a release in a faulty state due to the operator receiving a + `SIGKILL` signal during an upgrade. + +## Wait for resources to be ready + +!!! note + When you have many `HelmRelease` resources with the `.wait` flag + set, it is likely that you want to increase the amount of `--workers` to + ensure other releases are still processed, given the waiting process blocks + the worker from processing other `HelmRelease` resources. + +Normally Helm will mark a release as successfully deployed as soon as the +changes have been applied to the cluster. To instruct Helm to wait until +all resources are in ready state before marking the release as successful +you can set `.wait`. When set, it will wait for as long as +[`.timeout`](#configuring-the-timeout): + +```yaml +spec: + wait: true +``` + +## Configuring the max number of revision saved + +!!! note + Setting this only has effect for a `HelmRelease` targeting Helm 3. + You can configure a global history limit for Helm 2 by [passing `--history-max + ` to `helm init`](https://v2.helm.sh/docs/using_helm/#initialize-helm-and-install-tiller). + +To configure the maximum number of revision saved by Helm for a `HelmRelease`, +you can set `.maxHistory`. Use `0` for an unlimited number of revisions; +defaults to `10`: + +```yaml +spec: + maxHistory: 10 +``` diff --git a/docs/helmrelease-guide/rollbacks.md b/docs/helmrelease-guide/rollbacks.md new file mode 100644 index 000000000..e2807fb02 --- /dev/null +++ b/docs/helmrelease-guide/rollbacks.md @@ -0,0 +1,86 @@ +# Rollbacks + +From time to time a release made by the Helm Operator may fail, this section +of the guide will explain how you can recover from a failed release by enabling +rollbacks. + +!!! caution + Rollbacks of Helm charts containing `StatefulSet` resources can be a + tricky operation, and are one of the main reasons automated rollbacks are not + enabled by default. Verify a manual rollback (using `helm`) of your Helm + chart does not cause any problems before enabling it. + +## Enabling rollbacks + +When rollbacks for a `HelmRelease` are enabled, the Helm Operator will detect +a faulty upgrade and instruct Helm to perform a rollback, it will not attempt +a new upgrade unless it detects a change in values and/or the chart, or [retries +have been enabled](#enabling-retries-of-rolled-back-releases). Changes are +detected by comparing the failed release to a fresh dry-run release. + +Rollbacks can be enabled by setting `.rollback.enable`: + +```yaml +spec: + rollback: + enable: true +``` + +## Tweaking the rollback configuration + +To get more fine-grained control over how the rollback is performed by Helm, +the `.rollback` of the `HelmRelease` resources offers a couple of additional +settings. + +```yaml +spec: + rollback: + enable: true + disableHooks: false + force: false + recreate: false + timeout: 300 +``` + +The definition of the listed keys is as follows: + +* `enable`: Enables the performance of a rollback when a release fails. +* `disableHooks` _(Optional)_: When set to `true`, prevent hooks from running + during rollback. Defaults to `false` when omitted. +* `force` _(Optional)_: When set to `true`, force resource update through + delete/recreate if needed. Defaults to `false` when omitted. +* `recreate` _(Optional)_: When set to `true`, performs pods restart for the + resource if applicable. Defaults to `false` when omitted. +* `timeout` _(Optional)_: Time to wait for any individual Kubernetes operation + during rollback in seconds. Defaults to `300` when omitted. + +!!! warning + When your chart requires a high non-default `timeout` value it is advised + to increase the `teriminationGracePeriod` on the Helm Operator pod to not + end up with a release in a faulty state due to the operator receiving a + `SIGKILL` signal during an upgrade. + +## Enabling retries of rolled back releases + +Sometimes the cause of an upgrade failure may be transient. To guard yourself +against this it is possible to instruct the Helm Operator to retry the upgrade +of a rolled back release by setting `.rollback.retry` to `true`. This will +cause the Helm Operator to retry the upgrade until the `.rollback.maxRetries` +is reached: + +```yaml +spec: + rollback: + enable: true + retry: true + maxRetries: 5 +``` + +The definition of the listed keys is as follows: + +* `enable`: Enables the performance of a rollback when a release fails. +* `retry` _(Optional)_: When set to `true`, retries the upgrade of a failed + release until `maxRetries` is reached. Defaults to `false` when omitted. +* `maxRetries` _(Optional)_: The maximum amount of retries that should be + attempted for a rolled back release. Defaults to `5` when omitted, use `0` + for an unlimited amount of retries. diff --git a/docs/helmrelease-guide/values.md b/docs/helmrelease-guide/values.md new file mode 100644 index 000000000..347ac1bd8 --- /dev/null +++ b/docs/helmrelease-guide/values.md @@ -0,0 +1,144 @@ +# Values + +Now that we have a good understanding of where we can get our charts from and +what they have to offer, it is time to examine how you can supply +[values](https://helm.sh/docs/glossary/#values-values-files-values-yaml) to +be used with the chart when the Helm Operator makes a release. + +### Inlined values + +The most simple option to define the values for your Helm release. This is a +YAML map as you would put in a file and supply to Helm with `-f values.yaml`, +but inlined into the `HelmRelease` manifest. For example: + +```yaml +spec: + values: + foo: value1 + bar: + baz: value2 + oof: + - item1 + - item2 +``` + +## Values from sources + +It is possible to define a list of config maps, secrets (in the same namespace +as the `HelmRelease` by default, or in a configured namespace) or external +sources (URLs) from which to take values. For charts from a Git +repository, there is an additional option available to refer to a file in +the chart folder. + +The values are merged in the order given, with later values overwriting +earlier. These values always have a lower priority than the values +inlined in the `HelmRelease` via the `spec.values` parameter. + +This is useful if you want to have defaults such as the `region`, +`clustername`, `environment`, a local docker registry URL, etc., or if you +simply do not want the values to be visible as plaintext in the `HelmRelease`. + +!!! note + The Helm Operator does not watch the sources for updates. Changes to + sources are detected during the [reconciliation + loop](reconciliation-and-upgrades.md#reconciliation). + +### Config maps + +The reference to a config map is defined by adding a `configMapKeyRef` to the +`spec.valuesFrom` list. + +```yaml +spec: + valuesFrom: + - configMapKeyRef: + name: default-values + namespace: my-ns + key: values.yaml + optional: false +``` + +The definition of the listed keys is as follows: + +- `name`: The name of the config map. +- `namespace` _(Optional)_: The namespace the config map is in. Defaults to the + namespace of the `HelmRelease` when omitted. +- `key` _(Optional)_: The key in the config map to get the values from. + Defaults to `values.yaml` when omitted. +- `optional` _(Optional)_: When set to `true`, successful retrieval of the + config map is optional and a release will still be made if it is missing. + Defaults to `false` when omitted. + +### Secrets + +The reference to a secret is defined by adding a `secretKeyRef` to the +`spec.valuesFrom` list. + +```yaml +spec: + valuesFrom: + - secretKeyRef: + name: default-values + namespace: my-ns + key: values.yaml + optional: true +``` + +The definition of the listed keys is as follows: + +- `name`: The name of the config map. +- `namespace` _(Optional)_: The namespace the secret is in. Defaults to the + namespace of the `HelmRelease` when omitted. +- `key` _(Optional)_: The key in the secret to get the values from. + Defaults to `values.yaml` when omitted. +- `optional` _(Optional)_: When set to `true`, successful retrieval of the + secret is optional and a release will still be made if it is missing. + Defaults to `false` when omitted. + +### External sources + +The reference to an external source (URL) is defined by adding a +`externalSourceRef` to the `spec.valuesFrom` list. The external +source is expected to be a plain YAML file. + +```yaml +spec: + valuesFrom: + - externalSourceRef: + url: https://example.com/static/raw/values.yaml + optional: true +``` + +The definition of the listed keys is as follows: + +- `url`: The URL of the plain YAML file. +- `optional` _(Optional)_: When set to `true`, successful retrieval of the + YAML file is optional and a release will still be made if it could not be + found. Defaults to `false` when omitted. + +### Chart files + +!!! note + Values from chart files are only supported for charts from a [Git + repository](chart-sources.md#git-repositories). + +When making use of a chart sourced from a Git repository, it is possible to +refer to a values file relative to the path of the chart. This can for example +be utilized to select values optimized for production environments, that you ship +with your chart. + +```yaml +spec: + valuesFrom: + - chartFileRef: + path: overrides/environment-prod.yaml + optional: true +``` + +The definition of the listed keys is as follows: + +- `path`: The path relative to the `.chart.path` where the values file can be + found. +- `optional` _(Optional)_: When set to `true`, successful retrieval of the + YAML file is optional and a release will still be made if it could not be + found. Defaults to `false` when omitted. diff --git a/docs/how-to/upgrade-to-beta.md b/docs/how-to/upgrade-to-beta.md new file mode 100644 index 000000000..f547779d6 --- /dev/null +++ b/docs/how-to/upgrade-to-beta.md @@ -0,0 +1,153 @@ +# Upgrade from alpha (<=0.4.0) to beta + +The Helm Operator has undergone changes that necessitate some changes +to custom resources, and the deployment of the operator itself. + +The central difference is that the Helm Operator now works with +resources of the kind `HelmRelease` in the API version +`flux.weave.works/v1beta1`, which have a different format to the +custom resources used by the old Helm Operator (`FluxHelmRelease`). + +Here are some things to know: + +- The new operator will ignore the old custom resources (and the old + operator will ignore the new resources). +- Deleting a resource while the corresponding operator is running + will result in the Helm release also being deleted +- Deleting a `CustomResourceDefinition` will also delete all + custom resources of that kind. +- If both operators are running and both new and old custom resources + defining a release, the operators will fight over the release. + +The safest way to upgrade is to avoid deletions and fights by stopping +the old operator. Replacing it with the new one (e.g., by changing the +deployment, or re-releasing the Flux chart with the new version) will +have that effect. + +Once the old operator is not running, it is safe to deploy the new +operator, and start replacing the old resources with new +resources. You can keep the old resources around during this process, +since the new operator will ignore them. + +## Upgrading the operator deployment + +### Using the Flux chart + +The chart (from v0.5.0, or from this git repo) provides the +correct arguments to the operator; to upgrade, do + +```sh +helm repo update + +helm upgrade flux --reuse-values \ +--set image.tag=1.8.1 \ +--set helmOperator.tag=0.5.1 \ +--namespace=flux \ +fluxcd/flux --version 0.5.1 +``` + +The chart will leave the old custom resource definition and custom +resources in place. You will need to replace the individual resources, +as described below. + +### Using manifests + +You will need to adapt any existing manifest that you use to run the +Helm Operator. The arguments to the operator executable have changed, +since it no longer needs the git repo to be specified (and in some +cases, just to tidy up): + +- the new operator does not use the `--git-url`, `--git-charts-path`, + or `--git-branch` arguments, since the git repo and so on are + provided in each custom resource. +- the `--queue-worker-count` argument has been removed +- the `--chart-sync-timeout` argument has been removed +- other arguments stay the same + +It is entirely valid to run the operator with no arguments, which you +may end up with after removing those mentioned above. It will work +with the secrets mounted as for the old operator, to start off with, +since it expects the SSH key for the git repo to be in the same place. + +Once you want to use the new capabilities of the operator -- e.g., +releasing charts from Helm repos -- you will probably need to adapt +the manifest further. The [`HelmRelease` Custom Resource](../references/helmrelease-custom-resource.md) +and [operator](../references/operator.md) references explain all +the details. + +## Updating custom resources + +The main differences between the old resource format and the new are: + +- the API version and kind have changed +- you can now specify a chart to release either as a path in a git + repo, or a named, versioned chart from a Helm repo + +Here is how to change an old resource to a new resource: + +- change the `apiVersion` field to `flux.weave.works/v1beta1` +- change the `kind` field to `HelmRelease` +- you can remove the label `chart:` from the labels, if it's still + there, just to tidy up (it doesn't matter if it's there or not) +- replace the field `chartGitPath`, with the structure: + +```yaml +chart: + git: + ref: + path: +``` + +- the `values`, `releaseName`, and `valueFileSecrets` can stay as + they are. + +Note that you now give the git repo URL and branch and full path in +each custom resource, rather than supplying arguments to the Helm +operator. (As you've been using the old operator, you'll only have one +git repo for all charts -- but now you can use different repos for +charts!) + +As a full example, this is an old resource: + +```yaml +--- +apiVersion: helm.integrations.flux.weave.works/v1alpha2 +kind: FluxHelmRelease +metadata: + name: foobar + namespace: foo-ns +spec: + chartGitPath: foobar + values: + image: + repository: foobar + tag: v1 +``` + +Say the arguments given to the old Helm Operator were + +```yaml +args: + - --git-url=git@example.com:user/repo + - --git-charts-path=charts + - --git-branch=master +``` + +Then the new custom resource would be: + +```yaml +--- +apiVersion: flux.weave.works/v1beta1 # <- change API version +kind: HelmRelease # <- change kind +metadata: + name: foobar + namespace: foo-ns +spec: + chart: + git: git@example.com:user/repo # <- --git-url from operator args + path: charts/foobar # <- join --git-chart-path and chartGitPath + values: + image: + repository: foobar + tag: v1 +``` diff --git a/docs/how-to/upgrade-to-ga.md b/docs/how-to/upgrade-to-ga.md new file mode 100644 index 000000000..8c773244d --- /dev/null +++ b/docs/how-to/upgrade-to-ga.md @@ -0,0 +1,101 @@ +# Upgrade from beta (>=0.5.0) to stable (>=1.0.0) + +Due to the Flux CD project joining the CNCF Sandbox and the API +becoming stable, the Helm Operator has undergone changes that +necessitate some changes to your `HelmRelease` resources. + +The central difference is that the Helm Operator now works with +resources of the kind `HelmRelease` in the API version +`helm.fluxcd.io/v1`, the format of the resource is backwards +compatible. + +Here are some things to know: + +- The new operator will ignore the old custom resources (and the old + operator will ignore the new resources). +- Deleting a resource while the corresponding operator is running + will result in the Helm release also being deleted +- Deleting a `CustomResourceDefinition` will also delete all + custom resources of that kind. +- If both operators are running and both new and old custom resources + defining a release, the operators will fight over the release. + +The safest way to upgrade is to avoid deletions and fights by stopping +the old operator. Replacing it with the new one (e.g., by changing the +deployment, or re-releasing the Flux chart with the new version) will +have that effect. + +Once the old operator is not running, it is safe to deploy the new +operator, and start replacing the old resources with new +resources. You can keep the old resources around during this process, +since the new operator will ignore them. + +## Updating custom resources + +!!! note + Once the new CRD is applied it is no longer possible to list your old + and new `HelmRelease` resources with just + `kubectl get ` due to them sharing the same names. It + is however still possible to list them by their full name: + + ```console + # Old HelmRelease resources + kubectl get helmreleases.flux.weave.works + + # New HelmRelease resources + kubectl get helmreleases.helm.fluxcd.io + ``` + +The only difference between the old resource format and the new is +the changed API version. + +Changing an old resource to a new resource is thus as simple as +changing the `apiVersion` field to `helm.fluxcd.io/v1`. + +As a full example, this is an old resource: + +```yaml +--- +apiVersion: flux.weave.works/v1beta1 +kind: HelmRelease +metadata: + name: foobar + namespace: foo-ns +spec: + chart: + git: git@example.com:user/repo + path: charts/foobar + values: + image: + repository: foobar + tag: v1 +``` + +The new custom resource would be: + +```yaml +--- +apiVersion: helm.fluxcd.io/v1 # <- change API version +kind: HelmRelease +metadata: + name: foobar + namespace: foo-ns +spec: + chart: + git: git@example.com:user/repo + path: charts/foobar + values: + image: + repository: foobar + tag: v1 +``` + +## Deleting the old resources + +Once you have migrated all your `HelmRelease` resources to the new API +version and domain. You can remove all of the old resources by removing +the old Custom Resource Definition. + +```sh +kubectl delete crd helmreleases.flux.weave.works +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..e41158374 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,69 @@ +# Helm Operator + +The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), +allowing one to declaratively manage Helm chart releases. Combined with +[Flux](https://github.com/fluxcd/flux) this can be utilized to automate +releases in a GitOps manner, but the usage of Flux is not a strict +requirement. + +The desired state of a Helm release is described through a Kubernetes +Custom Resource named `HelmRelease`. Based on the creation, mutation or +removal of a `HelmRelease` resource in the cluster, Helm actions are +performed by the operator. + +![Helm Operator](_files/fluxcd-helm-operator-diagram.png) + +## Features + +* Declarative install, upgrade, and delete of Helm releases +* Pulls chart from _any_ chart source; + * Public or private Helm repositories over HTTP/S + * Public or private Git repositories over HTTPS or SSH + * Any other public or private chart source using one of the available + [Helm downloader plugins](https://helm.sh/docs/topics/plugins/#downloader-plugins) +* Allows Helm values to be specified; + * In-line in the `HelmRelease` resource + * In (external) sources, e.g. `ConfigMap` and `Secret` resources, + or a (local) URL +* Automated purging on release install failures +* Automated (optional) rollback on upgrade failures +* Automated image upgrades [using Flux](https://docs.fluxcd.io/en/stable/references/helm-operator-integration.html) +* Automated (configurable) chart dependency updates for Helm charts + from Git sources on install or upgrade +* Detection and recovery from Helm storage mutations + (e.g. a manual Helm release that was made but conflicts with the + declared configuration for the release) +* Parallel and scalable processing of different `HelmRelease` resources + using workers +* Supports both Helm 2 and 3 + +## Get started + +Get started installing the Helm Operator: + +- [Quickstart](get-started/quickstart.md) +- [Get started using Helm](get-started/using-helm.md) +- [Get started using Kustomize](get-started/using-kustomize.md) +- [Get started using YAMLs](get-started/using-yamls.md) + +## Integrations + +As the Helm Operator is Open Source, integrations are very straight-forward. Here are +a few popular ones you might want to check out: + +- [Progressive Delivery workshop](https://helm.workshop.flagger.dev/) +- [Managing Helm releases the GitOps way](https://github.com/fluxcd/helm-operator-get-started) +- [GitOps for Istio Canary deployments](https://github.com/stefanprodan/gitops-istio) + +## Getting Help + +If you have any questions about the Helm Operator and continuous delivery: + +- Invite yourself to the CNCF community + slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/) + channel. +- To be part of the conversation about Helm Operator's development, join the + [flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev). +- [File an issue.](https://github.com/fluxcd/helm-operator/issues/new) + +Your feedback is always welcome! diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 9eac5cdd7..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Helm operator -============= - -.. toctree:: - :maxdepth: 2 - - references/index - guides/index - tutorials/index - - faq - troubleshooting diff --git a/docs/references/chart.md b/docs/references/chart.md new file mode 120000 index 000000000..249466083 --- /dev/null +++ b/docs/references/chart.md @@ -0,0 +1 @@ +../../chart/helm-operator/README.md \ No newline at end of file diff --git a/docs/references/helmrelease-custom-resource.md b/docs/references/helmrelease-custom-resource.md index 23c3c6c64..29b2f3ac1 100644 --- a/docs/references/helmrelease-custom-resource.md +++ b/docs/references/helmrelease-custom-resource.md @@ -1,470 +1,1614 @@ # `HelmRelease` Custom Resource - -Each release of a chart is declared by a `HelmRelease` -resource. The schema for these resources is given in [the custom -resource definition](https://github.com/fluxcd/helm-operator/blob/master/deploy/crds.yaml). They -look like this: - -```yaml -apiVersion: helm.fluxcd.io/v1 -kind: HelmRelease -metadata: - name: rabbit - namespace: default -spec: - releaseName: rabbitmq - targetNamespace: mq - timeout: 300 - resetValues: false - wait: false - forceUpgrade: false - chart: - repository: https://kubernetes-charts.storage.googleapis.com/ - name: rabbitmq - version: 3.3.6 - values: - replicas: 1 -``` - -The `releaseName` will be given to Helm as the release name. If not -supplied, it will be generated by affixing the HR namespace and the -target namespace to the resource name. In the above example, if -`releaseName` were not given, it would be generated as `default-mq-rabbitmq`. -Because of the way Helm works, release names must be unique in the cluster. - -If you don't supply the `targetNamespace`, the release will be installed -in the same namespace as the HelmRelease object. - -The `chart` section gives a pointer to the chart; in this case, to a -chart in a Helm repo. Since the Helm operator is running in your -cluster, and doesn't have access to local configuration, the -repository is given as a URL rather than an alias (the URL in the -example is what's usually aliased as `stable`). The `name` and -`version` specify the chart to release. - -The `timeout` sets the timeout value for the Helm install or upgrade. -If you don't supply it, it is set to 300. - -The `resetValues`, if set to `true`, will reset values on Helm upgrade. - -The `wait`, if set to `true`, will instruct the operator to wait for an -Helm upgrade to complete before it is marked as successful in the -`HelmRelease` resource. - -The `forceUpgrade`, if set to `true`, will force Helm upgrade through delete/recreate - -The `values` section is where you provide the value overrides for the -chart. This is as you would put in a `values.yaml` file, but inlined -into the structure of the resource. See below for examples. - -**Why use URLs to refer to repositories, rather than names?** [^](#cite-why-repo-urls) - -A `HelmRelease` must be able to stand on its own. If we used names -in the spec, which were resolved to URLs elsewhere (e.g., in a -`repositories.yaml` supplied to the operator), it would be possible to -change the meaning of a `HelmRelease` without altering it. This is -undesirable because it makes it hard to specify exactly what you want, -in the one place; or to read exactly what is being specified, in the -one place. In other words, it's better to be explicit. - -## Using a chart from a Git repo instead of a Helm repo - -You can refer to a chart from a _git_ repo, rather than a chart repo, -with a `chart:` section like this: - -```yaml -spec: - chart: - git: git@github.com:fluxcd/flux-get-started - ref: master - path: charts/ghost -``` - -In this case, the git repo will be cloned, and the chart will be -released from the ref given. If not supplied, the operator uses -the value specified by the `--git-default-ref` flag (which -defaults to `master`). Commits to the git repo may result in releases, -if they update the chart at the path given. - -Note that you will usually need to provide an SSH key to grant access -to the git repository. The example deployment shows how to mount a -secret at the expected location of the key (`/etc/fluxd/ssh/`). If you -need more than one SSH key, you'll need to also mount an adapted -ssh_config; this is also demonstrated in the example deployment. - -### Notifying Helm Operator about Git changes - -The Helm Operator fetches the upstream of mirrored Git repositories -with a 5 minute interval. In some scenarios (think CI/CD), you may not -want to wait for this interval to occur. - -To help you with this the Helm Operator serves a HTTP API endpoint to -instruct it to immediately refresh all Git mirrors. - -```sh -$ kubectl -n flux port-forward deployment/flux-helm-operator 3030:3030 & -$ curl -XPOST http://localhost:3030/api/v1/sync-git -OK -``` - -> **Note:** the HTTP API has no built-in authentication, this means you -> either need to port forward before making the request or put something -> in front of it to serve as a gatekeeper. - -## Extending the supported Helm repository protocols - -By default, the Helm operator is able to pull charts from repositories -using HTTP/S. It is however possible to extend the supported protocols -by making use of a [Helm downloader plugin](https://helm.sh/docs/topics/plugins/#downloader-plugins), -this allows you for example to use charts hosted on [Amazon S3](https://github.com/hypnoglow/helm-s3) -or [Google Cloud Storage](https://github.com/hayorov/helm-gcs). - -> **Note:** the operator only offers support for _downloader plugins_, -> other plugins will not be recognized nor used. - -**Plugin folder paths per Helm version:** - -| Version | Plugins | Config -|--------|---------|--- -| Helm 2 | `/var/fluxd/helm/cache/plugins` | `/var/fluxd/helm/plugins` -| Helm 3 | `/root/.cache/helm/plugins` | `/root/.local/share/helm/plugins` - -### Install a Helm downloader plugin - -The easiest way to install a plugin so that it becomes accessible to -the Helm operator to use an [init container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) -and one of the available `helm` binaries in the operator's image and -a volume mount. For the Helm chart of the operator, [see the -documentation](https://github.com/fluxcd/helm-operator/tree/master/chart/helm-operator#use-helm-downloader-plugins). - -#### Using an init container - -Create a volume entry of [type `emptyDir`](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) -to the deployment of your Helm operator, this is where the plugins will -be stored for the lifetime duration of the pod. - -```yaml -spec: - volumes: - - name: helm-plugins-cache - emptyDir: {} -``` - -Add a new init container that utilizes the same image as the operator's -container and makes use of the earlier mentioned volume with correct -volume mounts for the Helm version your are making use of. -The available `helm2` and `helm3` binaries can then be used to install -the plugin. - -```yaml -spec: - initContainers: - - name: helm-3-downloader-plugin - image: docker.io/fluxcd/helm-operator: - imagePullPolicy: IfNotPresent - command: - - 'sh' - - '-c' - # Replace '' and '' with the respective - # values of the plugin you want to install - - 'helm3 plugin install --version ' - volumeMounts: - - name: helm-plugins-cache - # See: 'plugin folder paths per Helm version' - mountPath: /root/.cache/helm/plugins - subPath: v3 - - name: helm-plugins-cache - # See: 'plugin folder paths per Helm version' - mountPath: /root/.local/share/helm/plugins - subPath: v3-config -``` - -Last, add the same volume mounts to the operator's container so the -downloaded plugin becomes available. - -```yaml -spec: - containers: - - name: flux-helm-operator - image: docker.io/fluxcd/helm-operator: - ... - volumeMounts: - - name: helm-plugins-cache - # See: 'plugin folder paths per Helm version' - mountPath: /root/.cache/helm/plugins - subPath: v3 - - name: helm-plugins-cache - # See: 'plugin folder paths per Helm version' - mountPath: /root/.local/share/helm/plugins - subPath: v3-config -``` - -### Using an installed protocol in your `HelmRelease` - -Once a Helm downloader plugin has been successfully installed, the -newly added protocol can be used in the `.spec.chart.repository` -value of a `HelmRelease`. - -> **Note:** most downloader plugins expect some form of authentication -> to be available to be able to download a chart, make sure those are -> available in the operator's container before attempting to make use -> of the newly added protocol. - -```yaml -spec: - chart: - repository: s3://bucket-name/charts - name: chart-name - version: 1.0.0 -``` - -## Supplying values to the chart - -You can supply values to be used with the chart when installing it, in -two ways. - -### `.spec.values` - -This is a YAML map as you'd put in a file and supply to Helm with `-f -values.yaml`, but inlined into the `HelmRelease` manifest. For -example, - -```yaml -apiVersion: helm.fluxcd.io/v1 -kind: HelmRelease -# metadata: ... -spec: - # chart: ... - values: - foo: value1 - bar: - baz: value2 - oof: - - item1 - - item2 -``` - -### `.spec.valuesFrom` - -This is a list of secrets, config maps (in the same namespace as the -`HelmRelease` by default, or in a configured namespace) or external -sources (URLs) from which to take values. - -The values are merged in the order given, with later values -overwriting earlier. These values always have a lower priority than -those passed via the `.spec.values` parameter. - -This is useful if you want to have defaults such as the `region`, -`clustername`, `environment`, a local docker registry URL, etc., or if -you simply want to have values not checked into git as plaintext. - -#### Config maps - -```yaml -spec: - # chart: ... - valuesFrom: - - configMapKeyRef: - # Name of the config map - name: default-values # mandatory - # Namespace of the config map - namespace: my-ns # optional; defaults to HelmRelease namespace - # Key in the config map to get the values from - key: values.yaml # optional; defaults to values.yaml - # If set to true successful retrieval of the values file is no - # longer mandatory - optional: false # optional; defaults to false -``` - -#### Secrets - -```yaml -spec: - # chart: ... - valuesFrom: - - secretKeyRef: - # Name of the secret - name: default-values # mandatory - # Namespace of the secret - namespace: my-ns # optional; defaults to HelmRelease namespace - # Key in the secret to get thre values from - key: values.yaml # optional; defaults to values.yaml - # If set to true successful retrieval of the values file is no - # longer mandatory - optional: true # optional; defaults to false -``` - -#### External sources - -```yaml -spec: - # chart: ... - valuesFrom: - - externalSourceRef: - # URL of the values.yaml - url: https://example.com/static/raw/values.yaml # mandatory - # If set to true successful retrieval of the values file is no - # longer mandatory - optional: true # optional; defaults to false -``` - -#### Chart files - -```yaml -spec: - # chart: ... - valuesFrom: - - chartFileRef: - # path within the helm chart (from git repo) where environment-prod.yaml is located - path: overrides/environment-prod.yaml # mandatory - # If set to true successful retrieval of the values file is no - # longer mandatory - optional: true # optional; defaults to false -``` - -## Rollbacks - -From time to time a release made by the Helm operator may fail, it is -possible to automate the rollback of a failed release by setting -`.spec.rollback.enable` to `true` on the `HelmRelease` resource. - -> **Note:** a successful rollback of a Helm chart containing a -> `StatefulSet` resource is known to be tricky, and one of the main -> reasons automated rollbacks are not enabled by default for all -> `HelmRelease`s. Verify a manual rollback of your Helm chart does -> not cause any problems before enabling it. - -When enabled, the Helm operator will detect a faulty upgrade and -perform a rollback, it will not attempt a new upgrade unless it -detects a change in values and/or the chart. - -### Configuration - -```yaml -apiVersion: helm.fluxcd.io/v1 -kind: HelmRelease -# metadata: ... -spec: - # Listed values are the defaults. - rollback: - # If set, will perform rollbacks for this release. - enable: false - # If set, will force resource update through delete/recreate if - # needed. - force: false - # Prevent hooks from running during rollback. - disableHooks: false - # Time in seconds to wait for any individual Kubernetes operation. - timeout: 300 - # If set, will wait until all Pods, PVCs, Services, and minimum - # number of Pods of a Deployment are in a ready state before - # marking the release as successful. It will wait for as long - # as the set timeout. - wait: false -``` - -## Reinstalling a Helm release - -If a Helm release upgrade fails due to incompatible changes like modifying -an immutable field (e.g. headless svc to ClusterIP) -you can reinstall it using the following command: - -```sh -$ kubectl delete hr/my-release -``` - -When the Helm Operator receives a delete event from Kubernetes API it will -call Tiller and purge the Helm release. On the next Flux sync, the Helm Release -object will be created and the Helm Operator will install it. - -## Authentication - -At present, per-resource authentication is not implemented. The -`HelmRelease` definition includes a field `chartPullSecret` for -attaching a `repositories.yaml` file, but this is ignored for now. - -Instead, you need to provide the operator with credentials and keys (see the -following [Authentication for Helm repos](#authentication-for-helm-repos) -section for how to do this). - -### Authentication for Helm repos - -As a workaround, you can mount a `repositories.yaml` file with -authentication already configured, into the operator container. - -> **Note:** When using a custom `repositories.yaml` the -[default](https://github.com/fluxcd/helm-operator/blob/master/docker/helm-repositories.yaml) -that ships with the operator is overwritten. This means that for any -repository you want to make use of you should manually add an entry to -your `repositories.yaml` file. - -To prepare a file, add the repo _locally_ as you would normally: - -```sh -helm repo add --username --password -``` - -You need to doctor this file a little, since it will likely contain -absolute paths that will be wrong when mounted inside the -container. Copy the file and replace all the `cache` entries with just -the filename. - -```sh -cp ~/.helm/repository/repositories.yaml . -sed -i -e 's/^\( *cache: \).*\/\(.*\.yaml\)/\1\2/g' repositories.yaml -``` - -If you are using OSX and Helm 3 the command will be: - -```sh -cp ~/Library/Preferences/helm/repositories.yaml -``` - -Now you can create a secret in the same namespace as you're running -the Helm operator, from the repositories file: - -```sh -kubectl create secret generic flux-helm-repositories --from-file=./repositories.yaml -``` - -Lastly, mount that secret into the container. This can be done by -setting `helmOperator.configureRepositories.enable` to `true` for the -flux Helm release, or as shown in the commented-out sections of the -[example deployment](https://github.com/fluxcd/helm-operator/blob/master/deploy/helm-operator-deployment.yaml). - -#### Azure ACR repositories - -For Azure ACR repositories, the entry in `repositories.yaml` created by -running `az acr helm repo add` is unsufficient for the Helm operator. -Instead you will need to [create a service principal](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal#create-a-service-principal) -and use the plain text id and password this gives you. For example: - -```yaml -- caFile: "" - cache: -index.yaml - certFile: "" - keyFile: "" - name: - url: https://.azurecr.io/helm/v1/repo - username: - password: -``` - -### Authentication for Git repos - -In general, it's necessary to have an SSH key to clone a git -repo. This is sometimes (e.g., on GitHub) called a "deploy key". To -use a chart from git, the Helm Operator needs a key with read-only -access. - -To provide an SSH key, put the key in a secret under the entry -`identity`, and mount it into the operator container as shown in the -[example deployment](https://github.com/fluxcd/helm-operator/blob/master/deploy/helm-operator-deployment.yaml). -The default ssh_config expects an identity file at -`/etc/fluxd/ssh/identity`, which is where it'll be if you just -uncomment the blocks from the example. - -If you're using more than one repository, you may need to provide more -than one SSH key. In that case, you can create a secret with an entry -for each key, and mount that _as well as_ an ssh_config file -mentioning each key as an `IdentityFile`. +

Packages:

+ +

helm.fluxcd.io/v1

+

Package v1 is the v1 version of the API. The prior +version was flux.weave.works/v1beta1.

+Resource Types: + +

HelmRelease +

+

HelmRelease is a type to represent a Helm release.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 +helm.fluxcd.io/v1 +
+kind
+string +		 +HelmRelease +
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +HelmReleaseSpec + + +		 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+helmVersion
+ + +HelmVersion + + +		 +
+chart
+ + +ChartSource + + +		 + + + + + + + + + +
+GitChartSource
+ + +GitChartSource + + +		 +

+(Members of GitChartSource are embedded into this type.) +

+(Optional) +
+RepoChartSource
+ + +RepoChartSource + + +		 +

+(Members of RepoChartSource are embedded into this type.) +

+(Optional) +
+
+releaseName
+ +string + +		 +

ReleaseName is the name of the The Helm release. If not supplied, +it will be generated by affixing the namespace to the resource +name.

+
+maxHistory
+ +int + +		 +

MaxHistory is the maximum amount of revisions to keep for the +Helm release. If not supplied, it defaults to 10.

+
+valuesFrom
+ + +[]ValuesFromSource + + +		 +
+targetNamespace
+ +string + +		 +(Optional) +

TargetNamespace overrides the targeted namespace for the Helm +release. The default namespace equals to the namespace of the +HelmRelease resource.

+
+timeout
+ +int64 + +		 +(Optional) +

Timeout is the time to wait for any individual Kubernetes +operation (like Jobs for hooks) during installation and +upgrade operations.

+
+resetValues
+ +bool + +		 +(Optional) +

ResetValues will mark this Helm release to reset the values +to the defaults of the targeted chart before performing +an upgrade.

+
+skipCRDs
+ +bool + +		 +(Optional) +

SkipCRDs will mark this Helm release to skip the creation +of CRDs during a Helm 3 installation.

+
+wait
+ +bool + +		 +(Optional) +

Wait will mark this Helm release to wait until all Pods, +PVCs, Services, and minimum number of Pods of a Deployment, +StatefulSet, or ReplicaSet are in a ready state before marking +the release as successful.

+
+forceUpgrade
+ +bool + +		 +(Optional) +

Force will mark this Helm release to --force upgrades. This +forces the resource updates through delete/recreate if needed.

+
+rollback
+ + +Rollback + + +		 +(Optional) +

The rollback settings for this Helm release.

+
+values
+ + +HelmValues + + +		 +(Optional) +

Values holds the values for this Helm release.

+
+
+status
+ + +HelmReleaseStatus + + +		 + + + + + + + + + + + + + + + + + + + + + + + + + +
+releaseName
+ +string + +		 +(Optional) +

ReleaseName is the name as either supplied or generated.

+
+releaseStatus
+ +string + +		 +(Optional) +

ReleaseStatus is the status as given by Helm for the release +managed by this resource.

+
+observedGeneration
+ +int64 + +		 +(Optional) +

ObservedGeneration is the most recent generation observed by +the operator.

+
+revision
+ +string + +		 +(Optional) +

Revision holds the Git hash or version of the chart currently +deployed.

+
+rollbackCount
+ +int64 + +		 +(Optional) +

RollbackCount records the amount of rollback attempts made, +it is incremented after a rollback failure and reset after a +successful upgrade or revision change.

+
+conditions
+ + +[]HelmReleaseCondition + + +		 +(Optional) +

Conditions contains observations of the resource’s state, e.g., +has the chart which it refers to been fetched.

+
+
+
+
+

ChartFileSelector +

+

+(Appears on: +ValuesFromSource) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+path
+ +string + +		 +

Path is the file path to the source relative to the chart root.

+
+optional
+ +bool + +		 +(Optional) +

Optional will mark this ChartFileSelector as optional. +The result of this are that operations are permitted without +the source, due to it e.g. being temporarily unavailable.

+
+
+
+

ChartSource +

+

+(Appears on: +HelmReleaseSpec) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+GitChartSource
+ + +GitChartSource + + +		 +

+(Members of GitChartSource are embedded into this type.) +

+(Optional) +
+RepoChartSource
+ + +RepoChartSource + + +		 +

+(Members of RepoChartSource are embedded into this type.) +

+(Optional) +
+
+
+

ConditionStatus +(string alias)

+

+(Appears on: +HelmReleaseCondition) +

+

ConfigMapKeySelector +

+

+(Appears on: +OptionalConfigMapKeySelector) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+LocalObjectReference
+ + +LocalObjectReference + + +		 +

+(Members of LocalObjectReference are embedded into this type.) +

+
+namespace
+ +string + +		 +(Optional) +
+key
+ +string + +		 +(Optional) +
+
+
+

ExternalSourceSelector +

+

+(Appears on: +ValuesFromSource) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+url
+ +string + +		 +

URL is the URL of the external source.

+
+optional
+ +bool + +		 +(Optional) +

Optional will mark this ExternalSourceSelector as optional. +The result of this are that operations are permitted without +the source, due to it e.g. being temporarily unavailable.

+
+
+
+

GitChartSource +

+

+(Appears on: +ChartSource) +

+

GitChartSource describes a Helm chart sourced from Git.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+git
+ +string + +		 +

Git URL is the URL of the Git repository, e.g. +git@github.com:org/repo, http://github.com/org/repo, +or ssh://git@example.com:2222/org/repo.git.

+
+ref
+ +string + +		 +

Ref is the Git branch (or other reference) to use. Defaults to +‘master’, or the configured default Git ref.

+
+path
+ +string + +		 +

Path is the path to the chart relative to the repository root.

+
+secretRef
+ + +LocalObjectReference + + +		 +(Optional) +

SecretRef holds the authentication secret for accessing the Git +repository (over HTTPS). The credentials will be added to an +HTTPS GitURL before the mirror is started.

+
+skipDepUpdate
+ +bool + +		 +(Optional) +

SkipDepUpdate will tell the operator to skip running +‘helm dep update’ before installing or upgrading the chart, the +chart dependencies must be present for this to succeed.

+
+
+
+

HelmReleaseCondition +

+

+(Appears on: +HelmReleaseStatus) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+type
+ + +HelmReleaseConditionType + + +		 +

Type of the condition, one of (‘ChartFetched’, ‘Released’, ‘RolledBack’).

+
+status
+ + +ConditionStatus + + +		 +

Status of the condition, one of (‘True’, ‘False’, ‘Unknown’).

+ +
+
+lastUpdateTime
+ + +Kubernetes meta/v1.Time + + +		 +(Optional) +

LastUpdateTime is the timestamp corresponding to the last status +update of this condition.

+
+lastTransitionTime
+ + +Kubernetes meta/v1.Time + + +		 +(Optional) +

LastTransitionTime is the timestamp corresponding to the last status +change of this condition.

+
+reason
+ +string + +		 +(Optional) +

Reason is a brief machine readable explanation for the condition’s last +transition.

+
+message
+ +string + +		 +(Optional) +

Message is a human readable description of the details of the last +transition, complementing reason.

+
+
+
+

HelmReleaseConditionType +(string alias)

+

+(Appears on: +HelmReleaseCondition) +

+

HelmReleaseConditionType represents an HelmRelease condition value. +Valid HelmReleaseConditionType values are: +“ChartFetched”, +“Released”, +“RolledBack”

+

HelmReleaseSpec +

+

+(Appears on: +HelmRelease) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+helmVersion
+ + +HelmVersion + + +		 +
+chart
+ + +ChartSource + + +		 + + + + + + + + + +
+GitChartSource
+ + +GitChartSource + + +		 +

+(Members of GitChartSource are embedded into this type.) +

+(Optional) +
+RepoChartSource
+ + +RepoChartSource + + +		 +

+(Members of RepoChartSource are embedded into this type.) +

+(Optional) +
+
+releaseName
+ +string + +		 +

ReleaseName is the name of the The Helm release. If not supplied, +it will be generated by affixing the namespace to the resource +name.

+
+maxHistory
+ +int + +		 +

MaxHistory is the maximum amount of revisions to keep for the +Helm release. If not supplied, it defaults to 10.

+
+valuesFrom
+ + +[]ValuesFromSource + + +		 +
+targetNamespace
+ +string + +		 +(Optional) +

TargetNamespace overrides the targeted namespace for the Helm +release. The default namespace equals to the namespace of the +HelmRelease resource.

+
+timeout
+ +int64 + +		 +(Optional) +

Timeout is the time to wait for any individual Kubernetes +operation (like Jobs for hooks) during installation and +upgrade operations.

+
+resetValues
+ +bool + +		 +(Optional) +

ResetValues will mark this Helm release to reset the values +to the defaults of the targeted chart before performing +an upgrade.

+
+skipCRDs
+ +bool + +		 +(Optional) +

SkipCRDs will mark this Helm release to skip the creation +of CRDs during a Helm 3 installation.

+
+wait
+ +bool + +		 +(Optional) +

Wait will mark this Helm release to wait until all Pods, +PVCs, Services, and minimum number of Pods of a Deployment, +StatefulSet, or ReplicaSet are in a ready state before marking +the release as successful.

+
+forceUpgrade
+ +bool + +		 +(Optional) +

Force will mark this Helm release to --force upgrades. This +forces the resource updates through delete/recreate if needed.

+
+rollback
+ + +Rollback + + +		 +(Optional) +

The rollback settings for this Helm release.

+
+values
+ + +HelmValues + + +		 +(Optional) +

Values holds the values for this Helm release.

+
+
+
+

HelmReleaseStatus +

+

+(Appears on: +HelmRelease) +

+

HelmReleaseStatus contains status information about an HelmRelease.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+releaseName
+ +string + +		 +(Optional) +

ReleaseName is the name as either supplied or generated.

+
+releaseStatus
+ +string + +		 +(Optional) +

ReleaseStatus is the status as given by Helm for the release +managed by this resource.

+
+observedGeneration
+ +int64 + +		 +(Optional) +

ObservedGeneration is the most recent generation observed by +the operator.

+
+revision
+ +string + +		 +(Optional) +

Revision holds the Git hash or version of the chart currently +deployed.

+
+rollbackCount
+ +int64 + +		 +(Optional) +

RollbackCount records the amount of rollback attempts made, +it is incremented after a rollback failure and reset after a +successful upgrade or revision change.

+
+conditions
+ + +[]HelmReleaseCondition + + +		 +(Optional) +

Conditions contains observations of the resource’s state, e.g., +has the chart which it refers to been fetched.

+
+
+
+

HelmValues +

+

+(Appears on: +HelmReleaseSpec) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+-
+ +map[string]interface{} + +		 +

Data holds the configuration keys and values. +Work around for https://github.com/kubernetes-sigs/kubebuilder/issues/528

+
+
+
+

HelmVersion +(string alias)

+

+(Appears on: +HelmReleaseSpec) +

+

HelmVersion is the version of Helm to target. If not supplied, +the lowest enabled Helm version will be targeted. +Valid HelmVersion values are: +“v2”, +“v3”

+

LocalObjectReference +

+

+(Appears on: +ConfigMapKeySelector, +GitChartSource, +HelmReleaseSpec, +RepoChartSource, +SecretKeySelector) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+
+
+

OptionalConfigMapKeySelector +

+

+(Appears on: +ValuesFromSource) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+ConfigMapKeySelector
+ + +ConfigMapKeySelector + + +		 +

+(Members of ConfigMapKeySelector are embedded into this type.) +

+
+optional
+ +bool + +		 +(Optional) +
+
+
+

OptionalSecretKeySelector +

+

+(Appears on: +ValuesFromSource) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+SecretKeySelector
+ + +SecretKeySelector + + +		 +

+(Members of SecretKeySelector are embedded into this type.) +

+
+optional
+ +bool + +		 +(Optional) +
+
+
+

RepoChartSource +

+

+(Appears on: +ChartSource) +

+

RepoChartSources describes a Helm chart sourced from a Helm +repository.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+repository
+ +string + +		 +

RepoURL is the URL of the Helm repository, e.g. +https://kubernetes-charts.storage.googleapis.com or +https://charts.example.com.

+
+name
+ +string + +		 +

Name is the name of the Helm chart without an alias, e.g. +redis (for helm upgrade [flags] stable/redis).

+
+version
+ +string + +		 +

Version is the targeted Helm chart version, e.g. 7.0.1.

+
+chartPullSecret
+ + +LocalObjectReference + + +		 +(Optional) +

ChartPullSecret holds the reference to the authentication secret for accessing +the Helm repository using HTTPS basic auth. +NOT IMPLEMENTED!

+
+
+
+

Rollback +

+

+(Appears on: +HelmReleaseSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+enable
+ +bool + +		 +(Optional) +

Enable will mark this Helm release for rollbacks.

+
+retry
+ +bool + +		 +(Optional) +

Retry will mark this Helm release for upgrade retries after a +rollback.

+
+maxRetries
+ +int64 + +		 +(Optional) +

MaxRetries is the maximum amount of upgrade retries the operator +should make before bailing.

+
+force
+ +bool + +		 +(Optional) +

Force will mark this Helm release to --force rollbacks. This +forces the resource updates through delete/recreate if needed.

+
+recreate
+ +bool + +		 +(Optional) +

Recreate will mark this Helm release to --recreate-pods for +if applicable. This performs pod restarts.

+
+disableHooks
+ +bool + +		 +(Optional) +

DisableHooks will mark this Helm release to prevent hooks from +running during the rollback.

+
+timeout
+ +int64 + +		 +(Optional) +

Timeout is the time to wait for any individual Kubernetes +operation (like Jobs for hooks) during rollback.

+
+wait
+ +bool + +		 +(Optional) +

Wait will mark this Helm release to wait until all Pods, +PVCs, Services, and minimum number of Pods of a Deployment, +StatefulSet, or ReplicaSet are in a ready state before marking +the release as successful.

+
+
+
+

SecretKeySelector +

+

+(Appears on: +OptionalSecretKeySelector) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+LocalObjectReference
+ + +LocalObjectReference + + +		 +

+(Members of LocalObjectReference are embedded into this type.) +

+
+namespace
+ +string + +		 +(Optional) +
+key
+ +string + +		 +(Optional) +
+
+
+

ValuesFromSource +

+

+(Appears on: +HelmReleaseSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+configMapKeyRef
+ + +OptionalConfigMapKeySelector + + +		 +(Optional) +

The reference to a config map with release values.

+
+secretKeyRef
+ + +OptionalSecretKeySelector + + +		 +(Optional) +

The reference to a secret with release values.

+
+externalSourceRef
+ + +ExternalSourceSelector + + +		 +(Optional) +

The reference to an external source with release values.

+
+chartFileRef
+ + +ChartFileSelector + + +		 +(Optional) +

The reference to a local chart file with release values.

+
+
+
+
+

This page was automatically generated with gen-crd-api-reference-docs

+
diff --git a/docs/references/index.rst b/docs/references/index.rst deleted file mode 100644 index 092ec1169..000000000 --- a/docs/references/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -References -========== - -.. toctree:: - :maxdepth: 1 - - operator - helmrelease-custom-resource diff --git a/docs/references/monitoring.md b/docs/references/monitoring.md new file mode 100644 index 000000000..28ca7e6d9 --- /dev/null +++ b/docs/references/monitoring.md @@ -0,0 +1,12 @@ +# Monitoring + +The Helm Operator exposes a metrics endpoint at `/metrics` on the configured +[`--listen`](operator.md#general-flags) address (defaults to `:3030`) with data +in Prometheus format. + +The following metrics are exposed: + +| Metric | Description +|--------|--- +| `release_duration_seconds` | Release duration in seconds. +| `release_queue_length_count` | Count of releases waiting in the queue to be processed. diff --git a/docs/references/operator.md b/docs/references/operator.md index 0f537836a..2e49d9ac1 100644 --- a/docs/references/operator.md +++ b/docs/references/operator.md @@ -1,6 +1,6 @@ -# Helm operator (`helm-operator`) +# Operator reference -The Helm operator deals with Helm chart releases. The operator watches for +The Helm Operator deals with Helm chart releases. The operator watches for changes of Custom Resources of kind `HelmRelease`. It receives Kubernetes Events and acts accordingly. @@ -17,19 +17,44 @@ take action accordingly. `helm-operator` requires setup and offers customization though a multitude of flags. +### General flags + | Flag | Default | Purpose | -------------------------- | ----------------------------- | --- | `--log-format` | `fmt` | Changes the logging format; `fmt` or `json`. -| `--workers` | `2` | Amount of workers processing releases. +| `--workers` | `2` | Number of workers processing releases. | `--listen` | `:3030` | Listen address where `/metrics` and API will be served. -| **Cluster configuration** + +### Reconciliation configuration + +| Flag | Default | Purpose +| -------------------------- | ----------------------------- | --- +| `--charts-sync-interval` | `3m` | Period on which to reconcile the Helm releases with `HelmRelease` resources. +| `--status-update-interval` | `10s` | Period on which to update the Helm release status in `HelmRelease` resources. +| `--log-release-diffs` | `false` | Log the diff when a chart release diverges. **Potentially insecure due to logging of secret values.** + +### Cluster configuration + +| Flag | Default | Purpose +| -------------------------- | ----------------------------- | --- | `--kubeconfig` | | Path to a kubeconfig. Only required if out-of-cluster. | `--master` | | The address of the Kubernetes API server. Overrides any value in kubeconfig. Only required if out-of-cluster. | `--allow-namespace` | | If set, this limits the scope to a single namespace. if not specified, all namespaces will be watched. -| **Helm options** -| `--enabled-helm-versions` | `v2,v3` | The Helm client versions supported by this operator instance -| `--helm-repository-import` | | Targeted version and the path of the Helm repository index to import, i.e. `v3:/tmp/v3/index.yaml,v2:/tmp/v2/index.yaml` -| **Tiller options** + +### Helm configuration + +| Flag | Default | Purpose +| -------------------------- | ----------------------------- | --- +| `--enabled-helm-versions` | `v2,v3` | The Helm client versions supported by this operator instance. +| `--helm-repository-import` | | Targeted version and the path of the Helm repository index to import, i.e. `v3:/tmp/v3/index.yaml,v2:/tmp/v2/index.yaml`. + +#### Tiller configuration + +The following option flags are only applicable when support for Helm 2 is +enabled and a connection to Tiller needs to be made. + +| Flag | Default | Purpose +| -------------------------- | ----------------------------- | --- | `--tiller-ip` | | Tiller IP address. Only required if out-of-cluster. | `--tiller-port` | | Tiller port. | `--tiller-namespace` | | Tiller namespace. If not provided, the default is kube-system. @@ -37,13 +62,13 @@ take action accordingly. | `--tiller-tls-verify` | `false` | Verify TLS certificate from Tiller. Will enable TLS communication when provided. | `--tiller-tls-key-path` | `/etc/fluxd/helm/tls.key` | Path to private key file used to communicate with the Tiller server. | `--tiller-tls-cert-path` | `/etc/fluxd/helm/tls.crt` | Path to certificate file used to communicate with the Tiller server. -| `--tiller-tls-ca-cert-path` | | Path to CA certificate file used to validate the Tiller server. Required if tiller-tls-verify is enabled. +| `--tiller-tls-ca-cert-path` | | Path to CA certificate file used to validate the Tiller server. Required if `--tiller-tls-verify` is enabled. | `--tiller-tls-hostname` | | The server name used to verify the hostname on the returned certificates from the Tiller server. -| **Reconciliation configuration** -| `--charts-sync-interval` | `3m` | Period on which to reconcile the Helm releases with `HelmRelease` resources -| `--status-update-interval` | `10s` | Period on which to update the Helm release status in `HelmRelease` resources -| `--log-release-diffs` | `false` | Log the diff when a chart release diverges. **Potentially insecure due to logging of secret values.** -| **(Git sourced) chart changes** (none of these need overriding, usually) -| `--git-timeout` | `20s` | Duration after which git operations time out. -| `--git-poll-interval` | `5m` | Period on which to poll git chart sources for changes. -| `--update-chart-deps` | `true` | Update chart dependencies before installing or upgrading a release. + +### Git chart source configuration + +| Flag | Default | Purpose +| -------------------------- | ----------------------------- | --- +| `--git-timeout` | `20s` | Duration after which Git operations time out. +| `--git-poll-interval` | `5m` | Period on which to poll Git chart sources for changes. +| `--update-chart-deps` | `true` | Update chart dependencies from a Git chart source before installing or upgrading a release. diff --git a/docs/requirements.txt b/docs/requirements.txt index 867be2716..3e38cc02d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,5 @@ -sphinx == 2.1.2 -sphinx_markdown_tables == 0.0.9 -recommonmark == 0.5.0 +mkdocs == 1.1 +mkdocs-material == 4.6.3 +mkdocs-redirects +mkdocs-markdownextradata-plugin == 0.1.3 +pymdown-extensions == 6.3.0 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 61fad1353..6ad78b7b6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,7 +4,13 @@ Also see the [issues labeled with `question`](https://github.com/fluxcd/helm-operator/labels/question), which often explain workarounds. -## Error creating helm client: failed to append certificates from file: /etc/fluxd/helm-ca/ca.crt +## `failed to load chart from path [/tmp/flux-working012345678/chart/path] for release [x]: stat /tmp/flux-working012345678/chart/path: no such file or directory` + +The `.chart.path` of your Git sourced chart in the `HelmRelease` is likely +incorrect. It is expected to be a path to the chart folder relative to the +root directory of the Git repository. + +## `Error creating helm client: failed to append certificates from file: /etc/fluxd/helm-ca/ca.crt` Your CA certificate content is not set correctly, check if your ConfigMap contains the correct values. Example: diff --git a/docs/tutorials/get-started-kustomize.md b/docs/tutorials/get-started-kustomize.md index ca52258a0..905e1cbf4 100644 --- a/docs/tutorials/get-started-kustomize.md +++ b/docs/tutorials/get-started-kustomize.md @@ -1,156 +1 @@ -# How to bootstrap Helm operator using Kustomize - -This guide shows you how to use Kustomize to bootstrap Helm Operator on a Kubernetes cluster. - -## Prerequisites - -You will need to have Kubernetes set up. For a quick local test, -you can use `minikube`, `kubeadm` or `kind`. Any other Kubernetes setup -will work as well though. - -If working on e.g. GKE with RBAC enabled, you will need to add a cluster role binding: - -```sh -kubectl create clusterrolebinding "cluster-admin-$(whoami)" \ - --clusterrole=cluster-admin \ - --user="$(gcloud config get-value core/account)" -``` - -## Prepare Helm Operator installation - -Create a directory called `fluxcd` and add the `flux` namespace definition to it: - -```sh -mkdir fluxcd - -cat > fluxcd/namespace.yaml < fluxcd/repositories.yaml < fluxcd/kustomization.yaml < **Note:** If you want to install a specific Helm operator release, -> add the version number to the base URL: -> `github.com/fluxcd/helm-operator//deploy?ref=v1.0.0-rc2` - - -Create a patch file for Helm operator and mount the repositories secret: - -```sh -cat > fluxcd/patch.yaml < **Note:** When creating the certificate for Tiller the Common Name should match the hostname you are connecting to from the Helm operator. - -The following script can be used for that (requires [cfssl](https://github.com/cloudflare/cfssl)): - -```bash -# TILLER_HOSTNAME=. -export TILLER_HOSTNAME=tiller-deploy.kube-system -export TILLER_SERVER=server -export USER_NAME=flux-helm-operator - -mkdir tls -cd ./tls - -# Prep the configuration -echo '{"CN":"CA","key":{"algo":"rsa","size":4096}}' | cfssl gencert -initca - | cfssljson -bare ca - -echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","server auth","client auth"]}}}' > ca-config.json - -# Create the tiller certificate -echo '{"CN":"'$TILLER_SERVER'","hosts":[""],"key":{"algo":"rsa","size":4096}}' | cfssl gencert \ - -config=ca-config.json -ca=ca.pem \ - -ca-key=ca-key.pem \ - -hostname="$TILLER_HOSTNAME" - | cfssljson -bare $TILLER_SERVER - -# Create a client certificate -echo '{"CN":"'$USER_NAME'","hosts":[""],"key":{"algo":"rsa","size":4096}}' | cfssl gencert \ - -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem \ - -hostname="$TILLER_HOSTNAME" - | cfssljson -bare $USER_NAME -``` - -Alternatively, you can follow the [Helm documentation for configuring TLS](https://docs.helm.sh/using_helm/#using-ssl-between-helm-and-tiller). - -Next create the RBAC configuration for Tiller: - -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: tiller - namespace: kube-system ---- -apiVersion: rbac.authorization.k8s.io/v1beta1 -kind: ClusterRoleBinding -metadata: - name: tiller -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin -subjects: - - kind: ServiceAccount - name: tiller - namespace: kube-system - ---- -# Helm client serviceaccount -apiVersion: v1 -kind: ServiceAccount -metadata: - name: helm - namespace: kube-system ---- -apiVersion: rbac.authorization.k8s.io/v1beta1 -kind: Role -metadata: - name: tiller-user - namespace: kube-system -rules: -- apiGroups: - - "" - resources: - - pods/portforward - verbs: - - create -- apiGroups: - - "" - resources: - - pods - verbs: - - list ---- -apiVersion: rbac.authorization.k8s.io/v1beta1 -kind: RoleBinding -metadata: - name: tiller-user-binding - namespace: kube-system -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: tiller-user -subjects: -- kind: ServiceAccount - name: helm - namespace: kube-system -``` - -Save the above config as `helm-rbac.yaml` and deploy Tiller: - -```bash -kubectl apply -f helm-rbac.yaml - -# Deploy helm with mutual TLS enabled. -# --history-max limits the maximum number of revisions Tiller stores; -# leaving it to the default (0) may result in request timeouts after N -# releases, due to the excessive amount of ConfigMaps Tiller will -# attempt to retrieve. -helm init --upgrade --service-account tiller --history-max 10 \ - --override 'spec.template.spec.containers[0].command'='{/tiller,--storage=secret}' \ - --tiller-tls \ - --tiller-tls-cert ./tls/server.pem \ - --tiller-tls-key ./tls/server-key.pem \ - --tiller-tls-verify \ - --tls-ca-cert ./tls/ca.pem -``` - -To check if Tiller installed succesfully with TLS enabled, try `helm ls`. This should give an error: - -```bash -# Should give an error -$ helm ls -Error: transport is closing -``` - -When providing the certificates, it should work correctly: - -```bash -helm --tls --tls-verify \ - --tls-ca-cert ./tls/ca.pem \ - --tls-cert ./tls/flux-helm-operator.pem \ - --tls-key ././tls/flux-helm-operator-key.pem \ - --tls-hostname tiller-deploy.kube-system \ - ls -``` - -## Deploy the Helm Operator - -First create a new Kubernetes TLS secret for the client certs: - -```bash -kubectl create secret tls helm-client --cert=tls/flux-helm-operator.pem --key=./tls/flux-helm-operator-key.pem -``` - -> **Note:** this has to be in the same namespace as the flux-helm-operator is deployed in. - -Deploy Flux with Helm: - -```bash -helm repo add fluxcd https://fluxcd.github.io/flux - -helm upgrade --install \ - --set helmOperator.create=true \ - --set helmOperator.createCRD=true \ - --set git.url=$YOUR_GIT_REPO \ - --set helmOperator.tls.enable=true \ - --set helmOperator.tls.verify=true \ - --set helmOperator.tls.secretName=helm-client \ - --set helmOperator.tls.caContent="$(cat ./tls/ca.pem)" \ - flux \ - fluxcd/flux -``` - -> **Note:** -> -> - include --tls flags for `helm` as in the `helm ls` example, if talking to a tiller with TLS -> - optionally specify target --namespace - -## Check if it worked - -Use `kubectl logs` on the Helm Operator and observe the helm client being created. +The contents of this document have been moved to [`get-started`](../get-started/quickstart.md). diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst deleted file mode 100644 index 93aced3e8..000000000 --- a/docs/tutorials/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Tutorials -========= - -.. toctree:: - :maxdepth: 1 - - get-started - get-started-kustomize diff --git a/hack/crd-reference-doc-gen/config.json b/hack/crd-reference-doc-gen/config.json new file mode 100644 index 000000000..58fbc2e9c --- /dev/null +++ b/hack/crd-reference-doc-gen/config.json @@ -0,0 +1,25 @@ +{ + "hideMemberFields": [ + "TypeMeta", + "ValueFileSecrets" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/crd-reference-doc-gen/template/members.tpl b/hack/crd-reference-doc-gen/template/members.tpl new file mode 100644 index 000000000..bad4745ba --- /dev/null +++ b/hack/crd-reference-doc-gen/template/members.tpl @@ -0,0 +1,44 @@ +{{ define "members" }} + {{ range .Members }} + {{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") (eq (fieldName .) "status") (eq (fieldName .) "chart") }} + + {{ template "members" .Type }} +
+ {{ end }} + + + {{ end }} + {{ end }} +{{ end }} diff --git a/hack/crd-reference-doc-gen/template/pkg.tpl b/hack/crd-reference-doc-gen/template/pkg.tpl new file mode 100644 index 000000000..55269aeaf --- /dev/null +++ b/hack/crd-reference-doc-gen/template/pkg.tpl @@ -0,0 +1,47 @@ +{{ define "packages" }} +# `HelmRelease` Custom Resource + + +{{ with .packages}} +

Packages:

+ +{{ end}} + +{{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} + {{ safe (renderComments .) }} + {{ end }} + {{ end }} + + Resource Types: + +
    + {{- range (visibleTypes (sortedTypes .Types)) -}} + {{ if isExportedType . -}} +
  • + {{ typeDisplayName . }} +
    • + {{- end }} + {{- end -}} +
+ + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} +{{ end }} + +
+

This page was automatically generated with gen-crd-api-reference-docs

+
+{{ end }} diff --git a/hack/crd-reference-doc-gen/template/type.tpl b/hack/crd-reference-doc-gen/template/type.tpl new file mode 100644 index 000000000..c9b1cf376 --- /dev/null +++ b/hack/crd-reference-doc-gen/template/type.tpl @@ -0,0 +1,60 @@ +{{ define "type" }} +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+ +{{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{ $prev = . }} + {{ typeDisplayName . }} + {{- end -}} + ) +

+{{ end }} + +{{ with .CommentLines }} +{{ safe (renderComments .) }} +{{ end }} + +{{ if .Members }} +
+
+ + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" . }} + +
FieldDescription
+ apiVersion
+ string		 + {{ apiGroup . }} +
+ kind
+ string + 		+ {{ .Name.Name }} +
+
+
+{{ end }} +{{ end }} diff --git a/hack/tools/go.mod b/hack/tools/go.mod index 20bc7af04..adb517bbd 100644 --- a/hack/tools/go.mod +++ b/hack/tools/go.mod @@ -3,6 +3,7 @@ module github.com/fluxcd/helm-operator/hack/tools go 1.13 require ( + github.com/ahmetb/gen-crd-api-reference-docs v0.1.5 golang.org/x/tools v0.0.0-20190927052746-69890759d905 // indirect k8s.io/code-generator v0.17.2 k8s.io/gengo v0.0.0-20190907103519-ebc107f98eab // indirect diff --git a/hack/tools/go.sum b/hack/tools/go.sum index 321c98eee..a95f488dd 100644 --- a/hack/tools/go.sum +++ b/hack/tools/go.sum @@ -18,6 +18,8 @@ github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbt github.com/PuerkitoBio/urlesc v0.0.0-20160726150825-5bd2802263f2/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE= github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE= github.com/agnivade/levenshtein v1.0.1/go.mod h1:CURSv5d9Uaml+FovSIICkLbAUZ9S4RqaHDIsdSBg7lM= +github.com/ahmetb/gen-crd-api-reference-docs v0.1.5 h1:OU+AFpBEhyclrQGx4I6zpCx5WvXiKqvFeeOASOmhKCY= +github.com/ahmetb/gen-crd-api-reference-docs v0.1.5/go.mod h1:P/XzJ+c2+khJKNKABcm2biRwk2QAuwbLf8DlXuaL7WM= github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc= github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0= github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8= @@ -214,6 +216,7 @@ github.com/pborman/uuid v1.2.0/go.mod h1:X/NO0urCmaxf9VXbdlT7C2Yzkj2IKimNn4k+gtP github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic= github.com/peterbourgon/diskv v2.0.1+incompatible/go.mod h1:uqqh8zWWbv1HBMNONnaR/tNboyR3/BZd58JJSHlUSCU= github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= +github.com/pkg/errors v0.8.1 h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I= github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v0.0.0-20151028094244-d8ed2627bdf0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= @@ -228,8 +231,13 @@ github.com/prometheus/procfs v0.0.0-20181005140218-185b4288413d/go.mod h1:c3At6R github.com/prometheus/procfs v0.0.2/go.mod h1:TjEm7ze935MbeOT/UhFTIMYKhuLP4wbCsTZCD3I8kEA= github.com/remyoudompheng/bigfft v0.0.0-20170806203942-52369c62f446/go.mod h1:uYEyJGbgTkfkS4+E/PavXkNJcbFIpEtjt2B0KDQ5+9M= github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg= +github.com/russross/blackfriday v1.5.2 h1:HyvC0ARfnZBqnXwABFeSZHpKvJHJJfPz81GNueLj0oo= github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g= +github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q= +github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAmXWZgo= +github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo= +github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc= github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo= github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE= github.com/soheilhy/cmux v0.1.4/go.mod h1:IM3LyeVVIOuxMH7sFAkER9+bJ4dT7Ms6E4xg4kGIyLM= @@ -345,6 +353,7 @@ golang.org/x/tools v0.0.0-20181030221726-6c7e314b6563/go.mod h1:n7NCudcB/nEzxVGm golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20190125232054-d66bd3c5d5a6/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20190206041539-40960b6deb8e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= +golang.org/x/tools v0.0.0-20190213192042-740235f6c0d8/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY= golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs= golang.org/x/tools v0.0.0-20190312151545-0bb0c0a6e846/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs= @@ -411,6 +420,7 @@ k8s.io/gengo v0.0.0-20190822140433-26a664648505/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8 k8s.io/gengo v0.0.0-20190907103519-ebc107f98eab h1:j4L8spMe0tFfBvvW6lrc0c+Ql8+nnkcV3RYfi3eSwGY= k8s.io/gengo v0.0.0-20190907103519-ebc107f98eab/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0= k8s.io/klog v0.0.0-20181102134211-b9b56d5dfc92/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk= +k8s.io/klog v0.2.0/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk= k8s.io/klog v0.3.0/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk= k8s.io/klog v1.0.0 h1:Pt+yjF5aB1xDSVbau4VsWe+dQNzA0qv1LlXdC2dF6Q8= k8s.io/klog v1.0.0/go.mod h1:4Bi6QPql/J/LkTDqv7R/cd3hPo4k2DG6Ptcz060Ez5I= diff --git a/hack/tools/tools.go b/hack/tools/tools.go index 582a330fa..066a6f719 100644 --- a/hack/tools/tools.go +++ b/hack/tools/tools.go @@ -7,6 +7,7 @@ package tools // +build tools import ( + _ "github.com/ahmetb/gen-crd-api-reference-docs" _ "k8s.io/code-generator/cmd/client-gen" _ "k8s.io/code-generator/cmd/deepcopy-gen" _ "k8s.io/code-generator/cmd/informer-gen" diff --git a/hack/update/generate-all.sh b/hack/update/generate-all.sh old mode 100644 new mode 100755 diff --git a/hack/update/generate-crds.sh b/hack/update/generate-crds.sh index e8c6111a3..6cbb7b3e4 100755 --- a/hack/update/generate-crds.sh +++ b/hack/update/generate-crds.sh @@ -26,7 +26,7 @@ cd "${REPO_ROOT}" # build the generators using the tools module cd "hack/tools" "${REPO_ROOT}/hack/go_container.sh" go build -o /out/controller-gen sigs.k8s.io/controller-tools/cmd/controller-gen -# go back to the root +"${REPO_ROOT}/hack/go_container.sh" go build -o /out/crd-reference-gen github.com/ahmetb/gen-crd-api-reference-docs cd "${REPO_ROOT}" # turn off module mode before running the generators @@ -48,7 +48,7 @@ cd "${FAKE_REPOPATH}" # run the generators CRD_DIR="./chart/helm-operator/crds" -echo "Generate OpenAPI v3 schemas for chart CRDs" +echo "Generating OpenAPI v3 schemas for chart CRDs" bin/controller-gen \ schemapatch:manifests="${CRD_DIR}" \ output:dir="${CRD_DIR}" \ @@ -65,6 +65,13 @@ for file in $(find "${CRD_DIR}" -type f | sort -V); do done chmod 644 "$out" +echo "Generating CRD reference documentation" +bin/crd-reference-gen \ + -api-dir=./pkg/apis/helm.fluxcd.io/v1 \ + -config=./hack/crd-reference-doc-gen/config.json \ + -template-dir=./hack/crd-reference-doc-gen/template \ + -out-file=./docs/references/helmrelease-custom-resource.md + # set module mode back, return to repo root export GO111MODULE="on" cd "${REPO_ROOT}" diff --git a/hack/update/verify.sh b/hack/update/verify.sh index b024a6668..47edb8df3 100755 --- a/hack/update/verify.sh +++ b/hack/update/verify.sh @@ -18,31 +18,31 @@ set -o errexit -o nounset -o pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)" -DIFFROOT="${REPO_ROOT}/pkg" -TMP_DIFFROOT="${REPO_ROOT}/_tmp/pkg" -_tmp="${REPO_ROOT}/_tmp" +TMP_DIFFROOT="${REPO_ROOT}/_tmp" +DIFFROOT="${REPO_ROOT}" cleanup() { - rm -rf "${_tmp}" + rm -rf "${TMP_DIFFROOT}" } trap "cleanup" EXIT SIGINT cleanup mkdir -p "${TMP_DIFFROOT}" -cp -a "${DIFFROOT}"/* "${TMP_DIFFROOT}" +cp -a "${DIFFROOT}"/{pkg,docs,deploy} "${TMP_DIFFROOT}" -"${REPO_ROOT}/hack/update/generate-codegen.sh" -"${REPO_ROOT}/hack/update/generate-crds.sh" +"${REPO_ROOT}/hack/update/generate-all.sh" -echo "diffing ${DIFFROOT} against freshly generated codegen" +echo "diffing ${DIFFROOT} against freshly generated files" ret=0 -diff -Naupr "${DIFFROOT}" "${TMP_DIFFROOT}" || ret=$? -cp -a "${TMP_DIFFROOT}"/* "${DIFFROOT}" +for i in {pkg,docs,deploy}; do + diff -Naupr --no-dereference "${TMP_DIFFROOT}/${i}" "${DIFFROOT}/${i}" || ret=$? +done +cp -a "${TMP_DIFFROOT}"/{pkg,docs,deploy} "${DIFFROOT}" if [[ $ret -eq 0 ]] then echo "${DIFFROOT} up to date." else - echo "${DIFFROOT} is out of date. Please run hack/update/generated.sh" + echo "${DIFFROOT} is out of date. Please run hack/update/generate-all.sh" exit 1 fi diff --git a/internal_docs/releasing.md b/internal_docs/releasing.md index f0e46626c..d9be4ca0a 100644 --- a/internal_docs/releasing.md +++ b/internal_docs/releasing.md @@ -1,4 +1,4 @@ -# How to release the Helm operator +# How to release the Helm Operator The release process needs to do these things: @@ -11,7 +11,7 @@ Much of this is automated, but it needs a human to turn the wheel. ## Overview -The Helm operator releases use branches and tags with semver versions, like `1.2.3`. +The Helm Operator releases use branches and tags with semver versions, like `1.2.3`. Each minor version has its own "release series" branch, from which patch releases will be put together, called e.g., `release/1.2.x`. @@ -93,7 +93,7 @@ change. ## Helm chart release process 1. Create a new branch (i.e. `release/chart-1.0.0`) -2. Update `appVersion` with the new Flux Helm operator version in `chart/helm-operator/Chart.yaml` +2. Update `appVersion` with the new Helm Operator version in `chart/helm-operator/Chart.yaml` 3. Bump the chart version in `chart/helm-operator/Chart.yaml` 4. (Maybe) update `image.tag` with the new version in `chart/helm-operator/values.yaml` 6. Create a PR diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..8a96ba820 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,75 @@ +site_name: Flux Helm Operator +# site_description: +site_author: The Helm Operator contributors +site_url: https://docs.fluxcd.io/projects/helm-operator/ + +# Repository +repo_name: fluxcd/helm-operator +repo_url: https://github.com/fluxcd/helm-operator +edit_uri: "" + +extra: + version: master + social: + - type: 'github' + link: 'https://github.com/fluxcd/helm-operator' + +theme: + name: material + logo: _files/flux-icon@2x.png + favicon: _files/flux-icon@2x.png + language: en + feature: + tabs: false + palette: + primary: blue + accent: indigo + +docs_dir: docs + +extra_css: + - _static/custom.css + +plugins: + - search + - markdownextradata: {} + - redirects: + redirect_maps: + 'guides/upgrading-to-ga.md': 'how-to/upgrade-to-ga.md' + 'guides/upgrading-to-beta.md': 'how-to/upgrade-to-beta.md' + +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - toc: + permalink: true + - pymdownx.superfences + +nav: + - Overview: index.md + - Get started: + - Quickstart: get-started/quickstart.md + - Using Helm: get-started/using-helm.md + - Using Kustomize: get-started/using-kustomize.md + - Using YAMLs: get-started/using-yamls.md + - References: + - Operator reference: references/operator.md + - HelmRelease Custom Resource: references/helmrelease-custom-resource.md + - Helm chart: references/chart.md + - Monitoring: references/monitoring.md + - HelmRelease guide: + - Introduction: helmrelease-guide/introduction.md + - Chart sources: helmrelease-guide/chart-sources.md + - Values: helmrelease-guide/values.md + - Release configuration: helmrelease-guide/release-configuration.md + - Reconciliation and upgrades: helmrelease-guide/reconciliation-and-upgrades.md + - Rollbacks: helmrelease-guide/rollbacks.md + - Automation: helmrelease-guide/automation.md + - Debugging: helmrelease-guide/debugging.md + - How-to: + - Upgrade to GA: how-to/upgrade-to-ga.md + - Upgrade to beta: how-to/upgrade-to-beta.md + - Troubleshooting: + - FAQ: faq.md + - Troubleshooting: troubleshooting.md diff --git a/pkg/install/generated_templates.gogen.go b/pkg/install/generated_templates.gogen.go index 295161e85..56f28cf37 100644 --- a/pkg/install/generated_templates.gogen.go +++ b/pkg/install/generated_templates.gogen.go @@ -31,9 +31,9 @@ var templates = func() http.FileSystem { "/deployment.yaml.tmpl": &vfsgen۰CompressedFileInfo{ name: "deployment.yaml.tmpl", modTime: time.Date(1970, 1, 1, 0, 0, 0, 0, time.UTC), - uncompressedSize: 5068, + uncompressedSize: 6565, - compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcc\x58\x4f\x93\xdb\xba\x0d\xbf\xef\xa7\xc0\xec\x3b\xe4\xb2\x92\x36\xf3\xfe\xcc\x54\x99\x1c\xd2\x66\x5e\x36\x33\x2f\xe9\x4e\x37\xd3\x99\x9e\x5e\x60\x0a\xb6\x58\x53\xa4\x4a\x42\x76\x55\xcf\xf6\xb3\x77\x40\x4a\xb2\x64\xaf\x37\x9b\x9e\x9e\x2f\xeb\x25\x89\x1f\x40\x00\x3f\x00\x74\x96\x65\x57\xd8\xea\xbf\x93\x0f\xda\xd9\x12\xb0\x6d\x43\xb1\x7b\x7d\xb5\xd5\xb6\x2a\xe1\x3d\xb5\xc6\xf5\x0d\x59\xbe\x6a\x88\xb1\x42\xc6\xf2\x0a\xc0\x62\x43\x25\xd4\x64\x9a\xcc\xb5\xe4\x91\x9d\xbf\x3a\x1c\x32\xd0\x6b\xc8\x3f\x63\x43\xa1\x45\x45\xf0\xf8\x38\x1c\x8d\xff\x96\x70\x38\x9c\xec\x8a\x08\xd9\x4a\xbe\x86\x96\x94\x20\x7b\x6a\x8d\x56\x18\x4a\x78\x7d\x05\x10\xc8\x90\x62\xe7\x65\x07\xa0\x41\x56\xf5\x6f\xb8\x22\x13\xd2\xc2\xd3\x86\x00\x04\xf6\xc8\xb4\xe9\xd3\x29\xee\x5b\x2a\xe1\x6f\xa4\x3c\x21\xd3\x15\x00\x53\xd3\x1a\x64\x1a\x50\x67\xf7\x92\x8f\x59\x28\xb8\xa4\x42\x3e\x68\xad\x63\x64\xed\xec\xec\x78\xeb\x5d\x43\x5c\x53\x17\x72\xed\x8a\xa0\x3c\x8a\xf6\x6b\xf6\x1d\x5d\xc7\x43\xe3\x4d\xe3\x77\xf2\x3b\xad\xe8\x9d\x52\xae\xb3\xfc\xf9\xa2\xa6\x9d\x33\x5d\x43\x93\x96\x1f\xc6\xbf\xf0\x0f\xd7\xc1\x5e\x1b\x03\x96\xa8\x02\xae\x29\x10\xf0\xde\x8d\x02\x12\x90\x5e\x8e\xa0\x65\x60\x07\x14\x18\x57\x46\x87\x1a\x76\x68\x74\x85\x4c\x15\x7c\xf9\xed\x61\x82\x53\xce\x5a\x52\xf1\x46\x80\x1b\xd4\x36\x30\x7c\xd1\xc6\x90\x3f\xd3\x9c\xcd\x1d\xc3\x26\x64\x0a\xa7\x3d\x10\xa0\xb5\xde\x7c\xc2\xb6\x9c\x2d\x8e\xbe\x5c\x9b\xee\xdf\xd9\x4c\x2e\x4b\xa7\x17\x27\x2b\x5a\x63\x67\xf8\x93\xab\xa8\x84\xdb\x5f\x6e\x6f\xa7\xdd\x07\x09\x24\xc7\xa8\xc2\xb6\x5b\x91\xb7\xc4\x14\x9d\xcd\x26\x9c\x99\x77\xa2\x8b\x3c\xcf\xd4\x84\x08\xb5\x34\x31\xad\xa5\x50\x70\xbc\xfa\x53\x92\xa7\x06\xfe\x74\x34\x70\x3a\xf5\xa5\x26\x58\x3b\x63\xdc\x5e\xdb\xcd\x10\x11\xd0\x01\xd6\xce\x43\x17\x64\x0d\x41\x75\x81\x5d\xa3\x03\x55\xb0\xb5\x6e\x6f\x7f\xaf\x5d\xe0\x00\x6b\x6d\xe8\x66\x02\xda\xd7\x5a\xd5\x29\x8e\xc7\x50\x3b\xa8\xdc\x18\x5e\x11\x92\x2f\x1e\xdc\xde\xc2\x46\xb3\xd0\xc8\x81\x47\xae\x8f\x91\x03\xae\xd1\x0e\x8a\x37\x9a\xeb\x6e\x05\xce\x4b\xca\x80\xd1\x5b\xca\x25\x95\x5e\x19\x03\x68\x82\x9b\x54\x34\x92\x96\xa0\x8f\x37\xd7\x96\x5d\x94\x51\xce\x32\x6a\x4b\xfe\x06\x56\x64\xdc\x3e\x7f\x32\x35\x1b\xec\x13\xe0\x5e\x72\x8e\x9d\xb0\x63\xa7\x2b\x02\xb4\x10\x42\xfd\x7b\x0a\xfc\xc9\x75\xa5\xda\x68\x67\xc5\xce\xc6\x79\x4a\x76\x3b\x4b\xf0\xf5\x63\x25\x5b\xdc\xff\xaa\x0d\x7d\x7d\x13\x1d\x29\x29\x8a\x56\xd1\xcd\xe0\x8b\x57\x9e\x26\xa0\x74\xd7\x25\xc6\x07\xcd\x77\xdd\x2a\xfa\x27\x87\xcf\x7f\x8e\x77\x21\xcb\xbe\x87\x2d\xf5\x10\x6a\xd7\x99\x0a\x56\x47\x8c\xeb\x64\xe2\xf5\xe0\xcc\x04\x74\x7d\xb4\xfd\x5a\xf4\x46\x37\x51\x05\xda\xc2\x7f\x8b\x3c\x84\xba\x38\x77\xc7\x98\x90\x21\xd4\x95\xf6\xdf\x45\x95\x10\xea\x6f\x53\x44\x32\x70\x2c\xc1\x0f\x0f\x77\x0f\x53\x1a\xa7\x32\x3c\x70\xe7\xe1\x2e\xde\x93\x1d\xa0\x52\x14\x42\xbc\xff\x87\x21\x61\x82\x66\xe7\xfb\xa9\x92\x8d\x16\x6f\x34\x67\x5b\x3a\xae\x9f\xf2\x06\xce\x78\x23\x85\xfe\x82\x0d\xf0\xb4\xe9\x31\xcb\xc9\x4e\x9e\xf4\x84\x55\xe6\xac\xe9\x6f\x60\x4f\xb0\x77\xf6\x15\xc3\x8a\x00\x57\x86\xc4\x78\x55\x37\xae\x4a\xed\xc3\x84\xf9\x0d\x2f\x16\x46\x1d\x26\x06\x8e\x79\x32\x91\x70\x22\x0c\xd7\x78\x4c\x75\x11\x0c\x92\xa8\xa3\xd3\x24\xdd\x92\xd7\xde\x00\xe5\x9b\xfc\x06\x70\x4c\xa7\x2a\xb6\x49\x39\x95\xc3\xc7\xf5\x04\xb1\xd0\xf3\xcf\x2e\x70\x4c\xc1\xd0\xa9\x3a\xea\xbb\x89\xde\x1f\x7c\x31\xe3\xc3\x24\x8f\x46\xfc\xd0\x43\xeb\xb4\xe5\x00\xc8\x50\x10\xab\x42\x92\xa2\x2a\x24\xcd\xf4\x40\x08\xc0\x00\x38\xaa\x17\xb5\xc7\xda\x31\x54\xfe\x2e\xd0\x09\x13\xb6\xd4\xdf\x44\x0b\x67\x25\x65\xa4\xe7\x58\x4b\x26\x98\x19\x59\x71\xe5\x76\x74\x03\x7b\xcd\xb5\x78\x67\x49\xca\x81\x4b\xb1\x53\xcb\xa5\x09\x55\x3d\x81\x88\x13\xb5\x8d\x97\x4e\xd9\x32\x52\x9d\x2a\xa8\xc9\xd3\x65\xd2\x2c\x53\xf0\x25\xa5\x3b\x12\x47\xc4\x52\x68\x9e\x27\xce\xff\x95\x7d\xa3\xad\xc3\x10\x33\x63\xd9\x97\xb3\x36\x8c\x9e\x62\xfa\x44\x05\x29\xe9\x26\xc2\x69\x0a\x79\x8f\x8d\x39\xa9\x82\x68\xab\x21\x1c\x43\xa7\x40\x25\xc9\xa2\x7d\x1c\x88\xfa\x3c\xb6\x17\x83\xcc\xe4\xa5\xa9\x48\x04\x49\x2a\x97\xc2\x2e\x1c\xcb\xd7\xa4\x90\x63\x33\xf2\x0d\xf9\x44\x8b\x06\xb7\x94\x0a\xb9\xe0\x16\x47\xe0\xe3\xe5\x2f\x87\x63\x6e\x7b\x26\xb6\x7f\x6f\x60\x62\x43\x9e\xa3\x3c\xaf\x22\xda\x38\x43\xa4\xa6\xe5\xfe\xbd\xf6\x25\x1c\x1e\xaf\x86\xf5\xa9\x21\x4d\x53\x52\xf6\xcc\xe8\x36\x84\xc9\x53\x0c\x8d\x75\x70\x5d\xca\x44\x18\xf8\x1a\x74\x83\x1b\x4a\x5d\x7a\x21\x99\xc3\xaf\xda\xc6\x19\x0b\x1a\xe9\xb7\x9e\x94\x8c\xc5\x47\x3c\x4f\x86\x30\x90\x74\xd5\x88\x01\xbb\x34\x53\x0b\x6f\x6b\xe6\x36\x94\x45\x51\x77\xab\xbc\x72\x6a\x4b\x3e\x57\xae\x29\x7c\xb1\x27\xdc\xd1\xde\xf9\x6d\x28\x16\xda\x0a\xc6\x4d\x98\x81\x4b\x3a\xc8\x6c\x2c\x93\xb3\x98\xc0\xb8\x59\x70\x06\x92\xce\x12\x06\x74\xed\x62\x99\x50\xd5\x12\xb6\x7c\x9d\xdf\xe6\xb7\x99\x57\x7f\x5a\xca\xdd\x77\xc6\xdc\x3b\xa3\x55\x5f\xc2\xc7\xf5\x67\xc7\xf7\x9e\xc2\xfc\x7a\xad\xf3\x3c\x9b\x72\x27\xdf\x32\xb7\xb3\xca\x3e\x05\xe1\xde\x79\x2e\xe1\xc7\xdb\x1f\x6f\xa7\x5d\xa3\x77\x64\x29\x84\x7b\xef\x56\x34\xef\x1d\x82\xf1\xe1\xb4\x9d\xb4\xe7\x00\x71\x19\xb9\x2e\xa1\xa8\x09\x0d\xd7\xff\x99\x6d\x69\xab\x59\xa3\x79\x4f\x06\xfb\x07\x52\xce\x56\xc3\x13\x62\xfc\xb0\x6e\xc8\x75\x3c\xed\xfd\x3c\xed\x49\xc2\xeb\x3f\xa8\x65\xc1\x75\x5e\x51\x98\x5b\xe0\xe9\x5f\x1d\x05\x0e\x4b\xab\x54\xdb\x95\xf0\xf3\x6d\xb3\x58\x6c\xa8\x71\xbe\x2f\xe1\x97\x9f\x3e\xe9\x69\x23\xd5\xa4\x4f\x52\x18\x66\x18\x3f\xc0\x47\xab\x4c\x57\x51\xea\x95\xc3\x60\xb9\x9c\x03\x2f\x8e\xab\xce\x9f\x77\x2f\x81\x94\x8a\xf6\x66\xec\x31\xb3\xc1\xb2\xa6\xb1\x19\x57\xa4\x0c\x7a\xaa\x52\x57\xc9\x67\xb2\x4f\xce\x4b\x89\xfe\xd1\x9a\xfb\xe4\x6f\xef\x1c\xc7\x91\x6b\x71\x42\x42\xfa\x57\x6b\xfa\x12\xe4\xdd\xf5\xad\xb9\x08\x9e\x1d\x76\x96\xfa\x16\xfd\xf7\x89\x09\xe4\x72\xd7\x3a\xb7\xfd\x09\xac\xf4\x18\x3e\x87\xba\x54\x71\xcf\x41\x77\xe8\x07\x50\x21\x7e\xf1\xc4\x5c\xf7\x82\x22\xfb\x1d\xb0\xc5\xa9\xdc\xf9\xc3\x90\x3c\x87\x17\x38\x41\x04\x9e\x8b\xe2\x73\x2a\xf0\x85\xf8\xa7\x27\x2f\xa8\x40\xbf\x59\x70\xe3\xce\xed\x85\x06\x6b\x69\x00\x8b\xf7\xb0\x24\x4e\x96\x0d\xef\xc4\xe9\xa7\x8e\xb7\x32\x00\xa7\x73\x27\xbf\x86\x8c\x80\x7f\x71\x8d\xcc\x3e\xe0\xba\x38\x9d\x5d\x7e\x9a\x7f\xfb\x49\x9e\x1c\x32\x19\x31\x3e\xa9\xc9\x73\x26\x35\xe9\xed\xb9\x07\x0a\x85\xb9\xf2\x7c\x59\x9e\xac\x8c\x3a\x6f\xcf\xbc\xbe\x38\xb4\xa5\xfe\x49\x05\xf2\x0c\xcf\x97\x69\x7f\x6a\xde\x25\xdb\xa2\xe8\xb3\x96\xed\xc8\xeb\x75\xff\x0d\xcb\x5e\x78\xfd\xc3\x21\x16\x85\x3b\x32\xcd\xf0\xeb\x57\x98\x07\x49\x40\x93\x23\xaa\x34\xaf\x0c\xed\x3c\xc4\xe8\x9e\x4a\xcd\xd8\x3b\x56\x9b\x77\x55\xa5\x25\x6e\x68\xde\xf9\x4d\x58\xc6\xff\xb8\x27\xb9\xd6\x49\x2e\x84\xc3\x01\x3c\xda\x0d\x3d\x27\x99\xc5\xb7\x15\x3c\x3e\x1e\x0e\x73\x75\xc3\xd7\xff\x05\x00\x00\xff\xff\x72\xdd\xb4\x72\xcc\x13\x00\x00"), + compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcc\x58\xdd\x8f\xe3\xb6\x11\x7f\xdf\xbf\x62\xb0\x79\x28\x50\x58\xf2\x5e\x36\x09\x50\x1d\xee\xe1\xda\x34\xb9\x03\x72\xdb\x45\xf6\x50\xa0\x4f\x31\x4d\x8d\x2d\x76\x29\x52\x25\x47\x76\xd5\x43\xfa\xb7\x17\x43\x7d\x98\xb4\xa5\xfd\x28\x10\x20\xfb\x72\x3e\x91\x9c\x8f\xdf\xcc\x6f\x66\xc8\x2c\xcb\xae\x44\xa3\xfe\x8e\xce\x2b\x6b\x0a\x10\x4d\xe3\xd7\x87\x37\x57\x8f\xca\x94\x05\x7c\x8f\x8d\xb6\x5d\x8d\x86\xae\x6a\x24\x51\x0a\x12\xc5\x15\x80\x11\x35\x16\x50\xa1\xae\x33\xdb\xa0\x13\x64\xdd\xf0\xd5\x37\x42\x62\x01\x5f\xbe\x40\x7e\x37\xfe\x17\x7e\xfd\xf5\xca\x37\x28\xf9\xa4\xc3\x46\x2b\x29\x7c\x01\x6f\xae\x00\x3c\x6a\x94\x64\x1d\xaf\x00\xd4\x82\x64\xf5\x93\xd8\xa2\xf6\xfd\x87\x25\x45\x9e\x9c\x20\xdc\x77\xfd\x2e\xea\x1a\x2c\xe0\x67\x94\x0e\x05\xe1\x15\x00\x61\xdd\x68\x41\x38\x48\x8d\xec\xe6\x3f\x9d\x28\x58\x52\xc1\x7f\xc2\x18\x4b\x82\x94\x35\xd1\xf6\xc6\xd9\x1a\xa9\xc2\xd6\xe7\xca\xae\xbd\x74\x82\xb5\x5f\x93\x6b\xf1\x3a\x6c\x1a\x3d\x0d\xbf\xd1\x1d\x94\xc4\xf7\x52\xda\xd6\xd0\xdd\xa2\xa6\x83\xd5\x6d\x8d\x93\x96\xaf\xc6\x7f\xe1\x1f\xb6\x85\xa3\xd2\x1a\x0c\x62\x09\x54\xa1\x47\xa0\xa3\x1d\x0f\x80\xda\x41\xc7\x5b\x84\x21\x20\x0b\xe8\x49\x6c\xb5\xf2\x15\x1c\x84\x56\xa5\x20\x2c\xe1\xf3\x4f\x0f\x93\x38\x69\x8d\x41\x19\x3c\x02\xb1\x17\xca\x78\x82\xcf\x4a\x6b\x74\xf9\x85\xea\x6c\x40\x86\xc2\x7a\x46\xda\x67\x52\x4c\xab\xc0\xb2\x76\x6a\xff\x49\x34\x45\xf4\x11\xe6\x0e\x65\xfd\xd6\x64\x5b\x89\x3b\xd1\x6a\xfa\x64\x4b\x2c\xe0\xe6\xbb\x9b\x9b\x0b\xfd\x0f\x1c\x50\x02\xbb\x0b\x01\x86\xcd\x63\xbb\x45\x67\x90\x30\x00\x4f\xda\x6f\x2e\xe1\x9a\xb3\x19\x1d\x45\x9a\x7d\x90\x9a\x9a\xdc\x7f\xbb\x7b\xe6\xe4\xb9\xcd\xdf\xcc\xd8\xfc\xb9\x42\xd8\x59\xad\xed\x51\x99\xfd\x10\x24\x50\x1e\x76\xd6\x41\xeb\xf9\x9b\x00\xd9\x7a\xb2\xb5\xf2\x58\xc2\xe6\xd1\xd8\xa3\xf9\xa5\xb2\x9e\xfc\x06\x76\x4a\xe3\x6a\x12\x75\xac\x94\xac\xfa\xe0\x9e\xe2\x6f\xa1\xb4\x63\xcc\xf9\x14\xff\x70\x60\x8f\x06\xf6\x8a\x98\x5b\xd6\x2b\xb2\xae\x03\x27\xa8\x42\x37\x09\xa3\x4a\x98\xc1\x80\x1f\x15\x7d\x68\xb7\x60\x1d\x67\x13\x68\xf5\x88\xf9\x29\xcb\x84\xf6\x76\x52\x55\x73\xce\x82\x3a\x61\xa0\x0c\xd9\x70\x4a\x5a\x43\x42\x19\x74\x2b\xd8\xa2\xb6\xc7\xcb\xe4\x61\x89\xb5\xe8\x7a\x81\x47\x4e\x48\xb2\x4c\x9d\x83\x2a\x11\x84\x81\x8d\xf7\xd5\x2f\x7d\x5a\x9c\x3b\xce\xc5\x46\x59\xc3\xb6\xd6\xd6\x61\x6f\xbb\x35\x08\x9b\x8f\x25\x2f\x51\xf7\x83\xd2\xb8\x79\x1b\x40\xe5\x0c\x16\x46\xe2\x6a\x44\x45\x38\x9c\x24\xf5\x0e\xa7\x42\x06\xf7\x4f\x50\xe5\x70\xf7\xe7\x22\x78\x85\x86\x5c\x07\x8f\xd8\x81\xaf\x6c\xab\x4b\xd8\x9e\x44\x5d\xf7\xb6\x5e\x0f\xc0\xf6\xf2\xae\x4f\x4e\x5c\xb3\xfe\x00\x18\x96\xa0\x0c\xfc\x77\x9d\x7b\x5f\xad\x97\x59\xe5\x7d\x55\x2a\xf7\x52\x3a\xed\x74\xfb\xef\xcc\xfb\xea\x79\x26\x71\x56\x7e\xf9\x92\xb1\x39\xf9\xc3\xc3\x87\x87\x29\xb5\xb9\x08\x4f\xd4\x7a\xf8\x00\x8d\x53\x07\x41\x18\xfc\x25\x0b\x42\x4a\xf4\x9e\xe1\x39\x61\xa3\xd0\xe7\x53\xdd\x1b\x0d\xdf\x2b\xca\x1e\xb1\x9b\xbe\x9f\x53\x0a\x2e\x28\xc5\xbd\x60\xc1\x14\x98\xf7\x20\xa4\x3f\x9a\x09\x50\x87\xa2\xcc\xac\xd1\xdd\x0a\x8e\x08\x47\x6b\xfe\x40\xb0\x45\x10\x5b\x8d\x6c\xbb\xac\x6a\x5b\x06\xaf\x51\xfb\xd8\xd1\xc5\x32\xaa\xfc\x44\xce\x29\x6d\x26\x82\x9e\x51\x89\x2a\x71\xa2\x00\x9f\xf7\x9c\xc0\x0c\x21\x43\xc7\x49\xd8\x63\xf7\x16\x30\xdf\xe7\x2b\x10\x63\x8e\x95\xa1\x77\xf2\xae\x1c\x3e\xee\x26\x11\xa9\xba\x7f\xb6\x9e\x42\x62\xfa\x56\x56\x91\xda\x55\x48\xc9\x01\x99\x84\x2e\x93\x20\xa1\x19\x97\x0e\x1a\xab\x0c\x79\x10\x04\x9b\x35\x92\x5c\x73\xb2\x94\x6b\x4e\x3f\x35\x10\x66\x03\xc2\x83\x18\x2d\x61\x0b\x4e\x65\x66\xe8\x1c\xad\xc7\x33\xa6\x3c\x62\xb7\xba\xac\x3f\x23\x87\xc7\xc2\x33\x09\x4a\x18\x2d\xb6\xf6\x80\x2b\x38\x2a\xaa\x02\xdb\x13\xe6\x0e\x44\x0b\xdd\x9e\x21\x40\x21\xab\x49\x0c\x63\xaa\x4c\x70\xbe\xcf\xa1\xb1\x1e\x60\x09\x15\x3a\x5c\x66\x54\x9a\x98\x2f\xa9\xf5\x81\x55\x7c\xac\x8f\xd4\xd3\xac\xfa\xff\x73\xd2\x94\xaf\x4b\x49\xb2\xa0\xea\xc6\x3a\x02\x61\xba\xa1\x5d\xc0\x07\xd4\x75\xc2\xcc\x53\x1a\x98\x30\x18\x28\x07\xd2\x61\xc0\x59\x68\x4e\xd1\x72\x6d\x1d\x70\x0f\x53\x3b\x25\x99\xe9\x7d\x70\x5a\xd7\x4f\x34\x67\x55\x3f\xc9\xf0\xb8\xfa\xcf\x54\xfd\xa0\xd2\x23\x85\xaf\x9b\x2c\x0b\x13\xcd\x29\x75\xb3\xde\xfa\x28\x51\xdd\xbe\xe5\x28\x2e\x76\x8b\x31\x84\xb1\x7f\x59\x27\x6a\xfd\xda\x60\xa6\x96\xc4\x28\xcd\x57\xca\x7e\x75\x72\x6c\x1a\xc0\xb2\x27\xa6\xc2\xa1\xcf\x3b\x0c\x2c\x36\x16\xae\x0b\x1e\x36\x3d\x5d\x83\xaa\xc5\x1e\xfb\x6e\x9f\x9c\xcc\xe1\x07\xd5\x47\x09\x6a\xee\xda\x0e\x25\x4f\xd4\x27\x79\x0e\x35\x0a\x8f\xdc\x95\x83\x0c\x38\xf4\xe3\x38\x93\xba\x22\x6a\x7c\xb1\x5e\x57\xed\x36\x2f\xad\x7c\x44\x97\x4b\x5b\xaf\x5d\xe0\xb9\x2c\xd7\x89\xa6\x35\x89\xbd\x8f\x04\x73\xa4\x78\xe4\xe6\x29\x9c\xd5\x93\xd8\x27\x34\x82\x5e\x5f\x01\x83\x64\x65\x67\xc5\x16\x6f\xf2\x9b\xfc\x26\x73\xf2\x4f\xe9\xb9\xfb\x56\xeb\x7b\xab\x95\xec\x0a\xf8\xb8\xbb\xb3\x74\xef\xd0\xc7\xae\x71\x22\x44\xc3\xf3\x84\x2b\x51\x13\xb5\x80\x29\x00\xf7\xd6\x51\x01\xb7\x37\xb7\x37\xd3\xaa\x56\x07\x34\xe8\xfd\xbd\xb3\x5b\x8c\x9b\x0c\xcb\xf8\xf1\xbc\xef\x34\x97\x02\xc2\x67\x41\x55\x01\xeb\x0a\x85\xa6\xea\x3f\xd1\x92\x32\x8a\xf9\xf2\x3d\x6a\xd1\x3d\xa0\xb4\xa6\x1c\x6e\x26\xe3\x1f\xa9\x1a\x6d\x4b\xd3\xda\xb7\xd3\x1a\x17\x00\xf5\x3b\xb5\xcc\xdb\xd6\x49\xf4\xb1\x05\x0e\xff\xd5\xa2\x27\x9f\x5a\x25\x9b\xb6\x80\x6f\x6f\xea\xe4\x63\x8d\xb5\x75\x5d\x01\xdf\x7d\xf3\x49\x4d\x0b\x7d\x71\xfa\xc4\x55\x21\x92\xf1\x55\x94\x6b\x1f\x8d\xd4\x6d\x89\x7d\x2d\x1b\xfa\x6a\x5a\x4d\x9e\x18\x7e\xad\x9b\x6b\x72\x2c\x96\xa7\xc3\xb7\xa7\x46\x14\x8d\xa8\x5c\x7d\xfa\x39\x6a\x33\xd6\xce\xd0\x78\xf2\x59\xf3\x66\x27\xaf\xbe\x34\x04\xeb\xee\xfb\x48\x38\x6b\x29\x0c\x6f\xc9\x0e\x0e\xf6\xdf\x8c\xee\x0a\xe0\x8b\xde\x73\x13\xd6\x78\x15\x98\x99\xb3\xb8\xcf\x72\x7d\xe0\x41\xab\x67\x57\x28\xc6\x11\xfe\xcb\x83\x56\x6a\x68\xd2\xea\x67\xa6\x9f\xe7\x83\xf3\xcc\xd0\x93\x0c\x3b\x91\xa8\xd8\xa3\x78\xfc\x59\x0a\xd1\xe0\xc8\x6b\x62\x74\xee\xfb\x79\x90\x66\x7c\x8f\xbb\xec\xf3\xae\x8f\x63\x4f\xd4\x68\x2f\x3a\xec\xa9\xb3\x46\xc2\x5e\xd5\x63\x97\x30\x89\xe4\x6d\x2e\x7a\x5e\x8a\xd3\x6a\xb4\xe2\xf9\x46\x1b\xb7\xda\xb4\xd3\xce\x83\xbc\xd4\x6d\x97\x38\xc1\xda\xd7\x27\xed\xeb\xe4\x9e\x90\x9e\x9f\x45\x1f\x3d\xbe\xf0\xbd\x22\x7e\xa7\x88\x9d\x4b\x5e\x2c\x96\x13\xee\xec\x0e\xbf\x61\x08\x63\xc8\x93\xc7\x89\xcd\xf4\x96\x52\xa2\xd4\xc2\x61\x39\x03\x7c\x74\xe2\x8f\x73\x70\xfb\x97\xe0\x3d\xff\xb4\xf0\x54\x72\x33\xe2\x4f\x95\xa1\xa7\x75\x88\x17\x6a\x38\xdf\xb9\xa0\x44\xb8\x7d\xd2\x3c\x38\xb4\x70\x0c\x75\x62\x7a\xe8\xeb\x23\x03\x52\x18\x9e\x85\x77\xb6\x35\x65\x7c\x83\x9c\x80\x9c\x4e\xbc\xe3\xcb\x61\x7f\x2a\x79\x2e\x9c\xc3\xf1\x2f\xb6\x0e\xa9\x6d\xdb\x90\x3b\x2f\x4b\x9f\x85\x67\xae\xf3\x08\x25\x21\x96\x22\x04\x28\xe3\xde\xfc\xee\x12\xac\xb5\x14\xb9\x4c\xe2\x77\x76\x1e\x0d\xdf\x02\xde\x5d\x84\x28\xd9\xf4\x88\xdd\xac\x82\x35\x69\x9f\xa7\xb5\xef\xdc\xbc\x25\xdb\xc2\xd1\x27\x2d\x3b\xa0\x53\xbb\xee\x19\xcb\x5e\xeb\xfe\x6f\x5f\x6a\x7f\xf3\x4a\x6b\xca\xf1\x67\xa0\xc9\xea\xe9\x1e\xb5\x54\x88\xdf\x1d\xbe\x2e\x5e\x5a\x2b\x57\x87\xdb\x17\xef\x9d\xc6\x0d\xc6\x6d\x78\xa8\xf7\xe9\xb4\xf1\xd7\x90\x72\x65\x8f\xec\x61\xdc\x12\xba\xf8\x40\x46\x12\x6e\x8f\x4c\x90\x6d\x07\x02\x36\xbc\xf1\xe7\xfe\xd6\xb1\x49\x29\xda\x67\x6f\xd9\xfb\x38\x8a\x0a\x3c\x3d\x57\xff\xdc\xcc\x71\x46\xd8\x5e\x30\x08\xe0\x91\x43\x63\x62\xeb\xac\xa9\x91\xa8\x4b\xa3\xdf\x8e\xd7\x39\xcf\xb2\x37\x4b\x76\x1f\xbe\x5e\x1d\x6e\x37\xcb\x91\x5c\x38\x75\x1b\x0f\x15\x23\xfc\xef\xcb\x52\x71\xb6\x09\xfd\xde\xed\xcf\x02\x70\x5a\x3b\x35\x85\x2b\x00\x3e\xea\x84\xd9\xe3\x53\xa7\xb3\xf0\x44\xd6\x7f\x39\x53\x3b\xfc\xfc\x5f\x00\x00\x00\xff\xff\xec\x58\x51\x23\xa5\x19\x00\x00"), }, "/rbac.yaml.tmpl": &vfsgen۰CompressedFileInfo{ name: "rbac.yaml.tmpl", diff --git a/pkg/install/templates/deployment.yaml.tmpl b/pkg/install/templates/deployment.yaml.tmpl index 8e009a7c6..ff1f01814 100644 --- a/pkg/install/templates/deployment.yaml.tmpl +++ b/pkg/install/templates/deployment.yaml.tmpl @@ -3,9 +3,7 @@ apiVersion: apps/v1 kind: Deployment metadata: name: helm-operator -{{- if .Namespace }} namespace: {{ .Namespace }} -{{- end }} spec: replicas: 1 selector: @@ -24,26 +22,28 @@ spec: volumes: # # You will need these two volumes if you want to establish validated TLS - # connections against Tiller + # connections against Tiller. # - # - name: helm-tls-ca + # - name: tiller-tls-ca # configMap: - # name: flux-helm-tls-ca-config + # name: tiller-tls-ca-config # defaultMode: 0600 - # Secret type kubernetes.io/tls - # - name: flux-helm-tls-cert + # + # Secret of type `kubernetes.io/tls`: + # + # - name: tiller-tls-cert # secret: # secretName: tiller-tls-cert # defaultMode: 0400 # - # The following volume is for using a customised known_hosts file, - # which you will need to do if you host your own git repo rather - # than using github or the like. You'll also need to mount it + # The following volume is for using a customised `known_hosts` file, + # which you will need to do if you host your own git repository rather + # than using GitHub or the like. You will also need to mount it # into the container, below. # - # You may also wish to provide an ssh_config file, - # mentioning more than one `IdentityFile`; for instance, if you're - # using more than one GitHub repo. NB the entry key should be + # You may also wish to provide an `ssh_config` file, + # mentioning more than one `IdentityFile`; for instance, if you are + # using more than one GitHub repository. NB: the entry key should be # "config" rather than "ssh_config" if mounted in ~/.ssh/. # # - name: sshdir @@ -51,41 +51,40 @@ spec: # name: flux-ssh-config # defaultMode: 0400 {{- if .SSHSecretName }} - # SSH key to access the Git repository + # SSH private key to access Git repositories. - name: git-key secret: secretName: {{ .SSHSecretName }} defaultMode: 0400 # when mounted read-only, we won't be able to chmod {{- else }} # - # You will need this volume if you're using a git repo that + # You will need this volume if you are using a git repository that # needs an SSH key for access; e.g., a GitHub deploy key. If - # you're using just one such repo, the default ssh_config - # already points at /etc/fluxd/ssh/identity as a key. If you - # want to use more than one key, you'll need to provide your own - # ssh_config above, with an `IdentityFile` entry matching each + # you are using just one such repository, the default `ssh_config` + # already points at `/etc/fluxd/ssh/identity` as a key. If you + # want to use more than one key, you will need to provide your own + # `ssh_config` above, with an `IdentityFile` entry matching each # key in the secret mentioned here. # # - name: git-key # secret: # secretName: flux-git-deploy # defaultMode: 0400 # when mounted read-only, we won't be able to chmod +{{- end }} # -{{- end}} - # These two volumes are for mounting a repositories.yaml file, - # and providing a cache directory. The latter is needed because - # mounting the former will make the cache/ directory read-only. + # You will need this volume to import any custom Helm repositories + # and their credentials and/or certificate configurations. You will also + # need to mount it into the container and set the `--helm-repository-import` + # argument, below. # # - name: repositories-yaml # secret: # secretName: flux-helm-repositories - # - name: repositories-cache - # emptyDir: {} - + # defaultMode: 0400 containers: - name: helm-operator # There are no ":latest" images for helm-operator. Find the most recent - # release or image version at https://hub.docker.com/r/weaveworks/helm-operator/tags + # release or image version at https://hub.docker.com/r/fluxcd/helm-operator/tags # and replace the tag here. image: docker.io/fluxcd/helm-operator:1.0.0-rc9 imagePullPolicy: IfNotPresent @@ -109,42 +108,76 @@ spec: cpu: 50m memory: 64Mi volumeMounts: - # Include this if you need to mount a customised known_hosts or ssh_config - # file; you'll also need the volume declared above. + # + # Include this if you need to mount a customised `known_hosts` or `ssh_config` + # file; you will also need the `sshdir` volume above. + # # - name: sshdir # mountPath: /root/.ssh # readOnly: true {{- if .SSHSecretName }} + # The SSH private key to use for Git operations. - name: git-key mountPath: /etc/fluxd/ssh {{- else }} + # + # Include this if you are using a git repository that needs an SSH + # private key for access; you will also need the `git-key` volume above. + # # - name: git-key # mountPath: /etc/fluxd/ssh {{- end }} + # + # Include this if you want to import any Helm repositories and their + # credentials and/or certificate configurations; you will also need the + # `repositories-yaml` volume above, and the `--helm-repository-import` + # argument below. + # # - name: repositories-yaml - # mountPath: /var/fluxd/helm/repository - # - name: repositories-cache - # mountPath: /var/fluxd/helm/repository/cache - # - name: helm-tls-certs + # mountPath: /root/.helm/repository/repositories.yaml + # + # Include these if you want to establish validated TLS connections + # against Tiller; you will also need the `tiller-tls-cert` and + # `tiller-tls-ca` volumes declared above, and the `--tiller-tls-*` + # arguments below. + # + # - name: tiller-tls-cert # mountPath: /etc/fluxd/helm # readOnly: true - # - name: helm-tls-ca + # - name: tiller-tls-ca # mountPath: /etc/fluxd/helm-ca # readOnly: true args: - # How to find Tiller + # In what namespace Tiller can be found. - --tiller-namespace={{ .TillerNamespace }} - # Comment out to to establish validated TLS connections against Tiller + # + # Comment out to to establish validated TLS connections against Tiller. + # # - --tiller-tls-ca-cert-path=/etc/fluxd/helm-ca/ca.crt # - --tiller-tls-enable=true # - --tiller-tls-key-path=/etc/fluxd/helm/tls.key # - --tiller-tls-cert-path=/etc/fluxd/helm/tls.crt # - --tiller-tls-verify=true # - --tiller-tls-ca-cert-path=/etc/fluxd/helm-ca/ca.crt -{{ if .HelmVersions }} + # + # Include this if you want to import any Helm repositories and their + # credential and/or certificate configurations; you will also need the + # `repositories-yaml` volume and volume mount, above. + # + # - --helm-repository-import=v2:/root/.helm/repository/repositories.yaml,v3:/root/.helm/repository/repositories.yaml +{{- if .HelmVersions }} + # Enabled Helm versions that can be targeted by a `HelmRelease`. - --enabled-helm-versions={{ .HelmVersions }} +{{- else }} + # + # Comment out to enable a single Helm version that can be targeted + # by a `HelmRelease`; defaults to `--enabled-helm-versions=v2,v3`. + # + # - --enabled-helm-versions=v3 {{- end }} {{- if .AdditionalArgs }} - # Additional arguments{{ range .AdditionalArgs }} - - {{ . }}{{ end }} + # Additional arguments + {{- range .AdditionalArgs }} + - {{ . }} + {{- end }} {{- end }}