diff --git a/content/for-administrators/how-to-guides/certificate-management/images/certificate-status.png b/content/for-administrators/how-to-guides/certificate-management/images/certificate-status.png new file mode 100644 index 00000000..64b2a3d3 Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/certificate-status.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 index bea746d2..1ce6c316 100644 Binary files a/content/for-administrators/how-to-guides/certificate-management/images/console.png and b/content/for-administrators/how-to-guides/certificate-management/images/console.png 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 baf51813..9139f6dd 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 Certificate 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 Certificate and External DNS for different tenants. ## Step 1: Setup DNS creds in Vault @@ -14,9 +14,83 @@ 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 +!!! note -Create following resources in your Infra GitOps repository at given path: +Before proceeding further, confirm with Cluster Administrator that ClusterIssuer is setup in cluster as next steps are dependent on this resource. + +## Step 2: Create Certificate Resource + +Next step is to deploy Certificate. 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: + server: https://kubernetes.default.svc + project: + source: + path: / + repoURL: + targetRevision: HEAD + syncPolicy: + automated: + prune: true + selfHeal: true + ``` + +#### Key Fields + +- **`.spec.destination.namespace`**: Namespace where you want to deploy certificates. Usually it is `system` namespace that is assigned to your tenant. Check with cluster admin for availability of this namespace. +- **`.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 `Certificate` resource would exist. +- **`.spec.source.repoURL`**: This is the URL of Infra GitOps repo. + +### Certificate + + `Path: /` + + ```yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: certificate + spec: + secretName: + duration: 8760h0m0s + renewBefore: 720h0m0s + subject: + null + commonName: null + usages: + null + dnsNames: + - '*.example.com' + issuerRef: + name: + kind: ClusterIssuer + group: cert-manager.io + ``` + +#### Key Fields + +- **`.spec.secretName`**: Name of the secret that cert-manager will create once the certificate request gets approved by Certificate Authority (in present case LetsEncrypt). +- **`.spec.dnsNames`**: List of DNS names that you want this certificate to support. This list can also include [wild card domain names](https://knowledge.digicert.com/general-information/what-is-a-wildcard-certificate) like `*.example.com`. +- **`.spec.issuerRef.name`**: Name of the cluster issuer that you want to use when creating this certificate. You can confirm value for this field with cluster admin. + +Commit, push, and merge these changes to the `main` branch. ArgoCD will deploy the resources to the specified namespaces within few minutes. Confirm that certificate is available in system namespace and is up-to-date before proceeding further. + +## Step 3: Distribute certificate across tenant namespaces + +The next step is to distribute the TLS certificate across namespaces for use. Create following resources in your Infra GitOps repository at given path: ```plaintext /tenant-operator-config/templates/ @@ -27,68 +101,24 @@ 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: - -#### Cloudflare +The `Template` resource defines a way to distribute a secret resource across namespaces. Use the following template for setting up a secret containing TLS certificate: ```yaml apiVersion: tenantoperator.stakater.com/v1alpha1 kind: Template metadata: - name: certificate-creds + name: certificate-template resources: - manifests: - - apiVersion: external-secrets.io/v1beta1 - kind: ExternalSecret - metadata: - name: certificate-creds - spec: - secretStoreRef: - kind: ClusterSecretStore - name: shared-cluster-secret-store - refreshInterval: "1m0s" - target: - name: certificate-creds - creationPolicy: 'Owner' - template: - data: - api-token: "{{ .api-token | b64enc }}" - data: - - secretKey: api-token - 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 + resourceMappings: + secrets: + - name: + namespace: ``` -#### Explanation of Resources - -**`ExternalSecret`**: - -- Retrieves the `api-token` from the secret provider (Vault). -- The `api-token` authenticates the DNS provider (e.g., Cloudflare) for certificate validation. - -**`Issuer`**: +#### Key Fields -- 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. +- **`.spec.secret.name`**: Secret name that certificate will create in system namespace +- **`.spec.secret.namespace`**: Namespace where certificate will create a secret. Usually this is a system namespace in current tenant. ### TemplateGroupInstance @@ -100,7 +130,7 @@ kind: TemplateGroupInstance metadata: name: certificate-creds spec: - template: certificate-creds + template: certificate-template selector: matchExpressions: - key: stakater.com/tenant @@ -113,16 +143,18 @@ 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 `tenant1` or `tenant2`. Ensure this list includes the names of all tenants where the secret needs to be available. Commit, push, and merge these changes to the `main` branch. ArgoCD will deploy the resources to the specified namespaces within a few minutes. -## Step 3: Validation +## Step 4: Validation 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. +1. Select the system namespace and search for `Certificate` in the `Resources` dropdown. +1. Inspect the deployed certificate. In the `Condition` section, confirm that the issuer is up-to-date. + + ![OpenShift Console](images/console.png) -![OpenShift Console](images/console.png) + ![Certificate Details](images/certificate-status.png) -![Issuer Details](images/issuer-status.png) +1. Also confirm the other namespace has correct secret available.