Add Let's Encrypt support (#312)

AMRC-FactoryPlus · Jul 15, 2024 · b575c3f · b575c3f
1 parent 22a62b8
commit b575c3f
Show file tree

Hide file tree

Showing 5 changed files with 81 additions and 9 deletions.
diff --git a/deploy/Chart.lock b/deploy/Chart.lock
@@ -14,5 +14,8 @@ dependencies:
 - name: influxdb2
   repository: https://helm.influxdata.com/
   version: 2.1.1
-digest: sha256:ada9c6053be1c658b5fb7b7e925aecfbd7e4b1bd78b709896cd26ffb4c015520
-generated: "2024-03-27T09:43:35.2275948Z"
+- name: cert-manager
+  repository: https://charts.jetstack.io
+  version: v1.14.4
+digest: sha256:5e6b7a20a96c54dba427cd3913ff2f8246e6a1125b82e2cafd6eb710b722d77d
+generated: "2024-04-19T12:00:46.600094+01:00"
diff --git a/deploy/Chart.yaml b/deploy/Chart.yaml
@@ -38,3 +38,7 @@ dependencies:
     version: 2.1.1
     repository: https://helm.influxdata.com/
     condition: influxdb2.enabled
+  - name: cert-manager
+    repository: https://charts.jetstack.io
+    version: v1.14.4
+    condition: acs.letsEncrypt.enabled
diff --git a/deploy/templates/lets-encrypt/tls.yaml b/deploy/templates/lets-encrypt/tls.yaml
@@ -0,0 +1,43 @@
+{{ if .Values.acs.letsEncrypt.enabled -}}
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: letsencrypt
+spec:
+  acme:
+    server: {{ ternary "https://acme-staging-v02.api.letsencrypt.org/directory" "https://acme-v02.api.letsencrypt.org/directory" .Values.acs.letsEncrypt.staging }}
+    email: {{.Values.acs.letsEncrypt.email}}
+    privateKeySecretRef:
+      name: letsencrypt
+    solvers:
+      - http01:
+          ingress:
+            class: traefik
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: {{ .Values.acs.tlsSecretName }}
+  namespace: {{ .Release.Namespace }}
+spec:
+  secretName: {{ .Values.acs.tlsSecretName }}
+  privateKey:
+    rotationPolicy: Always
+  dnsNames:
+    - {{ .Values.acs.baseUrl}}
+    - visualiser.{{ .Values.acs.baseUrl}}
+    - auth.{{ .Values.acs.baseUrl}}
+    - admin.{{ .Values.acs.baseUrl}}
+    - clusters.{{ .Values.acs.baseUrl}}
+    - cmdesc.{{ .Values.acs.baseUrl}}
+    - configdb.{{ .Values.acs.baseUrl}}
+    - data.{{ .Values.acs.baseUrl}}
+    - directory.{{ .Values.acs.baseUrl}}
+    - git.{{ .Values.acs.baseUrl}}
+    - grafana.{{ .Values.acs.baseUrl}}
+    - manager.{{ .Values.acs.baseUrl}}
+    - mqtt.{{ .Values.acs.baseUrl}}
+  issuerRef:
+    name: letsencrypt
+    kind: Issuer
+{{- end }}
diff --git a/deploy/values.yaml b/deploy/values.yaml
@@ -5,6 +5,14 @@ acs:
   baseUrl: factoryplus.myorganisation.com
   # -- Whether or not services should be served over HTTPS
   secure: true
+  letsEncrypt:
+    # -- Whether or not to use Let's Encrypt to automatically generate
+    # certificates for the services
+    enabled: true
+    # -- The email address to use for Let's Encrypt
+    email: ''
+    # -- Whether or not to use the staging environment for Let's Encrypt
+    staging: false
   # -- The name of the secret holding the wildcard certificate for the
   # above domain. It will be used for every service unless that service
   # specifies its own tlsSecretName.
@@ -297,8 +305,6 @@ kubegres:
 traefik:
   enabled: true
   ports:
-    web:
-      expose: false
     mqtt:
       port: 1883
       expose: false
