helm-charts/matrix-synapse/values.yaml

# Scale the whole chart down without uninstalling it: scaleDown: true renders
# every Deployment/StatefulSet with replicas: 0 (and suspends CronJobs) and
# takes precedence over any per-workload replicas value. PVCs, Secrets and
# Services stay in place; scaleDown: false brings the workloads back up.
scaleDown: false

secrets:
  # homeserver.yaml is mounted into the Synapse StatefulSet from the Secret the
  # 1Password operator materializes from this item.
  #
  # Known limitation (#82): a change to the item in the vault does NOT restart
  # Synapse. Helm cannot hash the content (it never sees it - the operator fills
  # the Secret in-cluster after rendering), so the checksum/config mechanism the
  # delegation nginx uses does not apply here. The operator's own
  # "operator.1password.io/auto-restart" annotation is no help either: it only
  # ever restarts Deployments, and this workload is a StatefulSet (verified
  # against onepassword-operator 1.12.0). After changing the item, restart
  # Synapse by hand:
  #   kubectl rollout restart statefulset <release>-matrix-synapse-sfs
  configSecretRef: null

matrix:
  # Replica count for this workload; 0 is allowed and scales it down.
  # The chart-global scaleDown flag takes precedence.
  replicas: 1
  serverName: null
  timezone: UTC
  # The upstream image (ghcr.io/element-hq/synapse) only drops privileges
  # itself (via gosu, driven by UID/GID env vars) when started as root; with
  # an explicit non-root runAsUser it skips that step and runs directly as
  # that user. Synapse writes to /data and /media_store (both on the PVC) and
  # to /tmp (mounted as an emptyDir by the chart), so the root filesystem
  # stays read-only. The uid/gid 1000 matches the previous gosu default, so
  # existing PVC data stays accessible.
  securityContext:
    pod:
      runAsNonRoot: true
      runAsUser: 1000
      runAsGroup: 1000
      fsGroup: 1000
      fsGroupChangePolicy: Always
    container:
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      runAsNonRoot: true
      capabilities:
        drop:
          - ALL
  livenessProbe:
    httpGet:
      path: /health
      port: http
      scheme: HTTP
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3
  readinessProbe:
    httpGet:
      path: /health
      port: http
      scheme: HTTP
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3
  # The startup probe gates liveness/readiness. Synapse can take a
  # while to start (migrations, cache warmup): budget 10s * 30 = 300s.
  startupProbe:
    httpGet:
      path: /health
      port: http
      scheme: HTTP
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 30
  # Extra environment variables, appended to the ones the chart always sets.
  # Values are rendered through tpl; value, secretKeyRef and configMapKeyRef
  # forms are supported.
  env: []
  resources:
    # Limits are optional: memory and ephemeral-storage limits default to
    # limitFactor x the request, an explicitly set limit always wins, and a
    # CPU limit is only set when configured explicitly under "limits".
    limitFactor: 3
    requests:
      memory: "1Gi"
      cpu: "1"
      ephemeralStorage: "1Gi"
  delegation:
    # Replica count for this workload; 0 is allowed and scales it down.
    # The chart-global scaleDown flag takes precedence.
    replicas: 1
    enabled: false
    serverUrl: null
    # Auxiliary image, pinned independently of appVersion (which tracks
    # Synapse). Reviewed alongside every app-version update round.
    image:
      repository: nginx
      tag: 1.30.4
    # The delegation nginx runs as the image's unprivileged nginx user
    # (uid 101) and listens on the unprivileged port 8080; pid file and temp
    # paths are redirected to the /tmp emptyDir by the mounted nginx.conf.
    securityContext:
      pod:
        runAsNonRoot: true
        runAsUser: 101
        runAsGroup: 101
      container:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        runAsNonRoot: true
        capabilities:
          drop:
            - ALL
    livenessProbe:
      httpGet:
        path: /.well-known/matrix/server
        port: http
        scheme: HTTP
      periodSeconds: 10
      timeoutSeconds: 3
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /.well-known/matrix/server
        port: http
        scheme: HTTP
      periodSeconds: 10
      timeoutSeconds: 3
      failureThreshold: 3
    # The startup probe gates liveness/readiness. Startup budget = 5s * 30 = 150s.
    startupProbe:
      httpGet:
        path: /.well-known/matrix/server
        port: http
        scheme: HTTP
      periodSeconds: 5
      timeoutSeconds: 3
      failureThreshold: 30
    resources:
      # Limits are optional: memory and ephemeral-storage limits default to
      # limitFactor x the request, an explicitly set limit always wins, and a
      # CPU limit is only set when configured explicitly under "limits".
      limitFactor: 3
      requests:
        memory: "64Mi"
        cpu: "125m"
        ephemeralStorage: "50Mi"

