diff --git a/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-health.png b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-health.png new file mode 100644 index 00000000..c90c73f8 Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-health.png differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync-error.png b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync-error.png new file mode 100644 index 00000000..e9aa3c9c Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync-error.png differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync.png b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync.png new file mode 100644 index 00000000..9b48de9b Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/argocd-app-out-of-sync.png differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/argocd-console.png b/content/for-administrators/how-to-guides/certificate-management/images/argocd-console.png new file mode 100644 index 00000000..b0679b38 Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/argocd-console.png differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/argocd-hardrefresh.png b/content/for-administrators/how-to-guides/certificate-management/images/argocd-hardrefresh.png new file mode 100644 index 00000000..a644b13a Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/argocd-hardrefresh.png differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/console.png b/content/for-administrators/how-to-guides/certificate-management/images/console.png deleted file mode 100644 index bea746d2..00000000 Binary files a/content/for-administrators/how-to-guides/certificate-management/images/console.png and /dev/null differ diff --git a/content/for-administrators/how-to-guides/certificate-management/images/issuer-status.png b/content/for-administrators/how-to-guides/certificate-management/images/issuer-status.png deleted file mode 100644 index 71b8f57f..00000000 Binary files a/content/for-administrators/how-to-guides/certificate-management/images/issuer-status.png and /dev/null differ diff --git a/content/for-administrators/how-to-guides/certificate-management/tls-certs.md b/content/for-administrators/how-to-guides/certificate-management/tls-certs.md index 5c49d65d..d9469334 100644 --- a/content/for-administrators/how-to-guides/certificate-management/tls-certs.md +++ b/content/for-administrators/how-to-guides/certificate-management/tls-certs.md @@ -1,6 +1,6 @@ -# Configuring Cert Manager Issuer and External DNS +# Configuring Cert Manager ClusterIssuer and External DNS -This document provides a step-by-step guide to configure Cert Manager Issuer and External DNS for different tenants. +This document provides a step-by-step guide to configure Cert Manager ClusterIssuer and External DNS for different tenants. ## Step 1: Setup DNS creds in Vault @@ -14,7 +14,7 @@ Go to `common-shared-secret` path in Vault and create a secret `external-dns-cre | `domain-filter` | optional | This field should contain base domain that becomes base for registering further subdomains. For example: `example.com`. | | `zone-id-filter`| optional | In case of Cloudflare, if you want to give more restrictive access of only few zones to this token, then this field should contain these zone ids. -## Step 2: Create Cert Manager Issuer Resource +## Step 2: Create ExternalSecret Resource Create following resources in your Infra GitOps repository at given path: @@ -27,7 +27,7 @@ Create following resources in your Infra GitOps repository at given path: ### Template -The `Template` resource defines the underlying YAML files to be deployed to tenant namespaces. Use the following template for setting up a TLS certificate: +The `Template` resource defines the underlying YAML resources to be deployed to tenant namespaces. Use the following template for setting up an External Secret: #### Cloudflare @@ -58,22 +58,6 @@ resources: remoteRef: key: certificate-creds property: api-token - - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: - name: letsencrypt-cloudflare - spec: - acme: - email: - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-account-key - solvers: - - dns01: - cloudflare: - apiTokenSecretRef: - name: certificate-creds - key: api-token ``` #### Explanation of Resources @@ -83,16 +67,9 @@ resources: - Retrieves the `api-token` from the secret provider (Vault). - The `api-token` authenticates the DNS provider (e.g., Cloudflare) for certificate validation. -**`Issuer`**: - -- Configures Cert-Manager to generate TLS certificates using [Let’s Encrypt](https://letsencrypt.org/). -- Requires: - - `.spec.acme.email`: Email address for certificate lifecycle updates. - - `.spec.acme.solvers.dns01.cloudflare.apiTokenSecretRef`: Reference to the `ExternalSecret` created earlier. - ### TemplateGroupInstance -The `TemplateGroupInstance` deploys resources by referencing the created templates and specifying target namespaces: +The `TemplateGroupInstance` deploy resources by referencing the created templates and specifying target namespaces: ```yaml apiVersion: tenantoperator.stakater.com/v1alpha1 @@ -113,16 +90,93 @@ spec: - **`.spec.template`**: References the `Template` resource. - **`.spec.selector`**: Specifies namespaces to deploy resources based on label expressions. - - In this example, resources are deployed to tenant with the label `stakater.com/tenant` having values `tenant1` or `tenant2`. Ensure this list includes the names of all tenants where the `Issuer` needs to be available. Whenever you add a new tenant requiring an `Issuer`, update this field to include its name. + - In this example, resources are deployed to tenant with the label `stakater.com/tenant` having values that are defined in `values` field. Ensure this list includes the names of all tenants where this `ExternalSecret` needs to be available. Remember this External secret must be available in all namespace from where you want to expose your application to internet. + +## Step 3: Create ClusterIssuer Resource + +Next step is to deploy ClusterIssuer. For that we need to deploy following resources at given paths in Infra GitOps. + +### ArgoCD application + + `Path: /argocd-apps/` + + ```yaml + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + name: + namespace: rh-openshift-gitops-instance + spec: + destination: + namespace: rh-openshift-gitops-instance + server: https://kubernetes.default.svc + project: + source: + path: / + repoURL: + targetRevision: HEAD + syncPolicy: + automated: + prune: true + selfHeal: true + ``` + +#### Key Fields + +- **`.spec.project`**: Project name that this application should belong to. This can be a name of tenant. +- **`.spec.source.path`**: Path in Infra GitOps repo that this application should sync. This corresponds to the path of folder where `ClusterIssuer` resource would exist. +- **`.spec.source.repoURL`**: This is the url of Infra GitOps repo. + +### Cluster Issuer + + `Path: /` + +#### Cloudflare + + ```yaml + apiVersion: cert-manager.io/v1 + kind: ClusterIssuer + metadata: + name: letsencrypt-cloudflare + spec: + acme: + email: + server: https://acme-v02.api.letsencrypt.org/directory + privateKeySecretRef: + name: letsencrypt-account-key + solvers: + - dns01: + cloudflare: + apiTokenSecretRef: + name: certificate-creds + key: api-token + ``` + +#### Key Fields + +- **`.spec.acme.email`**: Email address for certificate lifecycle updates. +- **`.spec.acme.solvers.dns01.cloudflare.apiTokenSecretRef`**: Reference to the `ExternalSecret` created earlier. + +!!! note + +To deploy cluster-scoped resource (like ClusterIssuer), there is a need of whitelisting deployment of these using [`MTO's Extension resource`](https://docs.stakater.com/mto/main/crds-api-reference/extensions.html). This resource must be created at `/tenant-operator-config/extensions/` path in Infra GitOps. + +Commit, push, and merge these changes to the `main` branch. ArgoCD will deploy the resources to the specified namespaces within few minutes. -Commit, push, and merge these changes to the `main` branch. ArgoCD will deploy the resources to the specified namespaces within a few minutes. +## Step 4: Validation -## Step 3: Validation +1. Login to ArgoCD console. You can find link for ArgoCD from Forecastle. +1. Search for ArgoCD application that you created in step 3: +![ArgoCD Console](images/argocd-console.png) +1. Click on a drop-down next to `Refresh` button and click `Hard-Refresh`. ArgoCD might take some seconds to do a hard refresh. +![ArgoCD HardRefresh option](images/argocd-hardrefresh.png) +1. Check `App Health` and `Sync Status`. Under normal condition the values for these should be `Healthy` and `Synced` respectively. +![ArgoCD Health Status](images/argocd-app-health.png) -1. In the cluster console, switch to `Administrator` view and navigate to `Home > Search`. -1. Select the namespace and search for `Issuer` in the `Resources` dropdown. -1. Inspect the deployed issuer. In the `Condition` section, confirm that the issuer is up-to-date. +!!!note -![OpenShift Console](images/console.png) +If you haven't whitelisted creation of cluster-scoped resource in step 3 then corresponding ArgoCD application will have `OutofSync` as `Sync Status`. +![ArgoCD Out of Sync App](images/argocd-app-out-of-sync.png) -![Issuer Details](images/issuer-status.png) +When you click on `Sync Failed` you get a detailed message saying that current project does not have access to create ClusterIssuer. +![ArgoCD Out of Sync App error](images/argocd-app-out-of-sync-error.png)