@@ -412,3 +418,6 @@ influxdb2:
         influx v1 dbrp create --bucket-id ${DOCKER_INFLUXDB_INIT_BUCKET_ID} --db default --rp default --default --org ${DOCKER_INFLUXDB_INIT_ORG}
   pdb:
     create: false
+
+cert-manager:
+  fullnameOverride: "cert-manager"
diff --git a/docs/installation.md b/docs/installation.md
@@ -17,17 +17,28 @@ Kubectl is a command-line tool for controlling Kubernetes clusters. It must be i
 
 ### Configure DNS
 
-This Chart creates a load balancer on your Kubernetes cluster that exposes all services at various subdomains. Please ensure that you have a wildcard DNS entry configured to direct all `*.<baseURL>` requests to your Kubernetes cluster.
+This Chart creates a load balancer on your Kubernetes cluster that exposes all services at various subdomains. Please ensure that you have both a wildcard DNS `A Record` configured to direct all `*.<baseURL>` requests and a root `A Record` to direct all `<baseURL>` requests to your load balancer IP.
 
 ### Configure TLS
 
-#### Production deployment
+If `acs.letsEncrypt.enabled` is true (default) then ACS will utilise `cert-manager` and Let's Encrypt to automatically issue and renew TLS certificates for your ACS installation. Please note that the cluster's DNS will need to be resolvable via the internet for this to work. If you intend on utilising Let's Encrypt to handle certificates for you then you need to ensure that the cert-manager CRDs are installed onto your cluster.
 
-If `acs.secure` is set to `true` in your deployment (enabled by default) then you must also create a wildcard TLS secret on the cluster in the`default` namespace with the same name as the value specified in `acs.tlsSecretName` _before_ installing ACS. The TLS certificate must be valid for all domains covered by the wildcard DNS entry.
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.crds.yaml
+```
+
+> Please ensure that you set a valid email address in `acs.letsEncrypt.email` before installing.
+
+#### Bringing your own certificate
+If you'd prefer to use your own certificate, create a wildcard TLS secret in your namespace with the name of `acs.tlsSecretName` (`factoryplus-tls` by default) and set the `acs.letsEncrypt.enabled` value to `false`.
 
 #### Development (insecure) deployment
 
-To deploy a development/testing instance without TLS set `acs.secure` to `false` and ensure that you update the `traefik.ports.web.expose` and `traefik.ports.mqtt.expose` values to `true` in your `values.yaml` file.
+To deploy a development/testing instance without TLS set:
+
+- `acs.secure` to `false`
+- `acs.letsEncrypt.enabled` to `false`
+- `traefik.ports.mqtt.expose` to `true`
 
 ## Install ACS
 
@@ -46,6 +57,8 @@ Next, create a `values.yaml` file in a sensible location on your local machine.
 acs:
   baseUrl: factoryplus.myorganisation.com # Set this to the domain that ACS will be served from. This should be the same as the wildcard DNS entry you created earlier.
   organisation: MYORGANISATION # Set this to the name of your organisation. It will be used across the deployment for branding and naming.
+  letsEncrypt:
+    email: factoryplus@myorganisation.co.uk
 identity:
   realm: FACTORYPLUS.MYORGANISATION.COM # Set the identity realm for the deployment. This is used to namespace the identity server and should be unique to your deployment. It is recommended that you use the baseUrl in capitals for this value.
 ```
@@ -61,7 +74,7 @@ kubectl create namespace factory-plus
 Finally, install ACS by running the following command.
 
 ```bash
-helm install acs amrc-connectivity-stack/amrc-connectivity-stack --version ^3.0.0 -f values.yaml --namespace factory-plus
+helm install acs amrc-connectivity-stack/amrc-connectivity-stack --version ^3.0.0 -f values.yaml --namespace factory-plus --wait --timeout 30m
 ```
 
 If all went to plan you should now have a fully functioning ACS deployment beginning to deploy to your Kubernetes cluster. Note that it can take a few minutes to have all services operational as the containers are pulled and started.