diff --git a/content/docs/installation/README.md b/content/docs/installation/README.md index d15788c88cd..2237153d06a 100644 --- a/content/docs/installation/README.md +++ b/content/docs/installation/README.md @@ -32,10 +32,9 @@ which you can do from the OpenShift web console. ## Continuous deployment -> You know how to configure your cert-manager setup and want to automate this. +> If you know how to configure your cert-manager setup and want to automate this, +> you can use the cert-manager Helm chart directly with tools like Flux, ArgoCD and Anthos. +> Or you can output YAML using `helm template` to generate customized cert-manager installation manifests, +> which can be piped into your preferred deployment tool. -📖 **helm**: You can use [the cert-manager Helm chart](./helm.md) directly with systems like Flux, ArgoCD and Anthos. - -📖 **helm template**: You can use `helm template` to generate customized cert-manager installation manifests. -See [Output YAML using helm template](./helm.md#output-yaml) for more details. -This templated cert-manager manifest can be piped into your preferred deployment tool. +📖 **Continuous Deployment**: Learn [how to automate the installation of cert-manager using tools like Flux and Argo CD](./continuous-deployment-and-gitops.md). diff --git a/content/docs/installation/continuous-deployment-and-gitops.md b/content/docs/installation/continuous-deployment-and-gitops.md new file mode 100644 index 00000000000..45cfc450ea2 --- /dev/null +++ b/content/docs/installation/continuous-deployment-and-gitops.md @@ -0,0 +1,110 @@ +--- +title: Continuous Deployment +description: Learn how to automate the installation of cert-manager using tools like Flux and Argo CD +--- + +Learn how to automate the installation of cert-manager using tools like Flux and Argo CD. + +## Introduction + +You can use [the cert-manager Helm chart](./helm.md) directly with tools like Flux, ArgoCD and Anthos, +and you can [output YAML using helm template](./helm.md#output-yaml) to generate customized cert-manager installation manifests, +which can be piped into your preferred deployment tool. + +This page contains notes about how to install cert-manager with *some* of these tools. + +> 📢 Please help us improve this page +> by contributing notes or short tutorials about using cert-manager with common GitOps and continuous deployment tools. + +## Using the Flux Helm Controller + +The cert-manager Helm chart can be installed by the [Flux Helm Controller](https://fluxcd.io/flux/components/helm/). + +First create a [`HelmRepository` resource](https://fluxcd.io/flux/components/source/helmrepositories/), +configured with URL of the cert-manager Helm repository. +Then create a [`HelmRelease` resource](https://fluxcd.io/flux/components/helm/helmreleases/), +configured with your desired cert-manager chart values and release. + +Here is an example which installs the latest patch version of the cert-manager 1.12 release, +and then upgrades to the latest patch version of the 1.13 release. + +### Prerequisites + +You'll need the [`flux` CLI](https://fluxcd.io/flux/cmd/) +and a Kubernetes cluster with [Flux installed](https://fluxcd.io/flux/installation/). + +Here's how to quickly install Flux on a [Kind](https://kind.sigs.k8s.io/) cluster: + +```bash +kind create cluster +flux check --pre +flux install +flux check +``` + +### Create a `HelmRepository` resource + +```bash +flux create source helm cert-manager --url https://charts.jetstack.io +``` + +### Create a `HelmRelease` resource + +Put your Helm chart values in a `values.yaml` file. +Use the `installCRDs` value, so that Flux can install and upgrade the CRD resources. + +```yaml +# values.yaml +installCRDs: true +``` + +```bash +flux create helmrelease cert-manager \ + --chart cert-manager \ + --source HelmRepository/cert-manager.flux-system \ + --release-name cert-manager \ + --target-namespace cert-manager \ + --create-target-namespace \ + --crds CreateReplace \ + --values values.yaml \ + --chart-version 1.12.x +``` + +### Updates and Upgrades + +And when you want to upgrade to the cert-manager 1.13 release, +you can simply update the partial semantic version in the chart version: + +```bash +flux create helmrelease cert-manager \ + --chart cert-manager \ + --source HelmRepository/cert-manager.flux-system \ + --release-name cert-manager \ + --target-namespace cert-manager \ + --create-target-namespace \ + --crds CreateReplace \ + --values values.yaml \ + --chart-version 1.13.x +``` + +### Troubleshooting + +Check Flux events and logs for warnings and errors: + +```bash +flux events +flux logs +``` + +Use `cmctl` to check for problems with the cert-manager webhook or CRDs: + +```bash +cmctl check api +cmctl version -o yaml +``` + +Check the cert-manager logs for warnings and errors: + +```bash +kubectl logs -n cert-manager -l app.kubernetes.io/instance=cert-manager --prefix --all-containers +``` diff --git a/content/docs/installation/helm.md b/content/docs/installation/helm.md index b5a78cb483e..870cc78a0d8 100644 --- a/content/docs/installation/helm.md +++ b/content/docs/installation/helm.md @@ -247,7 +247,7 @@ of their approach [here](https://helm.sh/docs/chart_best_practices/custom_resour cert-manager actually bundles the CRDs along with the other templates in the Helm chart. This means that Helm manages these resources so they are -upgraded with your cert-manager release when you use +upgraded with your cert-manager release when you use `installCRDs: true` in your values file or CLI command. This does also mean that if you uninstall the release, the CRDs will also be uninstalled. If that happens then you will loose all instances of those CRDs, e.g. all `Certificate` @@ -282,7 +282,12 @@ Generally we recommend: You may want to consider your approach along with other tools that may offer helm compatible installs, for a standardized approach to managing CRD resources. If you have an approach that cert-manager does not currently -support, then please +support, then please [raise an issue](https://github.com/cert-manager/cert-manager/issues) to discuss. +## Using the Flux Helm Controller + +The cert-manager Helm chart can be installed and upgraded by the Flux Helm Controller. + +> 📖 Read more at [Continuous Deployment: Using the Flux Helm Controller](./continuous-deployment-and-gitops.md). diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 6d81d5889c9..dd806729969 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -285,6 +285,10 @@ "title": "c. OperatorHub (OLM)", "path": "/docs/installation/operator-lifecycle-manager.md" }, + { + "title": "d. Continuous Deployment", + "path": "/docs/installation/continuous-deployment-and-gitops.md" + }, { "title": "Configuring Components", "path": "/docs/installation/configuring-components.md"