storage:
  amount: 10Gi
  storageClass: longhorn-encrypted

ingress:
  # Set to false to omit the Ingress entirely. Note that ingress.domain is also
  # read by the delegation nginx, which serves it in the /.well-known/matrix/*
  # endpoints, so it stays required whenever matrix.delegation.enabled is true.
  # Only clusterIssuer becomes unnecessary.
  #
  # MUTUALLY EXCLUSIVE WITH httpRoute.enabled - the render aborts when both are
  # true, and the message names both value paths.
  enabled: true
  domain: null
  clusterIssuer: null
  className: nginx
  # Extra annotations for the Ingress; merged with the cert-manager
  # cluster-issuer annotation the chart always sets.
  #
  # INERT IN GATEWAY MODE - the Gateway API has no annotation channel for
  # controller behaviour. For THIS chart that is not a formality: read the
  # httpRoute block below for what this installation actually has in here and
  # which half of it matters.
  annotations: {}

# THE GATEWAY-API ALTERNATIVE TO THE INGRESS (Gitea #114).
#
# Mutually exclusive with ingress.enabled - the render aborts when both are
# true. The chart renders ONLY HTTPRoutes with parentRefs: no Gateway, no
# class, no Certificate, and no implementation-specific policy object. Class
# and certificate sit on the Gateway and its listeners and belong to the
# platform (cluster-config), which is what keeps the Gateway implementation
# replaceable without touching this chart again.
#
# TWO ROUTES, not one. The Ingress is a single object with two HOST rules - the
# homeserver on ingress.domain at "/", and the delegation nginx on
# matrix.delegation.serverUrl at "/.well-known/matrix". An HTTPRoute's
# hostnames apply to the whole object, so two hostnames wanting different paths
# and different backends must be two objects. (#114 describes this chart as
# rendering its Ingresses in a loop over several apps; it does not - that is
# freesailarr.)
#
# ONE THING THIS MODE MAKES EASIER, and it is the awkward part of Matrix
# delegation: the server name is usually an apex domain that already serves a
# website. Under ingress-nginx two Ingress objects cannot both claim one
# hostname - the admission webhook rejects the second - which is why the
# delegation rule has to live inside this chart's single Ingress object.
# HTTPRoutes attached to the same listener for the same hostname are MERGED by
# the implementation, longest match winning, so here the /.well-known/matrix
# route can sit beside whatever owns that apex without either side knowing.
#
# WHAT THIS MODE COSTS, MEASURED ON THE LIVE OBJECT ON 2026-10-12, where the
# Ingress carried - all of it OPERATOR-supplied through ingress.annotations,
# since this chart sets none of it:
#
#     nginx.ingress.kubernetes.io/proxy-body-size:    50m
#     nginx.org/client-max-body-size:                 50m
#     nginx.ingress.kubernetes.io/configuration-snippet: |
#       more_set_headers "X-Forwarded-For $remote_addr";
#       more_set_headers "X-Forwarded-Proto $scheme";
#       more_set_headers "Host $host:$server_port";
#
# 1. THE BODY SIZE IS THE REAL LOSS. Synapse's media repository takes uploads
#    and its own ceiling is max_upload_size in homeserver.yaml - which this
#    chart cannot see, because the whole config comes from 1Password through
#    secrets.configSecretRef. The effective limit is the smaller of the two,
#    and in this mode the proxy half becomes THE GATEWAY'S default: neither
#    number anyone can point at is necessarily the one that decides. The
#    Gateway API has no body-size field, so per decision 2 of #114 this is
#    documented rather than rebuilt. Set it next to the Gateway, in that
#    implementation's own object, and set it to match max_upload_size.
#    (nginx.org/client-max-body-size is the same limit spelled for NGINX Inc's
#    ingress controller rather than ingress-nginx - a hedge across both - and
#    it goes for the same reason.)
#
# 2. THE SNIPPET IS NOT LOAD-BEARING, WHICH TOOK CHECKING. It looks like what
#    Synapse's x_forwarded setting depends on - client IP for rate limiting,
#    and federation. It is not: more_set_headers is the OUTPUT-header directive
#    of headers-more-nginx-module ("Replaces (if any) or adds (if not any) the
#    specified output headers"), while the request-side directive is
#    more_set_input_headers. These three headers are therefore added to the
#    RESPONSE TO THE CLIENT; Synapse never sees them, and what it reads with
#    x_forwarded: true is the REQUEST's X-Forwarded-For, which ingress-nginx
#    sets itself.
#
#    So for the migration: not translatable, and not needed. The Gateway API's
#    ResponseHeaderModifier can set static response headers but knows no nginx
#    variables ($remote_addr, $scheme, $host), so rebuilding it is impossible
#    anyway - and pointless. Do NOT re-create it at the Gateway in the belief
#    that Synapse needs it.
#
#    Stated as what it is: a reading of the directive's documented semantics.
#    Nothing here observed a Synapse instance with and without the snippet.
#
# THE GATEWAY-API CRDs MUST BE PRESENT. The chart cannot detect them
# (.Capabilities.APIVersions is unreliable at template time) and an HTTPRoute
# without them fails at install, so this is a value and not a guess.
httpRoute:
  enabled: false

  # The Gateway(s) the HOMESERVER route attaches to - a platform object,
  # usually in another namespace, whose listener must allow this namespace in
  # allowedRoutes. Entries are the Gateway API's ParentReference (name, and
  # optionally namespace, sectionName, port, group, kind), passed through
  # unchanged:
  #
  #   parentRefs:
  #     - name: public
  #       namespace: gateway
  #       sectionName: https
  #
  # REQUIRED while httpRoute.enabled is true - the render aborts on an empty
  # list, because a route without a parent is created, is valid and routes
  # nothing, with no event to say so.
  parentRefs: []

  # Empty means [ingress.domain], so the homeserver hostname has one source of
  # truth. Set explicitly only to publish under a different or an additional
  # name - which is how a migration from the Ingress runs: the HTTPRoute takes
  # a second hostname while the Ingress keeps ingress.domain.
  #
  # THE DELEGATION HOST IS NOT COVERED BY THIS LIST, deliberately - see below.
  hostnames: []

  delegation:
    # The delegation route's own parent. Empty falls back to
    # httpRoute.parentRefs. Worth setting when the SERVER NAME is published by
    # a different Gateway than the homeserver host, which is the normal case:
    # the server name is an apex domain somebody else's website usually owns.
    parentRefs: []

    # Empty means [matrix.delegation.serverUrl], and it deliberately does NOT
    # fall back to httpRoute.hostnames. The server name is a different thing
    # from the homeserver's hostname - it is what REMOTE homeservers resolve -
    # and the migration order depends on telling them apart: move the
    # homeserver host first, confirm it answers, move the server name last.
    # A chart-global hostname list covering both would erase that distinction.
    # Set this only when the server name itself has to move.
    hostnames: []

