From 26eb6ca50207ead8dc16b60d56fae77c47ff872b Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Thu, 8 Aug 2019 13:41:34 +0200 Subject: [PATCH] Remove Helm operator docs They are now managed as a child project in RTD, and the docs reside in the Helm operator repository. --- docs/helm-operator/faq.md | 42 --- docs/helm-operator/guides/index.rst | 10 - .../helm-operator/guides/upgrading-to-beta.md | 154 -------- docs/helm-operator/index.rst | 15 - .../references/helmrelease-custom-resource.md | 334 ------------------ docs/helm-operator/references/index.rst | 11 - docs/helm-operator/references/operator.md | 40 --- docs/helm-operator/troubleshooting.md | 27 -- docs/helm-operator/tutorials/get-started.md | 175 --------- docs/helm-operator/tutorials/index.rst | 10 - docs/index.rst | 6 - 11 files changed, 824 deletions(-) delete mode 100644 docs/helm-operator/faq.md delete mode 100644 docs/helm-operator/guides/index.rst delete mode 100644 docs/helm-operator/guides/upgrading-to-beta.md delete mode 100644 docs/helm-operator/index.rst delete mode 100644 docs/helm-operator/references/helmrelease-custom-resource.md delete mode 100644 docs/helm-operator/references/index.rst delete mode 100644 docs/helm-operator/references/operator.md delete mode 100644 docs/helm-operator/troubleshooting.md delete mode 100644 docs/helm-operator/tutorials/get-started.md delete mode 100644 docs/helm-operator/tutorials/index.rst diff --git a/docs/helm-operator/faq.md b/docs/helm-operator/faq.md deleted file mode 100644 index 741372df42..0000000000 --- a/docs/helm-operator/faq.md +++ /dev/null @@ -1,42 +0,0 @@ -# Frequently asked questions - -### I'm using SSL between Helm and Tiller. How can I configure Flux to use the certificate? - -When installing Flux, you can supply the CA and client-side certificate using the `helmOperator.tls` options, -more details [here](https://github.com/fluxcd/flux/blob/master/chart/flux/README.md#installing-weave-flux-helm-operator-and-helm-with-tls-enabled). - -### I've deleted a HelmRelease file from Git. Why is the Helm release still running on my cluster? - -Flux doesn't delete resources, there is an [issue](https://github.com/fluxcd/flux/issues/738) opened about this topic on GitHub. -In order to delete a Helm release first remove the file from Git and afterwards run: - -```yaml -kubectl delete helmrelease/my-release -``` - -The 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 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. - -### I have a dedicated Kubernetes cluster per environment and I want to use the same Git repo for all. How can I do that? - -*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`. - -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"`. - -*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`. - -### Are there prerelease builds I can run? - -There are builds from CI for each merge to master branch. See -[fluxcd/helm-operator-prerelease](https://hub.docker.com/r/fluxcd/helm-operator-prerelease/tags). diff --git a/docs/helm-operator/guides/index.rst b/docs/helm-operator/guides/index.rst deleted file mode 100644 index 1dd0c6674d..0000000000 --- a/docs/helm-operator/guides/index.rst +++ /dev/null @@ -1,10 +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-beta diff --git a/docs/helm-operator/guides/upgrading-to-beta.md b/docs/helm-operator/guides/upgrading-to-beta.md deleted file mode 100644 index 7270adb2fb..0000000000 --- a/docs/helm-operator/guides/upgrading-to-beta.md +++ /dev/null @@ -1,154 +0,0 @@ -# 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 [Helm operator set-up -guide](../../references/helm-operator-integration.md) and [example -deployment](https://github.com/fluxcd/flux/blob/master/deploy-helm/helm-operator-deployment.yaml) -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/helm-operator/index.rst b/docs/helm-operator/index.rst deleted file mode 100644 index 9eac5cdd7b..0000000000 --- a/docs/helm-operator/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/helm-operator/references/helmrelease-custom-resource.md b/docs/helm-operator/references/helmrelease-custom-resource.md deleted file mode 100644 index eb8a4de1e8..0000000000 --- a/docs/helm-operator/references/helmrelease-custom-resource.md +++ /dev/null @@ -1,334 +0,0 @@ -# `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/flux/blob/master/deploy-helm/flux-helm-release-crd.yaml). They -look like this: - -```yaml -apiVersion: flux.weave.works/v1beta1 -kind: HelmRelease -metadata: - name: rabbit - namespace: default -spec: - releaseName: rabbitmq - 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 namespace to the -resource name. In the above example, if `releaseName` were not given, -it would be generated as `default-rabbitmq`. Because of the way Helm -works, release names must be unique in the cluster. - -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 `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 (which defaults to `master`, if not -supplied). 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. - -## 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: flux.weave.works/v1beta1 -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`) 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, must be in the same namespace as the - # HelmRelease - name: default-values # mandatory - # 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, must be in the same namespace as the - # HelmRelease - name: default-values # mandatory - # 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: flux.weave.works/v1beta1 -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/flux/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 -``` - -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/flux/blob/master/deploy-helm/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/flux/blob/master/deploy-helm/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`. diff --git a/docs/helm-operator/references/index.rst b/docs/helm-operator/references/index.rst deleted file mode 100644 index 092ec11694..0000000000 --- a/docs/helm-operator/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/helm-operator/references/operator.md b/docs/helm-operator/references/operator.md deleted file mode 100644 index 02a73d8d01..0000000000 --- a/docs/helm-operator/references/operator.md +++ /dev/null @@ -1,40 +0,0 @@ -# Helm operator (`helm-operator`) - -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. - -## Responsibilities - -When the Helm Operator sees a `HelmRelease` resource in the -cluster, it either installs or upgrades the named Helm release so that -the chart is released as specified. - -It will also notice when a `HelmRelease` resource is updated, and -take action accordingly. - -## Setup and configuration - -`helm-operator` requires setup and offers customization though a multitude of flags. - -| 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. -| **Tiller options** -| --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. -| --tiller-tls-enable | `false` | Enable TLS communication with Tiller. If provided, requires TLSKey and TLSCert to be provided as well. -| --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-hostname | | The server name used to verify the hostname on the returned certificates from the Tiller server. -| **repo chart changes** (none of these need overriding, usually) -| --charts-sync-interval | `3m` | Interval at which to check for changed charts. -| --git-timeout | `20s` | Duration after which git operations time out. -| --git-poll-interval | `5m` | Period on which to poll git chart sources for changes. -| --log-release-diffs | `false` | Log the diff when a chart release diverges. **Potentially insecure.** -| --update-chart-deps | `true` | Update chart dependencies before installing or upgrading a release. diff --git a/docs/helm-operator/troubleshooting.md b/docs/helm-operator/troubleshooting.md deleted file mode 100644 index 9a9d2f78ba..0000000000 --- a/docs/helm-operator/troubleshooting.md +++ /dev/null @@ -1,27 +0,0 @@ -# Troubleshooting - -Also see the [issues labeled with -`FAQ`](https://github.com/fluxcd/flux/labels/FAQ), which often -explain workarounds. - -## 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: - -```bash -$ kubectl get configmaps flux-helm-tls-ca-config -o yaml -apiVersion: v1 -data: - ca.crt: | - -----BEGIN CERTIFICATE----- - .... - -----END CERTIFICATE----- -kind: ConfigMap -metadata: - creationTimestamp: 2018-07-04T15:27:25Z - name: flux-helm-tls-ca-config - namespace: helm-system - resourceVersion: "1267257" - selfLink: /api/v1/namespaces/helm-system/configmaps/flux-helm-tls-ca-config - uid: c106f866-7f9e-11e8-904a-025000000001 -``` diff --git a/docs/helm-operator/tutorials/get-started.md b/docs/helm-operator/tutorials/get-started.md deleted file mode 100644 index 3453cfd7cd..0000000000 --- a/docs/helm-operator/tutorials/get-started.md +++ /dev/null @@ -1,175 +0,0 @@ -# Get started with the Helm operator - -## Installing Helm / Tiller - -Generate certificates for Tiller and Flux. This will provide a CA, servercerts for Tiller and client certs for Helm / Flux. - -> **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 deploy Helm with TLS and RBAC enabled; - -Create a file called `helm-rbac.yaml`. This contains all 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 -``` - -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://charts.fluxcd.io - -helm upgrade --install \ - --set helmOperator.create=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. diff --git a/docs/helm-operator/tutorials/index.rst b/docs/helm-operator/tutorials/index.rst deleted file mode 100644 index a37796c8e8..0000000000 --- a/docs/helm-operator/tutorials/index.rst +++ /dev/null @@ -1,10 +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 diff --git a/docs/index.rst b/docs/index.rst index bcf4f58b99..68d0f9af91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,12 +21,6 @@ Welcome to the Flux documentation! faq troubleshooting -.. toctree:: - :maxdepth: 3 - :caption: Helm operator - - helm-operator/index - .. toctree:: :maxdepth: 2 :caption: Contributing