Element Server Suite (ESS) Helm Charts

The syn2mas feature in the Helm chart facilitates a controlled migration from Synapse's legacy authentication to the Matrix Authentication Service (MAS). This is a one-way process; once the system reaches the delegated_auth state, you cannot roll back to legacy_auth.

The migration follows three distinct stages:

1. Setup (Dry Run): MAS is deployed in read-only mode and initializes the database. The system remains in legacy_auth state, and users continue using legacy authentication. The syn2mas job runs in dry-run mode to verify readiness.
2. Execution (Migration): The migration job runs, downscaling Synapse to 0 replicas during the process. The system transitions to syn2mas_migrated. Users now use delegated authentication. Rollback is no longer possible.
3. Finalization (Disable syn2mas): The syn2mas feature is disabled, and the system transitions to the final delegated_auth state.

The ESS Helm chart manages several stateful components that may persist even after a helm uninstall. Understanding their lifecycle is critical for preventing data loss or configuration errors.

Postgres Persistence

• Default Behavior: If postgres.enabled: true, the chart creates a PersistentVolumeClaim (PVC). This PVC is not deleted on helm uninstall to prevent data loss.
• Configuration:
  • To enable deletion on uninstall: Set postgres.storage.resourcePolicy: delete.
  • To use an external DB: Set postgres.enabled: false and provide connection details.
  • To use an existing PVC: Set postgres.storage.existingClaim.

Synapse Media Persistence

• Default Behavior: The PVC for Synapse media is not deleted on helm uninstall.
• Configuration:
  • To enable deletion on uninstall: Set synapse.media.storage.resourcePolicy: delete.
  • To use an existing PVC: Set synapse.media.storage.existingClaim.

Generated Secrets

• Purpose: When initSecrets.enabled: true, the chart uses Helm hooks to generate credentials (like Synapse signing keys) to support tools like ArgoCD.
• Lifecycle: These Secrets (labeled app.kubernetes.io/managed-by=matrix-tools-init-secrets) are not removed on helm uninstall to prevent losing critical credentials.
• Manual Control: You can disable this by setting initSecrets.enabled: false and providing your own secrets in the values.

Deployment Markers

• Purpose: When deploymentMarkers.enabled: true, the chart records the installation state in a ConfigMap to prevent invalid state transitions during upgrades/reinstalls.
• Lifecycle: The ConfigMap (labeled app.kubernetes.io/managed-by=matrix-tools-deployment-markers) is not removed on helm uninstall.
• Manual Control: You can disable this by setting deploymentMarkers.enabled: false.

Element Server Suite Community is a collection of components used to build a Matrix homeserver. The architecture consists of the following core components:

• Element Web Client: The web chat interface, preconfigured to use your local homeserver.
• Synapse Server: The core Matrix homeserver that handles all communication between users. It can be deployed as a multiple-workers deployment to offload processes and handle more users.
• Redis Pub/Sub: Enables Synapse to broadcast events between different Synapse workers.
• HAproxy: Acts as a load balancer that distributes Matrix API traffic across Synapse workers and the Matrix Authentication Service (MAS). It also serves /.well-known/matrix and /.well-known/element files.
• PostgreSQL Database: The primary storage backend for user profiles, room state, messages, and metadata. While the Helm chart provides a PostgreSQL instance by default, production deployments should use an external database.
• Matrix Authentication Service (MAS): Provides OIDC-based authentication and is enabled by default.
• Matrix RTC Backend: Provides the backend infrastructure for Matrix VoIP video calls.

To automate certificate issuance using Let's Encrypt, use Cert-Manager in your Kubernetes cluster:

1. Add the Jetstack Helm repository:

   helm repo add jetstack https://charts.jetstack.io --force-update

2. Install Cert-Manager:

   helm install \
     cert-manager jetstack/cert-manager \
     --namespace cert-manager \
     --create-namespace \
     --version v1.17.0 \
     --set crds.enabled=true

3. Create a ClusterIssuer to allow ESS to request certificates (using Traefik as the ingress class):

   kubectl apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: letsencrypt-prod
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       privateKeySecretRef:
         name: letsencrypt-prod-private-key
       solvers:
         - http01:
             ingress:
               class: traefik
   EOF

4. Configure ESS by downloading the Let's Encrypt fragment to your config directory:

   curl -L https://raw.githubusercontent.com/element-hq/ess-helm/main/charts/matrix-stack/ci/fragments/quick-setup-letsencrypt.yaml -o ~/ess-config-values/tls.yaml