# ---------------------------------------------------------------------------
# NetworkPolicy (Gitea #5). On by default. TWO objects, one per workload - see
# the template for why they are not one. The reference implementation with the
# full reasoning is template-chart; the convention is in README, "Chart style
# guidelines".
# ---------------------------------------------------------------------------
networkPolicy:
  # WHAT THESE POLICIES ALLOW. Synapse: inbound 8008 only, outbound DNS plus TCP
  # 5432 (Postgres), 443 and 8448 (federation, remote media, push gateways,
  # identity servers). The delegation nginx: inbound 8080 only, outbound DNS and
  # NOTHING else - it serves two static JSON documents and calls nobody.
  #
  # THAT ASYMMETRY IS THE REASON THERE ARE TWO. One policy selecting both pods
  # would have to permit the union of what each needs, which would hand
  # Synapse's full federation reach and its database port to an nginx whose
  # whole job is to return a constant - and it would look like one decision
  # rather than a widening.
  #
  # WHAT THEY DO NOT DO: federation cannot be narrowed. 443 and 8448 go to ANY
  # destination, because a federating homeserver may contact any other
  # homeserver on the internet and this object matches CIDRs and selectors but
  # never hostnames. And 5432 is the STANDARD Postgres port, not the configured
  # one - the connection lives inside secrets.configSecretRef, which this chart
  # never parses.
  #
  # Both probe ports stay open inside the cluster by default (see probeSources),
  # and a policy is only a boundary where the CNI enforces one.
  enabled: true
  # Namespaces whose pods may reach either workload, in addition to the
  # release's own namespace, which is always allowed. Empty means: own namespace
  # only. Matched on the "kubernetes.io/metadata.name" label Kubernetes sets on
  # every namespace itself, so no labelling work is needed - and no typo
  # protection either: a name that does not exist matches nothing and is
  # silently ineffective. An entry opens the port to EVERY pod in that
  # namespace.
  allowedNamespaces: []
  # Source CIDRs allowed to reach the two probe ports (Synapse's 8008 and the
  # delegation server's 8080). ONE VALUE GOVERNS BOTH POLICIES.
  #
  # EMPTY MEANS OPEN, NOT BLOCKED. With no entry both rules are rendered WITHOUT
  # a "from" selector, so the ports are reachable from anywhere the CNI routes
  # to - inside the cluster, since neither carries a NodePort.
  #
  # The kubelet's probes originate from the IP of the WORKER NODE running the
  # pod, an address this chart cannot know and must not guess: a CIDR that
  # excludes the real node blocks every probe, the pod never becomes Ready, the
  # rollout times out, and the symptom reads as a broken application rather
  # than as a policy.
  #
  # AND MIND WHAT ELSE THESE TWO PORTS CARRY. Inbound federation arrives at
  # 8008 through the Ingress, and every remote homeserver that wants to
  # federate fetches /.well-known/matrix from 8080. Narrowing this list without
  # ingressController below therefore does not merely hide a web UI: it stops
  # federation, inbound and discoverable, and the failure shows up on OTHER
  # people's servers before it shows up here.
  probeSources: []
  # The ingress controller allowed to reach both ports once probeSources
  # restricts them. Rendered only while ingress.enabled or httpRoute.enabled is
  # true, and only in the restricted branch - with the default (open) rules the
  # controller reaches both ports anyway.
  #
  # The two keys become ONE "from" entry and are therefore an AND: pods carrying
  # podLabels IN namespace. That is the point of having them here - the
  # controller's namespace in allowedNamespaces would open both ports to every
  # pod in kube-system.
  #
  # MEASURED ON THIS CLUSTER, NOT ASSUMED (2026-10-14): ingress-nginx is gone,
  # the only IngressClass is "traefik" and it is the default, and the controller
  # is the DaemonSet rke2-traefik in kube-system. The same Traefik serves the
  # Gateway API here, so this one source covers the Ingress and the HTTPRoute
  # path alike. A policy written against the wrong controller is accepted, looks
  # strict, and silently blocks all web traffic - and ingress.className says
  # nothing about it, because a class names an implementation, not the pods the
  # traffic comes from.
  ingressController:
    namespace: kube-system
    podLabels:
      app.kubernetes.io/name: rke2-traefik

  # The policy's INBOUND side. Mind the three names that overlap as substrings,
  # because a search for "ingress" matches all of them and they are different
  # things:
  #
  #   ingress                          (top level) the Ingress OBJECT this chart
  #                                    renders - host, TLS, className
  #   networkPolicy.ingress            this block: what the policy lets IN
  #   networkPolicy.ingressController  the SOURCE SELECTOR for the ingress
  #                                    controller's pods. A SIBLING of this block
  #                                    and NO PART OF IT, despite the name.
  ingress:
    # Opens the pod for Istio's ambient mesh (Gitea #143). OFF by default and
    # additive: while it is false this chart renders byte for byte as it did
    # before the value existed.
    #
    # IT RENDERS TWO THINGS, and that they come together is the point:
    #
    #   1. 15008/TCP inbound - ztunnel's HBONE tunnel. Every inbound mesh
    #      connection arrives on it, and ambient "does not and will never bypass
    #      Kubernetes NetworkPolicy enforcement", so without this port a pod
    #      whose namespace has joined the mesh is unreachable.
    #   2. 169.254.7.127/32 as an additional peer - but ONLY where the rule
    #      restricts sources at all, which here means probeSources is non-empty.
    #      Inside the mesh the kubelet's probes are redirected and no longer come
    #      from the worker node's address.
    #
    # WHY ONE SWITCH AND NOT TWO: point 2 is the one nobody thinks of. Whoever
    # adds "15008" to a port list by hand writes a policy that passes review, and
    # the first time probeSources is narrowed every probe is dropped - the pod
    # never becomes Ready and the symptom reads as a broken application rather
    # than as a policy. A switch whose halves can only be had together cannot be
    # set halfway, which is why this is a named intention and not a port list.
    #
    # TWO THINGS IT DOES NOT PROVE:
    #   - That 15008 alone is enough. That comes from Istio's documentation;
    #     measured on this cluster is only which listeners ztunnel opens.
    #     Provable at the first namespace to join the mesh - none carries
    #     istio.io/dataplane-mode yet.
    #   - That the probe-source half works. probeSources is empty in every chart
    #     here, so no release reaches that branch. CI proves its render, not its
    #     effect.
    #
    # Note where the port lands: it joins the rule that carries the probe port,
    # so once probeSources restricts that rule, 15008 is restricted with it.
    # Whether ztunnel needs a peer of its own is open - it runs with its own pod
    # IPs in istio-system (measured: no hostNetwork on the DaemonSet, Istio
    # 1.30.6), so if one proves necessary it is expressible as a
    # namespaceSelector plus podSelector and needs no unknowable node CIDR.
    # BOTH NUMBERS BELOW ARE ISTIO CONSTANTS, NOT STANDARDS, and they are values
    # rather than template literals for exactly that reason: a vendor constant
    # can change, and an operator should be able to correct it without waiting
    # for a chart release. Their provenance is written on each one.
    #
    # DELETING THIS OBJECT IS SAFE. Every read falls back to the defaults
    # declared here (#99), so "ambientMesh: null", or an object carrying only
    # "enabled: true", renders the documented defaults instead of failing.
    ambientMesh:
      # The switch. Everything else here is inert while it is false, and the
      # chart renders exactly as it did before the object existed.
      enabled: false

      # ISTIO'S HBONE PORT. A constant Istio chose, not a standard: not
      # registered with IANA for this, prescribed by no protocol, and unknown to
      # Kubernetes. Read for ztunnel 1.30.6 (measured on this cluster: ztunnel
      # opens [::]:15008 as its inbound listener).
      #
      # If Istio changes it, a pod in the mesh cannot be reached. Change it here
      # in all 30 charts AND in the pinned expectation inside
      # ci/run-networkpolicy-test.sh - the test is deliberately what forces
      # someone to look, because the exception it grants this port is pinned to
      # the number IT knows and not to whatever this value says. A value-driven
      # exception would let a mistyped port through, which is the hole design A
      # of #143 was rejected for.
      #
      # NOT MEASURED: that this port ALONE suffices comes from Istio's
      # documentation. Measured here is only which listeners ztunnel opens, and
      # no namespace carries istio.io/dataplane-mode yet.
      port: 15008

      # SOURCES THE KUBELET'S PROBES ARRIVE FROM ONCE ISTIO HAS REDIRECTED THEM.
      #
      # NOT THE SAME VALUE AS networkPolicy.probeSources one level up, and the
      # two are easy to confuse, so:
      #
      #   networkPolicy.probeSources
      #       YOUR worker node CIDRs. Empty by default, and empty means the
      #       probe rule is OPEN. The chart cannot know these addresses.
      #   networkPolicy.ingress.ambientMesh.redirectedProbeSources
      #       ISTIO's rewrite address. Shipped filled, because unlike the node
      #       IPs it is a constant the chart CAN know. Only rendered where the
      #       rule above is restricted, i.e. where probeSources is non-empty.
      #
      # WHERE 169.254.7.127 COMES FROM - vendor magic, not protocol:
      #
      #   - LINK-LOCAL, 169.254.0.0/16 (RFC 3927): a range reserved for
      #     node-local use that is never routed - exactly the range one picks a
      #     vendor's magic address out of.
      #   - Istio's IPv6 counterpart gives it away:
      #     fd16:9254:7127:1337:ffff:ffff:ffff:ffff carries the SAME DIGITS
      #     (9254:7127 is 169.254.7.127) plus 1337. Numbers built that way are
      #     vendor constants, not protocols.
      #   - KUBERNETES DOES NOT KNOW THIS ADDRESS. Neither the NetworkPolicy API
      #     nor the kubelet has any notion of it; only Istio's own data plane
      #     rewrites the probe source onto it.
      #
      # Read for ztunnel 1.30.6. IF ISTIO CHANGES IT, THE FAILURE IS SILENT:
      # probes would be dropped, and only where probeSources is non-empty - which
      # is nowhere in this repository today - so nothing here and nothing in
      # Kubernetes would report it. What to re-check then: the address Istio's
      # release notes name for probe redirection, this list in all 30 charts, and
      # the pinned expectation in ci/run-networkpolicy-test.sh.
      #
      # A LIST, not a string, and the one case where that does not contradict "a
      # constant, not a configuration": on a DUAL-STACK cluster BOTH entries are
      # needed at the same time, not one of two. This cluster is SingleStack
      # IPv4, so the IPv6 counterpart is left out - an ipBlock of the wrong
      # family is accepted by the API server and matches nothing. Add it
      # ALONGSIDE, never instead, if the cluster gains IPv6.
      #
      # Clearing this list restores the default rather than removing the ipBlock,
      # deliberately: the two halves of this switch are not separable. To not
      # open the port at all, set enabled: false.
      #
      # UNPROVEN IN OPERATION: probeSources is empty in every chart here, so no
      # release reaches this branch. CI proves the render, not the effect.
      redirectedProbeSources:
        - 169.254.7.127/32

  egress:
    # Additional outbound TCP ports FOR SYNAPSE ONLY. These deliberately do NOT
    # widen the delegation server's policy: an entry meant for Synapse's
    # database has no business reaching a workload that serves a constant.
    #
    # DNS is always allowed and has no switch - a knob whose only other setting
    # breaks every name lookup is a trap, not a feature, and Synapse resolves a
    # name for every server it federates with.
    #
    # PORTS, NOT DESTINATIONS: a NetworkPolicy matches CIDRs and selectors and
    # never hostnames, so each entry permits its port to ANY destination.
    #
    # The usual entries here: a Postgres that is not on 5432, a TURN/coturn
    # server for voice (3478 and its relay range), or SMTP (587 or 465) if this
    # release sends mail - Synapse's mail configuration lives inside
    # secrets.configSecretRef, which this chart never reads.
    extraPorts: []