From 0cb83769be3f1add12e6239e7097f68e4e141521 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Thu, 2 Nov 2023 15:24:08 +0000 Subject: [PATCH 1/4] Explain how to install cert-manager using Flux Signed-off-by: Richard Wall --- content/docs/installation/helm.md | 97 ++++++++++++++++++++++++++++++- 1 file changed, 95 insertions(+), 2 deletions(-) diff --git a/content/docs/installation/helm.md b/content/docs/installation/helm.md index b5a78cb483e..0aabc500874 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,100 @@ 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. + +## Install the Helm chart using Flux + +The cert-manager Helm chart can be installed by [Flux](https://fluxcd.io/). + +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.0 <1.13.0' +``` + +### Updates and Upgrades + +And when you want to upgrade to the cert-manager 1.13 release, +you can simply update the semantic version range 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.12.0 <1.14.0' +``` + +### 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 +``` From 3bda8cb9c142a322c45b6ffc74d5bd8f8afed88b Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Thu, 2 Nov 2023 15:45:05 +0000 Subject: [PATCH 2/4] Update content/docs/installation/helm.md Co-authored-by: Josh Soref <2119212+jsoref@users.noreply.github.com> Signed-off-by: Richard Wall --- content/docs/installation/helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/installation/helm.md b/content/docs/installation/helm.md index 0aabc500874..6bbb421fbad 100644 --- a/content/docs/installation/helm.md +++ b/content/docs/installation/helm.md @@ -292,7 +292,7 @@ discuss. The cert-manager Helm chart can be installed by [Flux](https://fluxcd.io/). First create a [`HelmRepository` resource](https://fluxcd.io/flux/components/source/helmrepositories/), -configured with URL of the cert-manager Helm repository. +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. From 72b590e1418292ff08f6a47ffc692f4b34f74902 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Fri, 3 Nov 2023 11:14:40 +0000 Subject: [PATCH 3/4] Use the shorter .x semver range syntax Signed-off-by: Richard Wall --- content/docs/installation/helm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/installation/helm.md b/content/docs/installation/helm.md index 6bbb421fbad..1e911a10bd9 100644 --- a/content/docs/installation/helm.md +++ b/content/docs/installation/helm.md @@ -338,13 +338,13 @@ flux create helmrelease cert-manager \ --create-target-namespace \ --crds CreateReplace \ --values values.yaml \ - --chart-version '>1.12.0 <1.13.0' + --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 semantic version range in the chart version: +you can simply update the partial semantic version in the chart version: ```bash flux create helmrelease cert-manager \ @@ -355,7 +355,7 @@ flux create helmrelease cert-manager \ --create-target-namespace \ --crds CreateReplace \ --values values.yaml \ - --chart-version '>1.12.0 <1.14.0' + --chart-version 1.13.x ``` ### Troubleshooting From c88984a7f1513b6478b1178acf696bff26e1a88a Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Fri, 3 Nov 2023 12:29:20 +0000 Subject: [PATCH 4/4] Create a new Continuous Deployment page Signed-off-by: Richard Wall --- content/docs/installation/README.md | 11 +- .../continuous-deployment-and-gitops.md | 110 ++++++++++++++++++ content/docs/installation/helm.md | 94 +-------------- content/docs/manifest.json | 4 + 4 files changed, 122 insertions(+), 97 deletions(-) create mode 100644 content/docs/installation/continuous-deployment-and-gitops.md 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 1e911a10bd9..870cc78a0d8 100644 --- a/content/docs/installation/helm.md +++ b/content/docs/installation/helm.md @@ -286,96 +286,8 @@ support, then please [raise an issue](https://github.com/cert-manager/cert-manager/issues) to discuss. +## Using the Flux Helm Controller -## Install the Helm chart using Flux +The cert-manager Helm chart can be installed and upgraded by the Flux Helm Controller. -The cert-manager Helm chart can be installed by [Flux](https://fluxcd.io/). - -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 -``` +> 📖 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"