diff --git a/charts/enterprise/clusterissuer/docs/how-to.md b/charts/enterprise/clusterissuer/docs/how-to.md index 311822a9c5c..b58c7e74ba4 100644 --- a/charts/enterprise/clusterissuer/docs/how-to.md +++ b/charts/enterprise/clusterissuer/docs/how-to.md @@ -4,26 +4,17 @@ This guide will walk you through setting up `clusterissuer`, certificate managem ## Prerequisites -Ensure you have the `enterprise` train enabled for `TrueCharts` as discussed [here](https://truecharts.org/manual/SCALE/guides/getting-started/#adding-truecharts). +- Ensure you have the `enterprise` train enabled for `TrueCharts` as discussed [here](https://truecharts.org/manual/SCALE/guides/getting-started/#adding-truecharts). +- Traefik is installed from enterprise train -Ensure you have traefik installed, required for Ingress. +## Set Scale Nameservers -Search for clusterissuer in the `Apps` menu | `Available Applications` tab and click **Install**. +It is important to configure Scale with reliable nameserver to avoid issues handling DNS-01 challenges. Under Network -> Global Configuration-> Nameservers, we recommend setting 1.1.1.1, 9.9.9.9 or 8.8.8.8. -## Cloudflare DNS-Provider +![clusterissuer scale nameservers](img/scale-network-nameserver.png) -You can setup multiple domains with a single `clusterissuer` app, all you have to do is either add the global API key (**not recommended**) or `Add` multiple `ACME Issuer` entries for each domain and create an API token for each at [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens). The recommended settings for creating `API Tokens` for use with `clusterissuer` can be found on the upstream [Cert-Manager](https://cert-manager.io/) documentation for [Cloudflare](https://cert-manager.io/docs/configuration/acme/dns01/cloudflare/). -- Give the certificate a name (eg domain or "maincert", etc). -- Select the correct provider, for example `Cloudflare`. -- Set **Server** to **Letsencrypt-Production**. -- Set Email to the account email. -- Optionally set Cloudflare API key (**not recommended**) -- Set the Cloudflare API Token to the one created earlier. - -![clusterissuer edit dialog](img/clusterissuer1.png) - -## clusterissuer App +## Install clusterissuer App :::note @@ -33,7 +24,47 @@ It is by design that the app does not run, there are no events, no logs and no s ![clusterissuer app card](img/clusterissuer2.png) -## How to Add Ingress to Apps with clusterissuer +## Configure ACME Issuer + +You can setup multiple domains and/or DNS providers with a single `clusterissuer` app. + +### Cloudflare DNS Provider + +#### Create a Cloudflare API token + +Login to Cloudflare dashboard and go to the [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) page. Select Edit Zone DNS template. + +![clusterissuer app card](img/cf-apitokens-template.png) + +The recommended `API Token` permissions are below: +![clusterissuer app card](img/cf-apitokens-perms.png) + +#### Cloudflare ACME Issuer Settings + +- **Name**: Name of the issuer entry; such as "cert" or "cloudflareprod". This name will be used later in the app ingress configuration +- **Type of DNS Provider**: `Cloudflare` +- **Server**: `Letsencrypt-Production` +- **Email**: The email address you register with Let's Encrypt for renewal/expiration notices +- **Cloudflare API key**: Leave blank since API token will be used +- **Cloudflare API Token**: Populate with token created from above. + +![clusterissuer edit dialog](img/clusterissuer-appconfig.png) + +More detail can be found on the upstream [Cert-Manager](https://cert-manager.io/) documentaition for [Cloudflare](https://cert-manager.io/docs/configuration/acme/dns01/cloudflare/). + +### Route 53 DNS Provider + +To be completed + +### Akamai DNS Provider + +To be completed + +### Digital Ocean DNS Provider + +To be completed + +## Configure Ingress using clusterissuer Here's an example on how to add ingress to an app with clusterissuer for a single domain only. @@ -45,9 +76,9 @@ Do **NOT** use this combined with the `TLS-Settings`. ::: -![how to add ingress using clusterissuer ](img/clusterissuer3.png) +![configure ingress using clusterissuer ](img/clusterissuer-ingressconfig.png) -If you want to support multiple domains, use the `TLS-Settings` option to create each one, basically an extra step each time. +If you want to support multiple domains on a single app, under `Show Advanced Settings` checkbox, use the `TLS-Settings` option to create each one with the Add button. ## Verifying clusterissuer is working @@ -56,4 +87,4 @@ Once installed using the Ingress settings above, you can see the `Application Ev ![clusterissuer4](img/clusterissuer4.png) ![clusterissuer5](img/clusterissuer5.png) -All is automated by `clusterissuer` +Renewals are handled automatically by `clusterissuer`. diff --git a/charts/enterprise/clusterissuer/docs/img/cf-apitokens-perms.png b/charts/enterprise/clusterissuer/docs/img/cf-apitokens-perms.png new file mode 100644 index 00000000000..4d15c50f9ae Binary files /dev/null and b/charts/enterprise/clusterissuer/docs/img/cf-apitokens-perms.png differ diff --git a/charts/enterprise/clusterissuer/docs/img/cf-apitokens-template.png b/charts/enterprise/clusterissuer/docs/img/cf-apitokens-template.png new file mode 100644 index 00000000000..32b32677739 Binary files /dev/null and b/charts/enterprise/clusterissuer/docs/img/cf-apitokens-template.png differ diff --git a/charts/enterprise/clusterissuer/docs/img/clusterissuer-appconfig.png b/charts/enterprise/clusterissuer/docs/img/clusterissuer-appconfig.png new file mode 100644 index 00000000000..06eea0e6e5a Binary files /dev/null and b/charts/enterprise/clusterissuer/docs/img/clusterissuer-appconfig.png differ diff --git a/charts/enterprise/clusterissuer/docs/img/clusterissuer-ingressconfig.png b/charts/enterprise/clusterissuer/docs/img/clusterissuer-ingressconfig.png new file mode 100644 index 00000000000..7d31bbffd62 Binary files /dev/null and b/charts/enterprise/clusterissuer/docs/img/clusterissuer-ingressconfig.png differ diff --git a/charts/enterprise/clusterissuer/docs/img/scale-network-nameserver.png b/charts/enterprise/clusterissuer/docs/img/scale-network-nameserver.png new file mode 100644 index 00000000000..074a4b17ec8 Binary files /dev/null and b/charts/enterprise/clusterissuer/docs/img/scale-network-nameserver.png differ