Merge pull request #362 from stakater/add-docs-for-tenant-certs

Added docs for setting up TLS certificates

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
+<cluster>/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: <domain-owning-authority's 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)

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: <secret name where tls creds will be stored>
+    dnsNames:
+      - <DNS for which we need to generate certificate for example:example.com>
+    issuerRef:
+      name: <cert manager's Issuer name. You can ask cluster admin for this>
+      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: <name-of-certificate-secret>
+      external-dns.alpha.kubernetes.io/hostname: <desired-dns-name>
+      cert-utils-operator.redhat-cop.io/inject-CA: "false"
+    host: <desired-dns-name>
+    path: <desired-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.

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: