ENDOC-302-add-tls-with-cert-mgr

vuepress/docs/.vuepress/next.js

@@ -458,10 +458,6 @@ module.exports = {
                         title: 'Backing Up and Restoring Keycloak',
                         path: path  + 'devops/backing-restoring-keycloak.md',
                     },
-                    {
-                        title: 'Manage NGINX',
-                        path: path  + 'devops/manage-nginx.md',
-                    },
                     {
                         title: 'Plugin Configuration',
                         path: path  + 'devops/plugin-configuration.md',
@@ -470,6 +466,14 @@ module.exports = {
                         title: 'Plugin Environment Variables',
                         path: path  + 'devops/plugin-environment-variables.md',
                     },
+                    {
+                        title: 'Manage NGINX',
+                        path: path  + 'devops/manage-nginx.md',
+                    },
+                    {
+                        title: 'Enable TLS',
+                        path: path  + 'devops/tls-with-cert-mgr.md',
+                    },
                     {
                         title: 'Configure the Entando App Context',
                         path: path  + 'devops/entando-de-app.md',

vuepress/docs/.vuepress/v72.js

@@ -458,10 +458,6 @@ module.exports = {
                         title: 'Backing Up and Restoring Keycloak',
                         path: path  + 'devops/backing-restoring-keycloak.md',
                     },
-                    {
-                        title: 'Manage NGINX',
-                        path: path  + 'devops/manage-nginx.md',
-                    },
                     {
                         title: 'Plugin Configuration',
                         path: path  + 'devops/plugin-configuration.md',
@@ -470,6 +466,14 @@ module.exports = {
                         title: 'Plugin Environment Variables',
                         path: path  + 'devops/plugin-environment-variables.md',
                     },
+                    {
+                        title: 'Manage NGINX',
+                        path: path  + 'devops/manage-nginx.md',
+                    },
+                    {
+                        title: 'Enable TLS',
+                        path: path  + 'devops/tls-with-cert-mgr.md',
+                    },
                     {
                         title: 'Configure the Entando App Context',
                         path: path  + 'devops/entando-de-app.md',

vuepress/docs/next/tutorials/consume/high-availability.md

@@ -32,8 +32,8 @@ kubectl scale deployment quickstart-deployment -n entando --replicas=2
 ```
 
 3. To view the pods in your deployment:
-```
-`kubectl get pods -n YOUR-NAMESPACE`
+``` bash
+kubectl get pods -n YOUR-NAMESPACE
 ```
 4. You should have two `quickstart-deployment` pods in your namespace.
 

vuepress/docs/next/tutorials/devops/external-db.md

@@ -1,4 +1,4 @@
-# Tutorial: Connecting to an External Database
+# Connecting to an External Database
 
 ## Overview
 

vuepress/docs/next/tutorials/devops/manage-nginx.md

@@ -63,7 +63,7 @@ Hostname: hello-app
 ```
 Note that you will need the EXTERNAL-IP address of your ingress controller to configure the application.
 
-7. Verify that you configured the ingress class in the Operator `ConfigMap` so Entando knows which ingress controller should be used:
+7. Verify that you configured the `ingress.class` in the Operator `ConfigMap` so Entando knows which ingress controller should be used:
 
 `entando.ingress.class: "nginx"`
 
@@ -74,7 +74,7 @@ kubectl delete deploy/hello-server service/hello-server ing/ingress-resource
 
 ## Customize the NGINX Configuration
 
-There are situations where the default NGINX ingress configuration isn't optimized for Entando, e.g. JWT tokens can be too large or `proxy-buffer-size` can be too small. A `502 Bad Gateway` error may indicate that the config needs to be modified.
+There are situations where the default NGINX ingress configuration isn't optimized for Entando, e.g., JWT tokens can be too large or `proxy-buffer-size` can be too small. A `502 Bad Gateway` error may indicate that the config needs to be modified.
 
 The NGINX controller can be configured for the entire cluster by editing the default NGINX `ConfigMap`, called `ingress-nginx-controller` in the `ingress-nginx` namespace. Add the following to the data parameter:
 
@@ -101,93 +101,4 @@ nginx.ingress.kubernetes.io/affinity: cookie
 nginx.ingress.kubernetes.io/affinity-mode: persistent
 nginx.ingress.kubernetes.io/session-cookie-name: ROUTE
 nginx.ingress.kubernetes.io/session-cookie-secure: "true"
-```
-## Add the `cert-manager` for TLS Support
-
-Follow the instructions below to install and configure `cert-manager` in Kubernetes environments.
-​
-### Installation
-​
-Create a namespace dedicated to `cert-manager`: 
-
-```
-kubectl create ns cert-manager
-```
-​
-Complete the installation:
-
-```yaml
-kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.0/cert-manager.yaml
-```
-### Configuration
-​
-To enable `cert-manager` to generate certificates, add these annotations to the ingress:
-​
-- `cert-manager.io/issuer: "[name of the issuer]"` for namespace-based issuers
-- `cert-manager.io/cluster-issuer: "[name of cluster issuer]"` for cluster-wide issuers
-
-and modify `spec`:
-
-```yaml
-spec:
-  tls:
-  - hosts:
-    - example.example.com
-    secretName: quickstart-example-tls # this Secret will be autogenereted by cert-manager.
-```
-#### Namespace Level Issuer
-​
-Use the following configuration when deploying an issuer per namespace. This is useful for higher levels of customization.
-​
-```yaml
-apiVersion: cert-manager.io/v1
-kind: Issuer
-metadata:
-  name: letsencrypt-prod
-spec:
-  acme:
-    # The ACME server URL
-    server: https://acme-v02.api.letsencrypt.org/directory
-    preferredChain: "ISRG Root X1"
-    # Email address used for ACME registration
-    email: <your email>
-    # Name of a secret used to store the ACME account privare key
-    privateKeySecretRef:
-      name: letsencrypt-prod
-    # Enable the http-01 challenge provider
-    solvers:
-    - http01:
-        ingress:
-          class: nginx
-​
-```
-#### Cluster Level Issuer
-
-Use the following configuration when deploying an issuer per cluster:
-
-```yaml
-apiVersion: cert-manager.io/v1
-kind: ClusterIssuer
-metadata:
-  name: letsencrypt-prod-cluster
-  namespace: cert-manager
-spec:
-  acme:
-    # The ACME server URL
-    server: https://acme-v02.api.letsencrypt.org/directory
-    preferredChain: "ISRG Root X1"
-    # Email address used for ACME registration
-    email: <your email>
-    # Name of a secret used to store the ACME account privare key
-    privateKeySecretRef:
-      name: letsencrypt-cluster-prod
-    # Enable the http-01 challenge provider
-    solvers:
-    - http01:
-        ingress:
-          class: nginx
-​
-```
-### `cert-manager` References
-- [Installation](https://cert-manager.io/docs/installation/)
-- [Supported releases](https://cert-manager.io/docs/installation/supported-releases/)
+```

vuepress/docs/next/tutorials/devops/tls-with-cert-mgr.md

@@ -0,0 +1,134 @@
+---
+sidebarDepth: 2
+---
+# Manage TLS Certificates using cert-manager
+Management of TLS certificates in an Entando instance can be easily managed using the powerful certificate controller [cert-manager](https://cert-manager.io/). This tutorial shows the configuration steps necessary for this setup.
+
+## Prerequisites
+- An existing deployment of an Entando App
+- Use of the [NGINX ingress controller](https://docs.nginx.com/nginx-ingress-controller/). See the  [cert-manager documentation](https://cert-manager.io/docs/installation/) for other install options.
+
+## Install cert-manager
+1. Create a namespace for `cert-manager`:
+``` bash
+kubectl create namespace cert-manager
+```
+
+2. Follow the install instructions to create the `cert-manager` resources in this namespace. The install can be as simple as the following command if the default configuration is acceptable: 
+``` bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml -n cert-manager
+```
+
+## Prepare an Issuer
+An [Issuer](https://cert-manager.io/docs/concepts/issuer) defines **how** `cert-manager` will request TLS certificates. Issuers can be either specific to a single namespace or provided as a cluster-wide `ClusterIssuer`. The following steps are for a cluster-wide configuration using the [Let's Encrypt](https://letsencrypt.org/) automated certificate authority.
+
+1. Create a file `letsencrypt-prod-cluster.yaml` with the following content:
+``` yaml
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod-cluster
+spec:
+  acme:
+    # The ACME server URL
+    server: https://acme-v02.api.letsencrypt.org/directory
+    # Email address used for ACME registration
+    email: YOUR-EMAIL-ADDRESS
+    # Name of a secret used to store the ACME account private key
+    privateKeySecretRef:
+      name: letsencrypt-prod
+    # Enable the HTTP-01 challenge provider
+    solvers:
+      - http01:
+          ingress:
+            ingressClassName: nginx
+```
+> ACME stands for Automatic Certificate Management Environment which is the protocol used by `Let's Encrypt` and `cert-manager`.
+
+2. Replace `YOUR-EMAIL-ADDRESS` with your own email. This will be used by `Let's Encrypt` for certification expiration and update notifications.
+
+3. (Optional) Change the issuer name from `letsencrypt-prod-cluster` to your preferred name. The name is needed when creating the `Certificate` resource below.
+
+4. Create the `ClusterIssuer`:
+``` bash
+kubectl apply -f letsencrypt-prod-cluster.yaml 
+```
+> If a namespace-level Issuer is used then include the namespace parameter in the command. The preceding resource definition and following command should also be changed from `clusterissuer` to `issuer`.
+
+5. Confirm the status of the `ClusterIssuer`:
+``` bash
+kubectl describe clusterissuer letsencrypt-prod-cluster
+```
+If the account and configuration is correct, you should see this message in the Status section:
+```
+The ACME account was registered with the ACME server
+```
+
+## Enable cert-manager to generate certificates
+The simplest way to have `cert-manager` generate certificates is by creating a `Certificate` resource.
+
+1. Create `certificate.yaml` with the following content:
+``` yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: entando-tls-secret
+spec:
+  secretName: entando-tls-secret
+  issuerRef:
+    group: cert-manager.io
+    kind: ClusterIssuer
+    name: letsencrypt-prod-cluster
+  dnsNames:
+  - YOUR-HOSTNAME
+  usages:
+  - digital signature
+  - key encipherment
+```
+
+2. Set `YOUR-HOSTNAME` to match your environment. Update `issuerRef:name` to use the issuer name from above.
+3. Create the certificate:
+``` bash
+kubectl apply -f certificate.yaml -n YOUR-NAMESPACE
+```
+> It may take a few minutes for `cert-manager` to generate the certificate and configure the new secret.
+
+4.  Confirm the secret was created:
+``` bash
+kubectl describe secret/entando-tls-secret -n YOUR-NAMESPACE
+```
+
+## Activate TLS in the Entando App
+Configure the Entando Application to use TLS now that the new secret is available.
+
+1. Edit the `entando-operator-config` ConfigMap and set the following property:
+``` yaml
+data:
+  entando.tls.secret.name: entando-tls-secret
+```
+> *Tip:* For a new Entando installation, the following steps (steps 2+) can be skipped. The operator will apply the TLS changes as part of the regular install process.
+
+2. Two environment variables need to be updated when switching from a non-TLS configuration to a TLS configuration. Edit the `EntandoApp` custom resource and add the following environment variables with the correct values:
+``` yaml
+  environmentVariables: 
+    - name: KEYCLOAK_AUTH_URL
+      value: https://YOUR-HOST-NAME/auth
+    - name: SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI
+      value: https://YOUR-HOST-NAME/auth/realms/entando
+```
+
+3. Also add the following annotation:
+``` yaml 
+metadata:
+   annotations: 
+      entando.org/processing-instruction: force
+```   
+
+5. Save the changes to the `EntandoApp` resource. The `EntandoApp` phase should change to `requested` then `started` as the Entando Operator proceeds to update the application.
+
+6. Confirm the application is using TLS once the EntandoApp is updated and the deployments have restarted.
+
+
+## `cert-manager` References
+- [Installation](https://cert-manager.io/docs/installation/)
+- [Supported releases](https://cert-manager.io/docs/installation/supported-releases/)

vuepress/docs/v7.2/tutorials/consume/high-availability.md

@@ -32,8 +32,8 @@ kubectl scale deployment quickstart-deployment -n entando --replicas=2
 ```
 
 3. To view the pods in your deployment:
-```
-`kubectl get pods -n YOUR-NAMESPACE`
+``` bash
+kubectl get pods -n YOUR-NAMESPACE
 ```
 4. You should have two `quickstart-deployment` pods in your namespace.
 

vuepress/docs/v7.2/tutorials/devops/build-core-image.md

@@ -43,4 +43,3 @@ additional commands and configuration can be found here:
 5.  Push the Image to your Repository
 
         docker push <YOUR-USER>/<YOUR-REPO-NAME>:<YOUR-VERSION>
-

vuepress/docs/v7.2/tutorials/devops/external-db.md

@@ -1,4 +1,4 @@
-# Tutorial: Connecting to an External Database
+# Connecting to an External Database
 
 ## Overview