Certificates Section

The third section of the ESS installer GUI is the Domains section, here you will configure the certificates to use for each previously specified domain name.

Certificate details configured via the UI in this section will be saved to your deployment.yml under each of the components' k8s: ingress: configuration with the cert contents (if manually uploaded) being saved to a secrets.yml in Base64.

This section covers all certificates to be used by the main components deployed by the installer, additional certificates may be required when enabling specific integrations - you will specify integration specific certificates on each respective integrations' page.

Config Example

deployment.yml

spec:
  components:
    elementWeb:
      k8s:
        ingress:
          tls: # (1)!
            certmanager:
              issuer: letsencrypt
            mode: certmanager
      secretName: element-web
    integrator:
      k8s:
        ingress:
          tls: # (2)!
            certificate:
              certFileSecretKey: integratorCertificate
              privateKeySecretKey: integratorPrivateKey
            mode: certfile
      secretName: integrator
    matrixAuthenticationService:
      k8s:
        ingress:
          fqdn: mas.example.com
          tls:
            certmanager:
              issuer: letsencrypt
            mode: certmanager
      secretName: matrix-authentication-service
    synapse:
      k8s:
        ingress:
          tls: # (3)!
            mode: existing
            secretName: example
      secretName: synapse
    synapseAdmin:
      k8s:
        ingress:
          tls: # (4)!
            mode: external
      secretName: synapse-admin
    wellKnownDelegation:
      k8s:
        ingress:
          tls:
            mode: external
      secretName: well-known-delegation

Example shows config when selecting Certmanager Let's Encrypt
Example shows config when selecting Certificate File
Example shows config when selecting Existing TLS Certificates in the Cluster
Example shows config when selecting Externally Managed

secrets.yml

apiVersion: v1
kind: Secret
metadata:
  name: element-web
  namespace: element-onprem
data:
  elementWebCertificate: >-
    exampleBase64EncodedString
  elementWebPrivateKey: >-
    exampleBase64EncodedString
---
apiVersion: v1
kind: Secret
metadata:
  name: integrator
  namespace: element-onprem
data:
  certificate: >-
    exampleBase64EncodedString
  privateKey: >-
    exampleBase64EncodedString
---
apiVersion: v1
kind: Secret
metadata:
  name: matrix-authentication-service
  namespace: element-onprem
data:
  certificate: >-
    exampleBase64EncodedString
  privateKey: >-
    exampleBase64EncodedString
---
apiVersion: v1
kind: Secret
metadata:
  name: synapse
  namespace: element-onprem
data:
  synapseCertificate: >-
    exampleBase64EncodedString
  synapsePrivateKey: >-
    exampleBase64EncodedString
---
apiVersion: v1
kind: Secret
metadata:
  name: synapse-admin
  namespace: element-onprem
data:
  synapseAdminUICertificate: >-
    exampleBase64EncodedString
  synapseAdminUIPrivateKey: >-
    exampleBase64EncodedString
---
apiVersion: v1
kind: Secret
metadata:
  name: well-known-delegation
  namespace: element-onprem
data:
  wellKnownDelegationCertificate: >-
    exampleBase64EncodedString
  wellKnownDelegationPrivateKey: >-
    exampleBase64EncodedString

You will need to configure certificates for the following components:

Well-Known Delegation
- Well-Known files are served on the base domain, i.e. https://example.com/.well-known/matrix/client and https://example.com/.well-known/matrix/server.
Synapse
- Please note, if you opt to turn on DNS SRV (via the Cluster Section), the Synapse certificate MUST include the base domain as an additional name.
Element Web
Synapse Admin
Integrator
Matrix Authentication Service

For each component, you will be presented with 4 options on how to configure the certificate.

cert-manager Let's Encrypt

Config Example

spec:
  components:
    componentName: # (1)!
      k8s:
        ingress:
          tls:
            certmanager:
              issuer: letsencrypt
            mode: certmanager
      secretName: component # (2)!

For example componentName could be:

elementWeb, integrator, synapse, synapseAdmin, wellKnownDelegation ...
Not used with 'cert-manager Let's Encrypt'

Select this to use Let's Encrypt to generate the certificates used, do not edit the Issuer field as no other options are available at this time.

Certificate File

Config Example

deployment.yml

spec:
  components:
    componentName: # (1)!
      k8s:
        ingress:
          tls:
            mode: certfile
            certificate:
              certFileSecretKey: componentCertificate
              privateKeySecretKey: componentPrivateKey
      secretName: component

For example componentName could be:

elementWeb, integrator, synapse, synapseAdmin, wellKnownDelegation ...

secrets.yml

apiVersion: v1
kind: Secret
metadata:
  name: component
  namespace: element-onprem
data:
  componentCertificate: >-
    exampleBase64EncodedString
  componentPrivateKey: >-
    exampleBase64EncodedString
---

Select this option to be able to manually upload the certificates that should be used to serve the specified domain. Make sure you certificate files are in the PEM encoded format and it is strongly advised to include the full certificate chain within the file to reduce likelihood of certificate-based issues post deployment.

Existing TLS Certificates in the Cluster

Config Example

spec:
  components:
    componentName: #  (1)!
      k8s:
        ingress:
          tls:
            mode: existing
            secretName: example
      secretName: component # (2)!

For example componentName could be:

elementWeb, integrator, synapse, synapseAdmin, wellKnownDelegation ...
Not used with 'Existing TLS Certificates in the Cluster'

This option is most applicable to Kubernetes deployments, however can be used with Standalone. Select this option when secrets containing the certificates are already present and managed within the cluster, provide the secret name that contains the TLS certificates for ESS to use them.

Externally Managed

Config Example

spec:
  components:
    componentName: # (1)!
      k8s:
        ingress:
          tls:
            mode: external
      secretName: component # (2)!

For example componentName could be:

elementWeb, integrator, synapse, synapseAdmin, wellKnownDelegation ...
Not used with 'Externally Managed'

Select this option is certificates are handled in front of the cluster, TLS will not be configured on the ingress for each component.

Well-Known Delegation

If you already host a site on your base domain, i.e. example.com, then you should either ensure your web server defers to the Well-Known Delegation component to serve the .well-known files or you should set Well-Known Delegation to Externally Managed and manually serve those files.

This is because Matrix clients and servers need to be able to request https://example.com/.well-known/matrix/client and https://example.com/.well-known/matrix/server respectively to work properly.

The web server hosting the base domain should either forward requests for /.well-known/matrix/client and /.well-known/matrix/server to the Well-Known Delegation component for it to serve, or a copy of the .well-known files will need to be added directly on the example.com web server.

If you don't already host a base domain example.com, then the Well-Known Delegation component hosts the .well-known files and serves the base domain i.e. example.com

Getting the contents of the `.well-known` files

Run kubectl get cm/first-element-deployment-well-known -n element-onprem -o yaml on your ESS host, it will output something similar to the below:

Config Example

apiVersion: v1
data:
  client: |-
    {
        "m.homeserver": {
            "base_url": "https://synapse.example.com"
        }
    }
   server: |-
    {
        "m.server": "synapse.example.com:443"
    }
 kind: ConfigMap
metadata:
  creationTimestamp: "2024-06-13T09:32:52Z"
  labels:
    app.kubernetes.io/component: matrix-delegation
    app.kubernetes.io/instance: first-element-deployment-well-known
    app.kubernetes.io/managed-by: element-operator
    app.kubernetes.io/name: well-known
    app.kubernetes.io/part-of: matrix-stack
    app.kubernetes.io/version: 1.24-alpine-slim
    k8s.element.io/crdhash: 9091d9610bf403eada3eb086ed2a64ab70cc90a8
  name: first-element-deployment-well-known
  namespace: element-onprem
  ownerReferences:
  - apiVersion: matrix.element.io/v1alpha1
    kind: WellKnownDelegation
    name: first-element-deployment
    uid: 24659493-cda0-40f0-b4db-bae7e15d8f3f
  resourceVersion: "3629"
  uid: 7b0082a9-6773-4a28-a2a9-588a4a7f7602

Copy the contents of the two supplied files (client and server) from the output into their own files:

Filename: client

{
  "m.homeserver": {
    "base_url": "https://synapse.example.com"
  }
}

Filename: server

{
  "m.server": "synapse.example.com:443"
}

Configure your webserver such that each file is served correctly at, i.e for a base domain of example.com:
https://example.com/.well-known/matrix/client
https://example.com/.well-known/matrix/server

Certificates Section

cert-manager Let's Encrypt

Certificate File

Existing TLS Certificates in the Cluster

Externally Managed

Well-Known Delegation

Getting the contents of the .well-known files

Getting the contents of the `.well-known` files