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 new file mode 100644 index 00000000..bea746d2 Binary files /dev/null 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 new file mode 100644 index 00000000..71b8f57f Binary files /dev/null and b/content/for-administrators/how-to-guides/certificate-management/images/issuer-status.png 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 new file mode 100644 index 00000000..5af9557f --- /dev/null +++ b/content/for-administrators/how-to-guides/certificate-management/tls-certs.md @@ -0,0 +1,128 @@ +# Configuring Cert Manager Issuer and External DNS + +This document provides a step-by-step guide to configure Cert Manager Issuer and External DNS for different tenants. + +## Step 1: Setup DNS creds in Vault + +Go to `common-shared-secret` path in Vault and create a secret `external-dns-creds`. This secret mainly have credentials for authenticating with DNS provider and should contain following fields: + +### Cloudflare + +- `api-token (required)`: API token generated from DNS provider being used. In case of Cloudflare, it should have `DNS:Edit` and `Zone:Read` access. +- `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: Navigate to the Target Path + +Navigate to the appropriate path in your Infra GitOps repository. For this example, the path is: + +```plaintext +/tenant-operator-config/templates/ +``` + +## Step 3: Create Required Resources + +In this directory, create the following resources: + +- [`Template`](https://docs.stakater.com/mto/main/crds-api-reference/template.html) +- [`TemplateGroupInstance`](https://docs.stakater.com/mto/main/crds-api-reference/template-group-instance.html) + +### Template + +The `Template` resource defines the underlying YAML files to be deployed to tenant namespaces. Below is an example template for setting up a TLS certificate: + +#### Cloudflare + +```yaml +apiVersion: tenantoperator.stakater.com/v1alpha1 +kind: Template +metadata: + name: certificate-creds +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 +``` + +#### Explanation of Resources + +1. **`ExternalSecret`**: + - Retrieves the `api-token` from the secret provider (Vault). + - The `api-token` authenticates the DNS provider (e.g., Cloudflare) for certificate validation. + +1. **`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. Example: + +```yaml +apiVersion: tenantoperator.stakater.com/v1alpha1 +kind: TemplateGroupInstance +metadata: + name: certificate-creds +spec: + template: certificate-creds + selector: + matchExpressions: + - key: stakater.com/kind + operator: In + values: [sandbox, dev] + sync: true +``` + +#### Key Fields + +- **`.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 namespaces with the label `stakater.com/kind` having values `sandbox` or `dev`. + +Commit, push, and merge these changes to the `main` branch. ArgoCD will deploy the resources to the specified namespaces within a few minutes. + +### Verify Deployment + +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. + +![OpenShift Console](images/console.png) + +![Issuer Details](images/issuer-status.png) diff --git a/content/for-developers/how-to-guides/expose-applications-to-internet/expose-applications-to-internet.md b/content/for-developers/how-to-guides/expose-applications-to-internet/expose-applications-to-internet.md new file mode 100644 index 00000000..184da311 --- /dev/null +++ b/content/for-developers/how-to-guides/expose-applications-to-internet/expose-applications-to-internet.md @@ -0,0 +1,98 @@ +# Exposing Your Application to Internet over HTTPS and custom hostname + +This guide provides a step-by-step process to configure an OpenShift `Route` resource to expose your application to the internet. + +## Prerequisites + +Before proceeding, ensure the following prerequisites are met: + +- **Cert Manager Issuer**: Verify with your cluster administrator that cert manager `Issuer` is properly configured. +- **External DNS**: Confirm that External DNS is set up and operational for managing DNS records. + +## Step 1: Setup Cert Manager Certificate + +A [`Certificate`](https://cert-manager.io/docs/usage/certificate/#creating-certificate-resources) resource is used to automatically manage TLS certificates for your application by integrating with a certificate authority (e.g., Let’s Encrypt). It handles the issuance, renewal, and revocation of certificates, ensuring secure communication over HTTPS. Follow the steps below to configure the Certificate resource + +### Update `values.yaml` + +In your application's Helm chart, add the following snippet in `values.yaml`. + +```yaml +application: + ... + certificate: + enabled: true + secretName: + dnsNames: + - + issuerRef: + name: + kind: Issuer +``` + +#### Important Details + +- **Certificate**: + - Instruct Cert-Manager to generate TLS certificates for specific DNS entries. + - Requires: + - `.certificate.secretName`: This is the name of secret that `Certificate` will create. It will contain TLS credentials that will find its utilization in next steps. + - `.certificate.dnsNames`: DNS name for which this certificate will be valid. It can contain wildcard names like `*.example.com` or specific names like `api.example.com`. + - `.certificate.issuerRef.name`: Name of the issuer that this certificate will reference. We have created this issuer in previous steps. + +## Step 2: Deploy the Route + +A [`Route`](https://docs.openshift.com/container-platform/4.17/networking/routes/route-configuration.html) resource is used to expose your application to the internet using a specific DNS name. Follow the steps below to configure the Route. + +### Update `values.yaml` + +Update the `values.yaml` file in your application’s Helm chart with the following configuration: + +```yaml +application: + ... + route: + enabled: true + annotations: + cert-utils-operator.redhat-cop.io/certs-from-secret: + external-dns.alpha.kubernetes.io/hostname: + cert-utils-operator.redhat-cop.io/inject-CA: "false" + host: + path: +``` + +#### Important Details + +- **Annotations**: + - `cert-utils-operator.redhat-cop.io/certs-from-secret`: Specifies the name of the secret that stores the TLS certificate created by the Certificate resource. + - `external-dns.alpha.kubernetes.io/hostname`: Registers the DNS record with the configured provider (e.g., Cloudflare). + - `cert-utils-operator.redhat-cop.io/inject-CA`: Indicates whether to inject the Certificate Authority (CA) into the Route. Set to "false" if not required. + +- **Additional Configuration**: + - `route.host`: Specifies the host name that you want to use for this route. This value must match the `external-dns.alpha.kubernetes.io/hostname` annotation. + - `route.path`: Specifies the URL path where your application will be exposed (e.g., `/api`). + +### Verify Deployment + +After updating the `values.yaml` file and applying the Helm chart, verify the deployment: + +#### Certificate + +1. In the cluster console, switch to `Administrator` view and navigate to `Home > Search`. +1. Select the namespace and search for `Certificate` in the `Resources` dropdown. +1. Inspect the deployed certificate. In the `Condition` section, confirm that the certificate is up-to-date. + +![OpenShift Console](images/console.png) + +![Certificate Details](images/certificate-details.png) + +!!! note + If the certificate status is not updated, wait a few minutes as Cert-Manager may take time to generate the certificate. + +#### Route + +1. Navigate to the OpenShift cluster console. +1. Go to Networking > Routes and locate the Route resource for your application. +1. Confirm that: + - The Route resource is listed. + - Its status is Accepted. + - The DNS name and TLS configuration are correct. diff --git a/content/for-developers/how-to-guides/expose-applications-to-internet/images/certificate-details.png b/content/for-developers/how-to-guides/expose-applications-to-internet/images/certificate-details.png new file mode 100644 index 00000000..d996d0d6 Binary files /dev/null and b/content/for-developers/how-to-guides/expose-applications-to-internet/images/certificate-details.png differ diff --git a/content/for-developers/how-to-guides/expose-applications-to-internet/images/console.png b/content/for-developers/how-to-guides/expose-applications-to-internet/images/console.png new file mode 100644 index 00000000..d1320e4c Binary files /dev/null and b/content/for-developers/how-to-guides/expose-applications-to-internet/images/console.png differ diff --git a/theme_override/mkdocs.yml b/theme_override/mkdocs.yml index 0052b87e..ab724619 100644 --- a/theme_override/mkdocs.yml +++ b/theme_override/mkdocs.yml @@ -54,6 +54,10 @@ nav: - For Administrators: - for-administrators/overview.md - for-administrators/user-stories.md + - How-to guides: + - for-administrators/how-to-guides/certificate-management/tls-certs.md + - Explanation: + - for-administrators/explanation/number-of-clusters.md - Plan your environment: - for-administrators/plan-your-environment/sizing.md - Secure your cluster: @@ -75,8 +79,6 @@ nav: - for-administrators/cluster-lifecycle/hibernate-your-cluster.md - Help: - for-administrators/help/faq.md - - Explanation: - - for-administrators/explanation/number-of-clusters.md - For DevOps Engineers: - for-devops-engineers/overview.md - Explanation: @@ -166,6 +168,7 @@ nav: - for-developers/how-to-guides/deploy-app-with-argocd-and-helm/deploy-app-with-argocd-and-helm.md - for-developers/how-to-guides/expose-spring-boot-metrics/expose-spring-boot-metrics.md - for-developers/how-to-guides/package-and-push-your-chart/package-and-push-your-chart.md + - for-developers/how-to-guides/expose-applications-to-internet/expose-applications-to-internet.md - For CISOs & DPOs: - for-cisos-dpos/overview.md - General Frameworks: