Skip to main content

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: # Selecting `Certmanager Let's Encrypt`
                certmanager:
                  issuer: letsencrypt
                mode: certmanager
          secretName: element-web
        integrator:
          k8s:
            ingress:
              tls: # Selecting `Certificate File`
                certificate:
                  certFileSecretKey: integratorCertificate
                  privateKeySecretKey: integratorPrivateKey
                mode: certfile
          secretName: integrator
        synapse:
          k8s:
            ingress:
              tls: # Selecting `Existing TLS Certificates in the Cluster`
                mode: existing
                secretName: example
          secretName: synapse
        synapseAdmin:
          k8s:
            ingress:
              tls: # Selecting `Externally Managed`
                mode: external
          secretName: synapse-admin
        wellKnownDelegation:
          k8s:
            ingress:
              tls:
                mode: external
          secretName: well-known-delegation
    
  • 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: 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 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

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

Certmanager Let's Encrypt

Config Example
spec:
  components:
    componentName: # `elementWeb`, `integrator`, `synapse`, `synapseAdmin`, `wellKnownDelegation`
      k8s:
        ingress:
          tls:
            certmanager:
              issuer: letsencrypt
            mode: certmanager
      secretName: component # Not used with 'Certmanager 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: # `elementWeb`, `integrator`, `synapse`, `synapseAdmin`, `wellKnownDelegation`
      k8s:
        ingress:
          tls:
            mode: certfile
            certificate:
              certFileSecretKey: componentCertificate
              privateKeySecretKey: componentPrivateKey
      secretName: component
  • 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 liklihood of certificate-based issues post deployment.

Existing TLS Certificates in the Cluster

Config Example
spec:
  components:
    componentName: # `elementWeb`, `integrator`, `synapse`, `synapseAdmin`, `wellKnownDelegation`
      k8s:
        ingress:
          tls:
            mode: existing
            secretName: example
      secretName: component # 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: # `elementWeb`, `integrator`, `synapse`, `synapseAdmin`, `wellKnownDelegation`
      k8s:
        ingress:
          tls:
            mode: external
      secretName: component # 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.