diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index cd971bd..5117c44 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -39,7 +39,7 @@ jobs: run: | export DEBIAN_FRONTEND=noninteractive apt-get update -qq - apt-get install -y -qq --no-install-recommends ca-certificates curl git python3-minimal >/dev/null + apt-get install -y -qq --no-install-recommends ca-certificates curl git python3-minimal python3-yaml >/dev/null - uses: coffey-labs/actions/checkout@fab0c4d45e0162963965f1555df27b7bed5e20ec - run: tools/install-tools.sh - run: tools/check.sh diff --git a/.gitignore b/.gitignore index 6d0c0ea..691d755 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ # Tools from tools/install-tools.sh .tools/ +__pycache__/ diff --git a/CHANGELOG.md b/CHANGELOG.md index b699455..014bacd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,10 @@ runs, pinned by digest. status names the part and why. The server container keeps its last log lines as its termination message too. Needs server 27.1-rc.33: an older server doesn't know `--check`. +- `tools/docs-pages.py --out ` writes the docs' generated Kubernetes + pages: the values reference, the Services and their ports, what each + network policy lets in and out, and the alerts, from `helm template` with + `ci/docs-values.yaml`. CI builds them, so a change that breaks one fails. - `charts/inbuxa/VALUES.md`, every value with its default and what the schema allows, generated from values.yaml and the schema by `tools/values-reference.py`; CI fails when it's out of date. The schema diff --git a/charts/inbuxa/VALUES.md b/charts/inbuxa/VALUES.md index 9e47a5e..6109b35 100644 --- a/charts/inbuxa/VALUES.md +++ b/charts/inbuxa/VALUES.md @@ -8,42 +8,42 @@ Every value the chart takes, with its default and what the values schema allows. A value the schema doesn't name is refused, as is one outside these limits, before anything is applied. -- **`nameOverride`** (string) - Default: `""`. - Allowed: at most 40 characters; matching `^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$`. +- **`nameOverride`** (string)\ + Default: `""`.\ + Allowed: at most 40 characters; matching `^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$`.\ Overrides the "inbuxa" in the names of everything the chart creates. -- **`fullnameOverride`** (string) - Default: `""`. - Allowed: at most 52 characters; matching `^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$`. +- **`fullnameOverride`** (string)\ + Default: `""`.\ + Allowed: at most 52 characters; matching `^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$`.\ Overrides the whole name (release name plus chart name). -- **`imagePullSecrets`** (list of object) +- **`imagePullSecrets`** (list of object)\ Default: `[]`. ## `server` ### `server.image` -- **`server.image.repository`** (string) - Default: `ghcr.io/inbuxa/inbuxa-server`. +- **`server.image.repository`** (string)\ + Default: `ghcr.io/inbuxa/inbuxa-server`.\ Allowed: at least 1 character. -- **`server.image.tag`** (string) - Default: `""`. +- **`server.image.tag`** (string)\ + Default: `""`.\ Defaults to the chart's appVersion -- **`server.image.digest`** (string) - Default: `""`. - Allowed: matching `^(sha256:[a-f0-9]{64})?$`. +- **`server.image.digest`** (string)\ + Default: `""`.\ + Allowed: matching `^(sha256:[a-f0-9]{64})?$`.\ sha256:..., which wins over the tag when set -- **`server.image.pullPolicy`** (string) - Default: `IfNotPresent`. +- **`server.image.pullPolicy`** (string)\ + Default: `IfNotPresent`.\ Allowed: one of `"Always"`, `"IfNotPresent"`, `"Never"`. -- **`server.dataStore`** (object) - Default: `{}`. +- **`server.dataStore`** (object)\ + Default: `{}`.\ The data store, written as the server's config.json. Required. A secret in it is a File reference to a path under /etc/inbuxa/secrets, never the secret itself. For example: ```yaml @@ -56,8 +56,8 @@ outside these limits, before anything is applied. useTls: true ``` -- **`server.secretMounts`** (list of object) - Default: `[]`. +- **`server.secretMounts`** (list of object)\ + Default: `[]`.\ Secrets mounted under /etc/inbuxa/secrets, where the data store, blob store and coordinator settings point with File references. Each entry is an existing Secret and the keys to mount from it: ```yaml @@ -69,58 +69,58 @@ outside these limits, before anything is applied. The new store's setup, applied once on install, before any server pod starts: the domain, administrator, blob store, coordinator and cluster roles the groups below name. A JMAP request body ("using" and "methodCalls"), the calls an administrator would send to /jmap, run as the system administrator. A value {"$file": /path} is replaced by that file's contents: put secrets in seed.secretMounts, never in the seed. Ignored by a store that's set up already. See the server's --seed. -- **`server.seed.enabled`** (boolean) +- **`server.seed.enabled`** (boolean)\ Default: `false`. -- **`server.seed.request`** (object) - Default: `{}`. +- **`server.seed.request`** (object)\ + Default: `{}`.\ The seed, as values -- **`server.seed.existingConfigMap`** (string) - Default: `""`. +- **`server.seed.existingConfigMap`** (string)\ + Default: `""`.\ Or an existing ConfigMap with it under the key seed.json -- **`server.seed.secretMounts`** (list of object) - Default: `[]`. +- **`server.seed.secretMounts`** (list of object)\ + Default: `[]`.\ Secrets only the seed run sees, at /etc/inbuxa/seed-secrets, in the same form as secretMounts -- **`server.seed.timeoutSeconds`** (integer) - Default: `600`. +- **`server.seed.timeoutSeconds`** (integer)\ + Default: `600`.\ Allowed: at least 30. -- **`server.seed.resources`** (object) - Default: `{}`. +- **`server.seed.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). ### `server.upgrade` Before an upgrade rolls new pods out, a Job on the new image asks the server what the upgrade does to the store, and upgrades it. Give `helm upgrade` a --timeout long enough for it: 20m covers a layout step that has to wait for the old pods' heartbeats to run out. -- **`server.upgrade.enabled`** (boolean) +- **`server.upgrade.enabled`** (boolean)\ Default: `true`. -- **`server.upgrade.acknowledgeLayout`** (integer) - Default: `0`. - Allowed: at least 0. +- **`server.upgrade.acknowledgeLayout`** (integer)\ + Default: `0`.\ + Allowed: at least 0.\ A change to the store's layout can't be undone without a backup taken before it. The upgrade refuses one until this names the layout version it moves to (the refusal says which): 3 for the 27.1 crossing. -- **`server.upgrade.stopServers`** (boolean) - Default: `true`. +- **`server.upgrade.stopServers`** (boolean)\ + Default: `true`.\ When a layout step needs every server pod stopped, scale the server Deployments to 0 first (mail is down until the rollout). Off: the upgrade waits for them to stop, and fails if they don't. -- **`server.upgrade.timeoutSeconds`** (integer) - Default: `1800`. +- **`server.upgrade.timeoutSeconds`** (integer)\ + Default: `1800`.\ Allowed: at least 60. -- **`server.upgrade.resources`** (object) - Default: `{}`. +- **`server.upgrade.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). ### `server.check` Before each server pod starts, an init container checks the data layer (`inbuxa --check`): it opens the data store, writes, reads and deletes a small object in the blob store, and connects to NATS. A pod that can't use one stays in Init:Error, and its status names the part and why (kubectl describe pod). Needs server 27.1-rc.33 or later. -- **`server.check.enabled`** (boolean) +- **`server.check.enabled`** (boolean)\ Default: `true`. #### `server.check.resources` @@ -129,63 +129,63 @@ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, #### `server.check.resources.requests` -- **`server.check.resources.requests.cpu`** (string or number) +- **`server.check.resources.requests.cpu`** (string or number)\ Default: `50m`. -- **`server.check.resources.requests.memory`** (string or number) +- **`server.check.resources.requests.memory`** (string or number)\ Default: `64Mi`. #### `server.check.resources.limits` -- **`server.check.resources.limits.memory`** (string or number) +- **`server.check.resources.limits.memory`** (string or number)\ Default: `256Mi`. -- **`server.publicUrl`** (string) - Default: `""`. - Allowed: matching `^(https://[^/\s]+)?$`. +- **`server.publicUrl`** (string)\ + Default: `""`.\ + Allowed: matching `^(https://[^/\s]+)?$`.\ Where browsers and clients reach the server, as https://host. Sign-in pages and OAuth metadata name it. -- **`server.trustedProxies`** (list of string) - Default: `[]`. +- **`server.trustedProxies`** (list of string)\ + Default: `[]`.\ The proxies whose X-Forwarded-For the server believes, as CIDRs: the ingress or gateway, and the webmail. The server reads the header so that its limits and bans for failed sign-ins count each client, not the proxy. Empty: loopback and the private ranges, which covers pods on most clusters. List your pod network here if it isn't private (100.64.0.0/10, say). ### `server.listeners` The port in the pod of each listener a new store gets, which is what the Services send traffic to. 0 leaves that listener out. The pods may listen below 1024 without any privilege: they set the namespaced sysctl net.ipv4.ip_unprivileged_port_start, which Pod Security "restricted" allows. SMTP stays on 25: the server's default rules tell mail from the internet from submissions by local port 25. Used once, when the store is new; after that the listeners are settings in the console, and these have to match them. -- **`server.listeners.smtp`** (integer) - Default: `25`. - Allowed: one of `0`, `25`. +- **`server.listeners.smtp`** (integer)\ + Default: `25`.\ + Allowed: one of `0`, `25`.\ 25, or 0 for no SMTP. The server's default rules treat only port 25 as mail from the internet, so SMTP can't move. -- **`server.listeners.submissions`** (integer) - Default: `465`. - Allowed: at least 0; at most 65535. +- **`server.listeners.submissions`** (integer)\ + Default: `465`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.listeners.imaps`** (integer) - Default: `993`. - Allowed: at least 0; at most 65535. +- **`server.listeners.imaps`** (integer)\ + Default: `993`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.listeners.pop3s`** (integer) - Default: `0`. - Allowed: at least 0; at most 65535. +- **`server.listeners.pop3s`** (integer)\ + Default: `0`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.listeners.sieve`** (integer) - Default: `4190`. - Allowed: at least 0; at most 65535. +- **`server.listeners.sieve`** (integer)\ + Default: `4190`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.listeners.https`** (integer) - Default: `443`. - Allowed: at least 0; at most 65535. +- **`server.listeners.https`** (integer)\ + Default: `443`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.listeners.http`** (integer) - Default: `8080`. - Allowed: at least 1; at most 65535. +- **`server.listeners.http`** (integer)\ + Default: `8080`.\ + Allowed: at least 1; at most 65535.\ Plain HTTP, which the probes use, so it can't be left out. ### `server.groups` @@ -196,126 +196,126 @@ The server's role groups, each a Deployment. INBUXA_ROLE names a role (a Cluster Client protocols, web and JMAP; no outbound delivery, no scheduler -- **`server.groups.front.enabled`** (boolean) +- **`server.groups.front.enabled`** (boolean)\ Default: `true`. -- **`server.groups.front.replicas`** (integer) - Default: `2`. +- **`server.groups.front.replicas`** (integer)\ + Default: `2`.\ Allowed: at least 0. -- **`server.groups.front.role`** (string) - Default: `peer`. +- **`server.groups.front.role`** (string)\ + Default: `peer`.\ The registry ClusterRole the group's pods run as; empty runs every task. -- **`server.groups.front.resources`** (object) - Default: `{}`. +- **`server.groups.front.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). -- **`server.groups.front.nodeSelector`** (map of string) +- **`server.groups.front.nodeSelector`** (map of string)\ Default: `{}`. -- **`server.groups.front.tolerations`** (list of object) +- **`server.groups.front.tolerations`** (list of object)\ Default: `[]`. -- **`server.groups.front.affinity`** (object) +- **`server.groups.front.affinity`** (object)\ Default: `{}`. -- **`server.groups.front.podAnnotations`** (map of string) +- **`server.groups.front.podAnnotations`** (map of string)\ Default: `{}`. -- **`server.groups.front.podLabels`** (map of string) - Default: `{}`. +- **`server.groups.front.podLabels`** (map of string)\ + Default: `{}`.\ Extra labels on the pods, for what selects them by label: an egress gateway policy, say. Not app.kubernetes.io/ or inbuxa.org/ ones. -- **`server.groups.front.extraEnv`** (list of object) +- **`server.groups.front.extraEnv`** (list of object)\ Default: `[]`. #### `server.groups.mta` As front, plus outbound delivery. Place it where its egress address is the one your SPF and PTR records name: on nodes with a fixed address (nodeSelector, tolerations), or behind an egress gateway that selects it (podLabels). server.egress checks it. -- **`server.groups.mta.enabled`** (boolean) +- **`server.groups.mta.enabled`** (boolean)\ Default: `true`. -- **`server.groups.mta.replicas`** (integer) - Default: `2`. +- **`server.groups.mta.replicas`** (integer)\ + Default: `2`.\ Allowed: at least 0. -- **`server.groups.mta.role`** (string) - Default: `peer-mta`. +- **`server.groups.mta.role`** (string)\ + Default: `peer-mta`.\ The registry ClusterRole the group's pods run as; empty runs every task. -- **`server.groups.mta.resources`** (object) - Default: `{}`. +- **`server.groups.mta.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). -- **`server.groups.mta.nodeSelector`** (map of string) +- **`server.groups.mta.nodeSelector`** (map of string)\ Default: `{}`. -- **`server.groups.mta.tolerations`** (list of object) +- **`server.groups.mta.tolerations`** (list of object)\ Default: `[]`. -- **`server.groups.mta.affinity`** (object) +- **`server.groups.mta.affinity`** (object)\ Default: `{}`. -- **`server.groups.mta.podAnnotations`** (map of string) +- **`server.groups.mta.podAnnotations`** (map of string)\ Default: `{}`. -- **`server.groups.mta.podLabels`** (map of string) - Default: `{}`. +- **`server.groups.mta.podLabels`** (map of string)\ + Default: `{}`.\ Extra labels on the pods, for what selects them by label: an egress gateway policy, say. Not app.kubernetes.io/ or inbuxa.org/ ones. -- **`server.groups.mta.extraEnv`** (list of object) +- **`server.groups.mta.extraEnv`** (list of object)\ Default: `[]`. #### `server.groups.core` Everything, including the task scheduler. Exactly one replica: a second would queue every maintenance task twice. -- **`server.groups.core.enabled`** (boolean) +- **`server.groups.core.enabled`** (boolean)\ Default: `true`. -- **`server.groups.core.replicas`** (integer) - Default: `1`. - Allowed: at least 0; at most 1. +- **`server.groups.core.replicas`** (integer)\ + Default: `1`.\ + Allowed: at least 0; at most 1.\ 0 or 1: a second core would queue every maintenance task twice. -- **`server.groups.core.role`** (string) - Default: `""`. +- **`server.groups.core.role`** (string)\ + Default: `""`.\ The registry ClusterRole the group's pods run as; empty runs every task. -- **`server.groups.core.resources`** (object) - Default: `{}`. +- **`server.groups.core.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). -- **`server.groups.core.nodeSelector`** (map of string) +- **`server.groups.core.nodeSelector`** (map of string)\ Default: `{}`. -- **`server.groups.core.tolerations`** (list of object) +- **`server.groups.core.tolerations`** (list of object)\ Default: `[]`. -- **`server.groups.core.affinity`** (object) +- **`server.groups.core.affinity`** (object)\ Default: `{}`. -- **`server.groups.core.podAnnotations`** (map of string) +- **`server.groups.core.podAnnotations`** (map of string)\ Default: `{}`. -- **`server.groups.core.podLabels`** (map of string) - Default: `{}`. +- **`server.groups.core.podLabels`** (map of string)\ + Default: `{}`.\ Extra labels on the pods, for what selects them by label: an egress gateway policy, say. Not app.kubernetes.io/ or inbuxa.org/ ones. -- **`server.groups.core.extraEnv`** (list of object) +- **`server.groups.core.extraEnv`** (list of object)\ Default: `[]`. ### `server.egress` The addresses outbound mail should leave from: the ones with reverse DNS (PTR) records and in your SPF. When set, a Job placed like the mta pods asks checkUrl which address it came from after each install and upgrade, and records the answer on the mta Deployment as an event: a Warning when it isn't one of these (kubectl get events). checkUrl answers a GET with the caller's address as plain text; pick one you trust, as it sees your cluster's address. -- **`server.egress.expectedAddresses`** (list of string) +- **`server.egress.expectedAddresses`** (list of string)\ Default: `[]`. -- **`server.egress.checkUrl`** (string) - Default: `""`. +- **`server.egress.checkUrl`** (string)\ + Default: `""`.\ Allowed: matching `^(https?://\S+)?$`. ### `server.certificates` @@ -332,28 +332,28 @@ chart ask cert-manager for one. The pods reread them within about two minutes of a renewal, with no restart. Needs server 27.1-rc.33. ``` -- **`server.certificates.acmeHosts`** (list of string) +- **`server.certificates.acmeHosts`** (list of string)\ Default: `[]`. -- **`server.certificates.secrets`** (list of string) - Default: `[]`. +- **`server.certificates.secrets`** (list of string)\ + Default: `[]`.\ Names of Secrets in this namespace, each with tls.crt and tls.key #### `server.certificates.certManager` -- **`server.certificates.certManager.enabled`** (boolean) +- **`server.certificates.certManager.enabled`** (boolean)\ Default: `false`. -- **`server.certificates.certManager.issuerRef`** (object) - Default: `{}`. +- **`server.certificates.certManager.issuerRef`** (object)\ + Default: `{}`.\ The Issuer or ClusterIssuer, e.g. {name: letsencrypt, kind: ClusterIssuer} -- **`server.certificates.certManager.dnsNames`** (list of string) - Default: `[]`. +- **`server.certificates.certManager.dnsNames`** (list of string)\ + Default: `[]`.\ The mail host names, e.g. [mail.example.org, mx.example.org] -- **`server.certificates.certManager.renewBefore`** (string) - Default: `""`. +- **`server.certificates.certManager.renewBefore`** (string)\ + Default: `""`.\ Renew this long before expiry; empty is cert-manager's default ### `server.resources` @@ -362,46 +362,46 @@ Used for every group that sets no resources of its own #### `server.resources.requests` -- **`server.resources.requests.cpu`** (string or number) +- **`server.resources.requests.cpu`** (string or number)\ Default: `250m`. -- **`server.resources.requests.memory`** (string or number) +- **`server.resources.requests.memory`** (string or number)\ Default: `512Mi`. #### `server.resources.limits` -- **`server.resources.limits.cpu`** (string or number) +- **`server.resources.limits.cpu`** (string or number)\ Default: `"2"`. -- **`server.resources.limits.memory`** (string or number) +- **`server.resources.limits.memory`** (string or number)\ Default: `2Gi`. -- **`server.terminationGracePeriodSeconds`** (integer) - Default: `120`. - Allowed: at least 0. +- **`server.terminationGracePeriodSeconds`** (integer)\ + Default: `120`.\ + Allowed: at least 0.\ Time for SMTP sessions in progress to finish when a pod stops ### `server.topologySpread` Pods of a group are spread across nodes (never two on one node while another node has room) and, where the cluster has zones, across zones. -- **`server.topologySpread.nodes`** (string) - Default: `DoNotSchedule`. +- **`server.topologySpread.nodes`** (string)\ + Default: `DoNotSchedule`.\ Allowed: one of `"DoNotSchedule"`, `"ScheduleAnyway"`, `"off"`. -- **`server.topologySpread.zones`** (string) - Default: `ScheduleAnyway`. +- **`server.topologySpread.zones`** (string)\ + Default: `ScheduleAnyway`.\ Allowed: one of `"DoNotSchedule"`, `"ScheduleAnyway"`, `"off"`. ### `server.podDisruptionBudget` At most this many pods of a group down at once for a drain or upgrade -- **`server.podDisruptionBudget.enabled`** (boolean) +- **`server.podDisruptionBudget.enabled`** (boolean)\ Default: `true`. -- **`server.podDisruptionBudget.maxUnavailable`** (integer) - Default: `1`. +- **`server.podDisruptionBudget.maxUnavailable`** (integer)\ + Default: `1`.\ Allowed: at least 1. ### `server.services` @@ -410,159 +410,159 @@ At most this many pods of a group down at once for a drain or upgrade Web, JMAP and the API, inside the cluster. Front ends and an Ingress or Gateway route point here. -- **`server.services.http.type`** (string) - Default: `ClusterIP`. +- **`server.services.http.type`** (string)\ + Default: `ClusterIP`.\ Allowed: one of `"ClusterIP"`, `"NodePort"`, `"LoadBalancer"`. -- **`server.services.http.annotations`** (map of string) +- **`server.services.http.annotations`** (map of string)\ Default: `{}`. -- **`server.services.http.groups`** (array) +- **`server.services.http.groups`** (array)\ Default: `[front, core]`. #### `server.services.mail` Mail from outside, on the standard ports. Local keeps each client's own address (no SNAT): the load balancer sends only to nodes running a mail pod. -- **`server.services.mail.enabled`** (boolean) +- **`server.services.mail.enabled`** (boolean)\ Default: `true`. -- **`server.services.mail.type`** (string) - Default: `LoadBalancer`. +- **`server.services.mail.type`** (string)\ + Default: `LoadBalancer`.\ Allowed: one of `"LoadBalancer"`, `"NodePort"`, `"ClusterIP"`. -- **`server.services.mail.externalTrafficPolicy`** (string) - Default: `Local`. +- **`server.services.mail.externalTrafficPolicy`** (string)\ + Default: `Local`.\ Allowed: one of `"Local"`, `"Cluster"`. -- **`server.services.mail.loadBalancerClass`** (string) +- **`server.services.mail.loadBalancerClass`** (string)\ Default: `""`. -- **`server.services.mail.loadBalancerIP`** (string) +- **`server.services.mail.loadBalancerIP`** (string)\ Default: `""`. -- **`server.services.mail.annotations`** (map of string) +- **`server.services.mail.annotations`** (map of string)\ Default: `{}`. -- **`server.services.mail.groups`** (array) +- **`server.services.mail.groups`** (array)\ Default: `[front, mta]`. #### `server.services.mail.ports` -- **`server.services.mail.ports.smtp`** (integer) - Default: `25`. +- **`server.services.mail.ports.smtp`** (integer)\ + Default: `25`.\ Allowed: at least 0; at most 65535. -- **`server.services.mail.ports.submissions`** (integer) - Default: `465`. +- **`server.services.mail.ports.submissions`** (integer)\ + Default: `465`.\ Allowed: at least 0; at most 65535. -- **`server.services.mail.ports.imaps`** (integer) - Default: `993`. +- **`server.services.mail.ports.imaps`** (integer)\ + Default: `993`.\ Allowed: at least 0; at most 65535. -- **`server.services.mail.ports.pop3s`** (integer) - Default: `995`. +- **`server.services.mail.ports.pop3s`** (integer)\ + Default: `995`.\ Allowed: at least 0; at most 65535. -- **`server.services.mail.ports.sieve`** (integer) - Default: `4190`. +- **`server.services.mail.ports.sieve`** (integer)\ + Default: `4190`.\ Allowed: at least 0; at most 65535. #### `server.services.mail.proxyProtocol` PROXY protocol v2 from the load balancer, instead of keeping the client's address with externalTrafficPolicy Local alone. The pods get a second listener for each mail port (these ports in the pod) that takes the client's address from the PROXY header, believed only from trustedNetworks: the load balancer's own addresses, as it connects to the pods. Keep externalTrafficPolicy Local: with Cluster, connections arrive from the nodes, and trusting nodes lets anyone who reaches a port claim any address. The load balancer listens on the standard ports (25, 465, ...): the server tells mail from the internet by port 25, which it reads from the PROXY header. Needs server 27.1-rc.32. -- **`server.services.mail.proxyProtocol.enabled`** (boolean) +- **`server.services.mail.proxyProtocol.enabled`** (boolean)\ Default: `false`. -- **`server.services.mail.proxyProtocol.trustedNetworks`** (list of string) - Default: `[]`. +- **`server.services.mail.proxyProtocol.trustedNetworks`** (list of string)\ + Default: `[]`.\ The load balancer's addresses, as it connects to the pods: addresses or networks of /8 or narrower. #### `server.services.mail.proxyProtocol.ports` -- **`server.services.mail.proxyProtocol.ports.smtp`** (integer) - Default: `10025`. - Allowed: at least 0; at most 65535. +- **`server.services.mail.proxyProtocol.ports.smtp`** (integer)\ + Default: `10025`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.services.mail.proxyProtocol.ports.submissions`** (integer) - Default: `10465`. - Allowed: at least 0; at most 65535. +- **`server.services.mail.proxyProtocol.ports.submissions`** (integer)\ + Default: `10465`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.services.mail.proxyProtocol.ports.imaps`** (integer) - Default: `10993`. - Allowed: at least 0; at most 65535. +- **`server.services.mail.proxyProtocol.ports.imaps`** (integer)\ + Default: `10993`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.services.mail.proxyProtocol.ports.pop3s`** (integer) - Default: `10995`. - Allowed: at least 0; at most 65535. +- **`server.services.mail.proxyProtocol.ports.pop3s`** (integer)\ + Default: `10995`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. -- **`server.services.mail.proxyProtocol.ports.sieve`** (integer) - Default: `14190`. - Allowed: at least 0; at most 65535. +- **`server.services.mail.proxyProtocol.ports.sieve`** (integer)\ + Default: `14190`.\ + Allowed: at least 0; at most 65535.\ A port in the pod, or 0 to leave the listener out. ### `server.backup` A nightly export of the whole store to an S3 bucket (`inbuxa --export s3://...`), streamed, while the server runs. Each goes in a new folder named for the time, with export.json written last: an export without it didn't finish. Nothing here deletes old exports: give the bucket a lifecycle rule. Restore into a new, empty store with `inbuxa --import s3://bucket/prefix` (the newest finished export) before any server pod starts. Needs server 27.1-rc.34. -- **`server.backup.enabled`** (boolean) +- **`server.backup.enabled`** (boolean)\ Default: `false`. -- **`server.backup.schedule`** (string) - Default: `"30 2 * * *"`. - Allowed: at least 1 character. +- **`server.backup.schedule`** (string)\ + Default: `"30 2 * * *"`.\ + Allowed: at least 1 character.\ Cron, in timeZone (the controller's, UTC on most clusters, when empty) -- **`server.backup.timeZone`** (string) +- **`server.backup.timeZone`** (string)\ Default: `""`. -- **`server.backup.url`** (string) - Default: `""`. - Allowed: matching `^$|^s3://[^/]+(/.*)?$`. +- **`server.backup.url`** (string)\ + Default: `""`.\ + Allowed: matching `^$|^s3://[^/]+(/.*)?$`.\ s3://bucket/prefix -- **`server.backup.endpoint`** (string) - Default: `""`. - Allowed: matching `^$|^https?://`. +- **`server.backup.endpoint`** (string)\ + Default: `""`.\ + Allowed: matching `^$|^https?://`.\ An S3-compatible service (MinIO, Garage, Ceph), addressed path-style; empty for AWS -- **`server.backup.region`** (string) - Default: `us-east-1`. +- **`server.backup.region`** (string)\ + Default: `us-east-1`.\ Allowed: at least 1 character. -- **`server.backup.existingSecret`** (string) - Default: `""`. +- **`server.backup.existingSecret`** (string)\ + Default: `""`.\ A Secret with the keys under access-key and secret-key. Empty: the AWS defaults (the pod's role, through serviceAccountName) -- **`server.backup.serviceAccountName`** (string) +- **`server.backup.serviceAccountName`** (string)\ Default: `""`. -- **`server.backup.timeoutSeconds`** (integer) - Default: `21600`. - Allowed: at least 60. +- **`server.backup.timeoutSeconds`** (integer)\ + Default: `21600`.\ + Allowed: at least 60.\ A run longer than this is stopped (and fails) -- **`server.backup.backoffLimit`** (integer) - Default: `1`. - Allowed: at least 0. +- **`server.backup.backoffLimit`** (integer)\ + Default: `1`.\ + Allowed: at least 0.\ Tries per night: a failed try leaves an unfinished folder behind -- **`server.backup.successfulJobsHistoryLimit`** (integer) - Default: `3`. +- **`server.backup.successfulJobsHistoryLimit`** (integer)\ + Default: `3`.\ Allowed: at least 0. -- **`server.backup.failedJobsHistoryLimit`** (integer) - Default: `3`. +- **`server.backup.failedJobsHistoryLimit`** (integer)\ + Default: `3`.\ Allowed: at least 0. -- **`server.backup.resources`** (object) - Default: `{}`. +- **`server.backup.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). ### `server.storeCheck` @@ -571,43 +571,43 @@ Store checks on a schedule (`inbuxa --store-check`): quick finds blobs the store #### `server.storeCheck.quick` -- **`server.storeCheck.quick.enabled`** (boolean) +- **`server.storeCheck.quick.enabled`** (boolean)\ Default: `false`. -- **`server.storeCheck.quick.schedule`** (string) - Default: `"15 3 * * *"`. +- **`server.storeCheck.quick.schedule`** (string)\ + Default: `"15 3 * * *"`.\ Allowed: at least 1 character. -- **`server.storeCheck.quick.timeoutSeconds`** (integer) - Default: `21600`. +- **`server.storeCheck.quick.timeoutSeconds`** (integer)\ + Default: `21600`.\ Allowed: at least 60. #### `server.storeCheck.full` -- **`server.storeCheck.full.enabled`** (boolean) +- **`server.storeCheck.full.enabled`** (boolean)\ Default: `false`. -- **`server.storeCheck.full.schedule`** (string) - Default: `"15 4 * * 0"`. +- **`server.storeCheck.full.schedule`** (string)\ + Default: `"15 4 * * 0"`.\ Allowed: at least 1 character. -- **`server.storeCheck.full.timeoutSeconds`** (integer) - Default: `172800`. +- **`server.storeCheck.full.timeoutSeconds`** (integer)\ + Default: `172800`.\ Allowed: at least 60. -- **`server.storeCheck.timeZone`** (string) +- **`server.storeCheck.timeZone`** (string)\ Default: `""`. -- **`server.storeCheck.successfulJobsHistoryLimit`** (integer) - Default: `3`. +- **`server.storeCheck.successfulJobsHistoryLimit`** (integer)\ + Default: `3`.\ Allowed: at least 0. -- **`server.storeCheck.failedJobsHistoryLimit`** (integer) - Default: `3`. +- **`server.storeCheck.failedJobsHistoryLimit`** (integer)\ + Default: `3`.\ Allowed: at least 0. -- **`server.storeCheck.resources`** (object) - Default: `{}`. +- **`server.storeCheck.resources`** (object)\ + Default: `{}`.\ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). ### `server.metrics` @@ -616,182 +616,182 @@ Metrics, for Prometheus or an OpenTelemetry collector. Needs server 27.1-rc.34; #### `server.metrics.prometheus` -- **`server.metrics.prometheus.enabled`** (boolean) - Default: `false`. +- **`server.metrics.prometheus.enabled`** (boolean)\ + Default: `false`.\ Every server pod serves /metrics/prometheus on its http port, behind basic auth. A headless Service, -metrics, lists them all. -- **`server.metrics.prometheus.username`** (string) - Default: `prometheus`. +- **`server.metrics.prometheus.username`** (string)\ + Default: `prometheus`.\ Allowed: matching `^[^:\s]+$`. -- **`server.metrics.prometheus.existingSecret`** (string) - Default: `""`. +- **`server.metrics.prometheus.existingSecret`** (string)\ + Default: `""`.\ A Secret with the keys username (the same as above) and password. Empty: the chart makes one, with a random password kept across upgrades. The pods read the password as a file. #### `server.metrics.prometheus.serviceMonitor` A ServiceMonitor for the Prometheus Operator, scraping each pod -- **`server.metrics.prometheus.serviceMonitor.enabled`** (boolean) +- **`server.metrics.prometheus.serviceMonitor.enabled`** (boolean)\ Default: `false`. -- **`server.metrics.prometheus.serviceMonitor.interval`** (string) - Default: `30s`. +- **`server.metrics.prometheus.serviceMonitor.interval`** (string)\ + Default: `30s`.\ Allowed: matching `^[0-9]+(ms|s|m|h)$`. -- **`server.metrics.prometheus.serviceMonitor.labels`** (map of string) +- **`server.metrics.prometheus.serviceMonitor.labels`** (map of string)\ Default: `{}`. #### `server.metrics.prometheus.rules` PrometheusRules: alerts for a pod down, a cluster lease not renewed, a large or stuck queue, failing deliveries, a certificate about to expire and a slow data store. They read the pods' group from the label the ServiceMonitor adds, so they need it on. -- **`server.metrics.prometheus.rules.enabled`** (boolean) +- **`server.metrics.prometheus.rules.enabled`** (boolean)\ Default: `false`. -- **`server.metrics.prometheus.rules.labels`** (map of string) +- **`server.metrics.prometheus.rules.labels`** (map of string)\ Default: `{}`. -- **`server.metrics.prometheus.rules.kubeStateMetrics`** (boolean) - Default: `true`. +- **`server.metrics.prometheus.rules.kubeStateMetrics`** (boolean)\ + Default: `true`.\ Alerts on restarts and readiness from kube-state-metrics, when the cluster has it -- **`server.metrics.prometheus.rules.queueMessages`** (integer) - Default: `5000`. - Allowed: at least 1. +- **`server.metrics.prometheus.rules.queueMessages`** (integer)\ + Default: `5000`.\ + Allowed: at least 1.\ Messages in the queue -- **`server.metrics.prometheus.rules.queueOldestHours`** (number) - Default: `24`. - Allowed: more than 0. +- **`server.metrics.prometheus.rules.queueOldestHours`** (number)\ + Default: `24`.\ + Allowed: more than 0.\ Hours the oldest message may wait. A queue keeps retrying a message for days, so one that waits longer is worth a look. -- **`server.metrics.prometheus.rules.deliveryFailureRatio`** (number) - Default: `0.25`. - Allowed: more than 0; at most 1. +- **`server.metrics.prometheus.rules.deliveryFailureRatio`** (number)\ + Default: `0.25`.\ + Allowed: more than 0; at most 1.\ Share of deliveries that bounce, over half an hour, once at least deliveryFailureMinimum have -- **`server.metrics.prometheus.rules.deliveryFailureMinimum`** (integer) - Default: `10`. +- **`server.metrics.prometheus.rules.deliveryFailureMinimum`** (integer)\ + Default: `10`.\ Allowed: at least 1. -- **`server.metrics.prometheus.rules.certificateDays`** (number) - Default: `14`. - Allowed: more than 0. +- **`server.metrics.prometheus.rules.certificateDays`** (number)\ + Default: `14`.\ + Allowed: more than 0.\ Days before the first certificate in use expires -- **`server.metrics.prometheus.rules.storeLatencyMs`** (number) - Default: `1000`. - Allowed: more than 0. +- **`server.metrics.prometheus.rules.storeLatencyMs`** (number)\ + Default: `1000`.\ + Allowed: more than 0.\ 99th-percentile data store read or write, in milliseconds -- **`server.metrics.prometheus.rules.backupHours`** (number) - Default: `36`. - Allowed: more than 0. +- **`server.metrics.prometheus.rules.backupHours`** (number)\ + Default: `36`.\ + Allowed: more than 0.\ With backup on and kubeStateMetrics: hours since the last export that finished #### `server.metrics.otlp` Push metrics to an OpenTelemetry collector over OTLP. Only when the store has no OpenTelemetry metrics set: the console's setting wins. Every pod pushes its own, named by service.instance.id and k8s.pod.name; the collector adds them up. -- **`server.metrics.otlp.enabled`** (boolean) +- **`server.metrics.otlp.enabled`** (boolean)\ Default: `false`. -- **`server.metrics.otlp.endpoint`** (string) - Default: `""`. - Allowed: matching `^$|^https?://`. +- **`server.metrics.otlp.endpoint`** (string)\ + Default: `""`.\ + Allowed: matching `^$|^https?://`.\ The collector, e.g. http://otel-collector.monitoring:4318 -- **`server.metrics.otlp.protocol`** (string) - Default: `http/protobuf`. - Allowed: one of `"http/protobuf"`, `"grpc"`. +- **`server.metrics.otlp.protocol`** (string)\ + Default: `http/protobuf`.\ + Allowed: one of `"http/protobuf"`, `"grpc"`.\ http/protobuf or grpc -- **`server.metrics.otlp.intervalSeconds`** (integer) - Default: `60`. +- **`server.metrics.otlp.intervalSeconds`** (integer)\ + Default: `60`.\ Allowed: at least 1. -- **`server.metrics.otlp.headersSecret`** (string) - Default: `""`. +- **`server.metrics.otlp.headersSecret`** (string)\ + Default: `""`.\ A Secret whose key headers holds headers to send, key=value pairs by commas or lines, for a collector that wants a token. The pods read it as a file. #### `server.metrics.grafanaDashboard` A Grafana dashboard as a ConfigMap, for Grafana's dashboard sidecar -- **`server.metrics.grafanaDashboard.enabled`** (boolean) +- **`server.metrics.grafanaDashboard.enabled`** (boolean)\ Default: `false`. -- **`server.metrics.grafanaDashboard.labels`** (map of string) +- **`server.metrics.grafanaDashboard.labels`** (map of string)\ The label the sidecar looks for -- **`server.metrics.grafanaDashboard.labels.grafana_dashboard`** (string) +- **`server.metrics.grafanaDashboard.labels.grafana_dashboard`** (string)\ Default: `"1"`. -- **`server.metrics.grafanaDashboard.annotations`** (map of string) +- **`server.metrics.grafanaDashboard.annotations`** (map of string)\ Default: `{}`. ## `webmail` The webmail, signing people in through the server's own page (OAuth). Off by default: it needs its own address, and the server's publicUrl. -- **`webmail.enabled`** (boolean) +- **`webmail.enabled`** (boolean)\ Default: `false`. ### `webmail.image` -- **`webmail.image.repository`** (string) - Default: `ghcr.io/inbuxa/inbuxa-webmail`. +- **`webmail.image.repository`** (string)\ + Default: `ghcr.io/inbuxa/inbuxa-webmail`.\ Allowed: at least 1 character. -- **`webmail.image.tag`** (string) - Default: `""`. +- **`webmail.image.tag`** (string)\ + Default: `""`.\ The webmail's own release (27.1-rc.N); it's versioned apart from the server, so there's no default. Needs 27.1-rc.7 or later. -- **`webmail.image.digest`** (string) - Default: `""`. +- **`webmail.image.digest`** (string)\ + Default: `""`.\ Allowed: matching `^(sha256:[0-9a-f]{64})?$`. -- **`webmail.image.pullPolicy`** (string) - Default: `IfNotPresent`. +- **`webmail.image.pullPolicy`** (string)\ + Default: `IfNotPresent`.\ Allowed: one of `"Always"`, `"IfNotPresent"`, `"Never"`. -- **`webmail.publicUrl`** (string) - Default: `""`. - Allowed: matching `^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`. +- **`webmail.publicUrl`** (string)\ + Default: `""`.\ + Allowed: matching `^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`.\ Where browsers reach it, as https://host. Required. The server registers it as an OAuth client with this address. -- **`webmail.replicas`** (integer) - Default: `2`. +- **`webmail.replicas`** (integer)\ + Default: `2`.\ Allowed: at least 1. -- **`webmail.existingSecret`** (string) - Default: `""`. +- **`webmail.existingSecret`** (string)\ + Default: `""`.\ A Secret with app-secret (seals sessions; the same on every replica) and oauth-client-secret (the server holds it too). Empty: the chart makes one with random values and keeps them across upgrades. The webmail reads both as files, never from its environment. -- **`webmail.previousAppSecret`** (boolean) - Default: `false`. +- **`webmail.previousAppSecret`** (boolean)\ + Default: `false`.\ While rotating app-secret: true, with the old value(s), comma-separated, under app-secret-previous in existingSecret. Sessions sealed with them still open. Set it back to false once they have expired. -- **`webmail.trustedProxies`** (list of string) - Default: `[]`. +- **`webmail.trustedProxies`** (list of string)\ + Default: `[]`.\ Addresses whose X-Forwarded-For the webmail believes, as CIDRs. Empty: the private ranges, which covers an ingress inside the cluster. ### `webmail.autoscaling` -- **`webmail.autoscaling.enabled`** (boolean) +- **`webmail.autoscaling.enabled`** (boolean)\ Default: `false`. -- **`webmail.autoscaling.minReplicas`** (integer) - Default: `2`. +- **`webmail.autoscaling.minReplicas`** (integer)\ + Default: `2`.\ Allowed: at least 1. -- **`webmail.autoscaling.maxReplicas`** (integer) - Default: `6`. +- **`webmail.autoscaling.maxReplicas`** (integer)\ + Default: `6`.\ Allowed: at least 1. -- **`webmail.autoscaling.targetCPUUtilizationPercentage`** (integer) - Default: `70`. +- **`webmail.autoscaling.targetCPUUtilizationPercentage`** (integer)\ + Default: `70`.\ Allowed: at least 1; at most 100. ### `webmail.resources` @@ -800,92 +800,92 @@ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, #### `webmail.resources.requests` -- **`webmail.resources.requests.cpu`** (string or number) +- **`webmail.resources.requests.cpu`** (string or number)\ Default: `100m`. -- **`webmail.resources.requests.memory`** (string or number) +- **`webmail.resources.requests.memory`** (string or number)\ Default: `128Mi`. #### `webmail.resources.limits` -- **`webmail.resources.limits.cpu`** (string or number) +- **`webmail.resources.limits.cpu`** (string or number)\ Default: `"1"`. -- **`webmail.resources.limits.memory`** (string or number) +- **`webmail.resources.limits.memory`** (string or number)\ Default: `512Mi`. ### `webmail.podDisruptionBudget` -- **`webmail.podDisruptionBudget.enabled`** (boolean) +- **`webmail.podDisruptionBudget.enabled`** (boolean)\ Default: `true`. -- **`webmail.podDisruptionBudget.maxUnavailable`** (integer or string) +- **`webmail.podDisruptionBudget.maxUnavailable`** (integer or string)\ Default: `1`. -- **`webmail.nodeSelector`** (map of string) +- **`webmail.nodeSelector`** (map of string)\ Default: `{}`. -- **`webmail.tolerations`** (array) +- **`webmail.tolerations`** (array)\ Default: `[]`. -- **`webmail.affinity`** (object) +- **`webmail.affinity`** (object)\ Default: `{}`. -- **`webmail.podAnnotations`** (map of string) +- **`webmail.podAnnotations`** (map of string)\ Default: `{}`. -- **`webmail.extraEnv`** (array) +- **`webmail.extraEnv`** (array)\ Default: `[]`. ## `console` INBUXA Admin, the console, served as static files; the browser talks to the server's publicUrl directly. Off by default, like the webmail. -- **`console.enabled`** (boolean) +- **`console.enabled`** (boolean)\ Default: `false`. ### `console.image` -- **`console.image.repository`** (string) - Default: `ghcr.io/inbuxa/inbuxa-admin`. +- **`console.image.repository`** (string)\ + Default: `ghcr.io/inbuxa/inbuxa-admin`.\ Allowed: at least 1 character. -- **`console.image.tag`** (string) - Default: `""`. +- **`console.image.tag`** (string)\ + Default: `""`.\ The console's own release (27.1-rc.N); no default, as for the webmail -- **`console.image.digest`** (string) - Default: `""`. +- **`console.image.digest`** (string)\ + Default: `""`.\ Allowed: matching `^(sha256:[0-9a-f]{64})?$`. -- **`console.image.pullPolicy`** (string) - Default: `IfNotPresent`. +- **`console.image.pullPolicy`** (string)\ + Default: `IfNotPresent`.\ Allowed: one of `"Always"`, `"IfNotPresent"`, `"Never"`. -- **`console.publicUrl`** (string) - Default: `""`. - Allowed: matching `^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`. +- **`console.publicUrl`** (string)\ + Default: `""`.\ + Allowed: matching `^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`.\ Where browsers reach it, as https://host. Required. The server registers it as an OAuth client and lets its origin call the API. -- **`console.replicas`** (integer) - Default: `2`. +- **`console.replicas`** (integer)\ + Default: `2`.\ Allowed: at least 1. ### `console.autoscaling` -- **`console.autoscaling.enabled`** (boolean) +- **`console.autoscaling.enabled`** (boolean)\ Default: `false`. -- **`console.autoscaling.minReplicas`** (integer) - Default: `2`. +- **`console.autoscaling.minReplicas`** (integer)\ + Default: `2`.\ Allowed: at least 1. -- **`console.autoscaling.maxReplicas`** (integer) - Default: `4`. +- **`console.autoscaling.maxReplicas`** (integer)\ + Default: `4`.\ Allowed: at least 1. -- **`console.autoscaling.targetCPUUtilizationPercentage`** (integer) - Default: `70`. +- **`console.autoscaling.targetCPUUtilizationPercentage`** (integer)\ + Default: `70`.\ Allowed: at least 1; at most 100. ### `console.resources` @@ -894,49 +894,49 @@ Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, #### `console.resources.requests` -- **`console.resources.requests.cpu`** (string or number) +- **`console.resources.requests.cpu`** (string or number)\ Default: `20m`. -- **`console.resources.requests.memory`** (string or number) +- **`console.resources.requests.memory`** (string or number)\ Default: `32Mi`. #### `console.resources.limits` -- **`console.resources.limits.cpu`** (string or number) +- **`console.resources.limits.cpu`** (string or number)\ Default: `500m`. -- **`console.resources.limits.memory`** (string or number) +- **`console.resources.limits.memory`** (string or number)\ Default: `128Mi`. ### `console.podDisruptionBudget` -- **`console.podDisruptionBudget.enabled`** (boolean) +- **`console.podDisruptionBudget.enabled`** (boolean)\ Default: `true`. -- **`console.podDisruptionBudget.maxUnavailable`** (integer or string) +- **`console.podDisruptionBudget.maxUnavailable`** (integer or string)\ Default: `1`. -- **`console.nodeSelector`** (map of string) +- **`console.nodeSelector`** (map of string)\ Default: `{}`. -- **`console.tolerations`** (array) +- **`console.tolerations`** (array)\ Default: `[]`. -- **`console.affinity`** (object) +- **`console.affinity`** (object)\ Default: `{}`. -- **`console.podAnnotations`** (map of string) +- **`console.podAnnotations`** (map of string)\ Default: `{}`. ## `networkPolicy` NetworkPolicies: every pod the chart makes denies all traffic in and out except what it needs (templates/networkpolicy.yaml has the map). They need a CNI that enforces them. -- **`networkPolicy.enabled`** (boolean) +- **`networkPolicy.enabled`** (boolean)\ Default: `true`. -- **`networkPolicy.httpFrom`** (list of object) - Default: `[]`. +- **`networkPolicy.httpFrom`** (list of object)\ + Default: `[]`.\ Who may reach the HTTP ports of the server, the webmail and the console: your ingress controller or gateway, as NetworkPolicy peers, e.g. Empty: from anywhere. The webmail always reaches the server. ```yaml @@ -944,8 +944,8 @@ NetworkPolicies: every pod the chart makes denies all traffic in and out except matchLabels: {kubernetes.io/metadata.name: ingress-nginx} ``` -- **`networkPolicy.metricsFrom`** (list of object) - Default: `[]`. +- **`networkPolicy.metricsFrom`** (list of object)\ + Default: `[]`.\ Prometheus, when httpFrom is set: it scrapes the server pods' http port. As NetworkPolicy peers, e.g. ```yaml @@ -953,12 +953,12 @@ NetworkPolicies: every pod the chart makes denies all traffic in and out except matchLabels: {kubernetes.io/metadata.name: monitoring} ``` -- **`networkPolicy.serverEgress`** (list of object) - Default: `[]`. +- **`networkPolicy.serverEgress`** (list of object)\ + Default: `[]`.\ Where the server and its Jobs may connect, as NetworkPolicy egress rules, besides DNS. Empty: anywhere, which a mail server needs to deliver mail unless it hands everything to a relay. Narrow it to your data store, relay and the Kubernetes API (for the upgrade Job) if you can. -- **`networkPolicy.webmailInternet`** (boolean) - Default: `true`. +- **`networkPolicy.webmailInternet`** (boolean)\ + Default: `true`.\ The webmail fetches remote images in mail and subscribed calendars over HTTP and HTTPS. Off: only the server. ## `routes` @@ -967,27 +967,27 @@ Routes from outside to the server's publicUrl, the webmail's and the console's, ### `routes.gateway` -- **`routes.gateway.enabled`** (boolean) +- **`routes.gateway.enabled`** (boolean)\ Default: `false`. -- **`routes.gateway.parentRefs`** (array) - Default: `[]`. +- **`routes.gateway.parentRefs`** (array)\ + Default: `[]`.\ The Gateway listeners to attach to, e.g. [{name: public, namespace: gateway}] -- **`routes.gateway.annotations`** (map of string) +- **`routes.gateway.annotations`** (map of string)\ Default: `{}`. ### `routes.ingress` -- **`routes.ingress.enabled`** (boolean) +- **`routes.ingress.enabled`** (boolean)\ Default: `false`. -- **`routes.ingress.className`** (string) +- **`routes.ingress.className`** (string)\ Default: `""`. -- **`routes.ingress.annotations`** (map of string) +- **`routes.ingress.annotations`** (map of string)\ Default: `{}`. -- **`routes.ingress.tls`** (array) - Default: `[]`. +- **`routes.ingress.tls`** (array)\ + Default: `[]`.\ As an Ingress takes it, e.g. [{hosts: [mail.example.org], secretName: mail-tls}] diff --git a/charts/inbuxa/ci/docs-values.yaml b/charts/inbuxa/ci/docs-values.yaml new file mode 100644 index 0000000..f999ee7 --- /dev/null +++ b/charts/inbuxa/ci/docs-values.yaml @@ -0,0 +1,40 @@ +# SPDX-FileCopyrightText: 2026 Coffey Labs LLC +# SPDX-License-Identifier: Apache-2.0 +# +# What tools/docs-pages.py renders the docs' tables from: the defaults, plus +# the parts most installs turn on (webmail, console, metrics, backups), so +# every Service, policy and alert shows. Anything else stays at its default. +server: + dataStore: + "@type": PostgreSql + host: pg-rw.data.svc + port: 5432 + database: inbuxa + authUsername: inbuxa + authSecret: {"@type": File, filePath: /etc/inbuxa/secrets/pg-password} + useTls: true + secretMounts: + - secretName: inbuxa-data + items: [{key: pg-password, path: pg-password}] + publicUrl: https://mail.example.org + backup: + enabled: true + url: s3://mail-backups/inbuxa + existingSecret: inbuxa-backup-keys + storeCheck: + quick: {enabled: true} + full: {enabled: true} + metrics: + prometheus: + enabled: true + serviceMonitor: {enabled: true} + rules: {enabled: true} +webmail: + enabled: true + image: {tag: 27.1-rc.9} + publicUrl: https://webmail.example.org + existingSecret: webmail-secrets +console: + enabled: true + image: {tag: 27.1-rc.22} + publicUrl: https://admin.example.org diff --git a/tools/check.sh b/tools/check.sh index 0010543..406322e 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -31,6 +31,9 @@ done step "the values reference is current (tools/values-reference.py)" python3 tools/values-reference.py --check +step "the docs' generated Kubernetes pages build (tools/docs-pages.py)" +python3 tools/docs-pages.py --out "$OUT/docs" + step "bad values are refused before anything is applied (tools/bad-values)" # Each file's first line names what the refusal has to mention. helm # template, as an install renders: the schema and the templates' own checks. diff --git a/tools/docs-pages.py b/tools/docs-pages.py new file mode 100755 index 0000000..155e599 --- /dev/null +++ b/tools/docs-pages.py @@ -0,0 +1,295 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Coffey Labs LLC +# SPDX-License-Identifier: Apache-2.0 +"""The generated pages of the docs' Kubernetes section, from the chart as +built: the values reference, the ports, Services and network policies, and +the alerts. The docs' other pages are written by hand and link to these. + + tools/docs-pages.py --out ../inbuxa.org/docs-site/content/docs/kubernetes + tools/docs-pages.py --check DIR fails when DIR's copies are out of date + +The tables come from `helm template` with ci/docs-values.yaml (the defaults, +plus webmail, console, metrics and backups on), so they show what an +install gets, not what the templates could make. Needs helm and PyYAML. +""" +import importlib.util, json, re, subprocess, sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +CHART = ROOT / "charts" / "inbuxa" +VALUES = CHART / "ci" / "docs-values.yaml" +PAGES = ("values.md", "ports.md", "alerts.md") + +spec = importlib.util.spec_from_file_location("values_reference", ROOT / "tools" / "values-reference.py") +values_reference = importlib.util.module_from_spec(spec) +spec.loader.exec_module(values_reference) + +# What each port is for, by the name the chart gives it +PORTS = { + "smtp": "Mail from the internet (MX)", + "submissions": "Mail clients sending, over TLS", + "submission": "Mail clients sending, STARTTLS", + "imaps": "IMAP over TLS", + "imap": "IMAP, STARTTLS", + "pop3s": "POP3 over TLS", + "sieve": "ManageSieve (filters)", + "https": "JMAP, CalDAV, CardDAV, WebDAV, the server's web pages, ACME", + "http": "Plain HTTP inside the cluster", +} + +# What each chart part runs +COMPONENT = { + "server": "the mail server", + "webmail": "the webmail", + "console": "the console", +} + +# A Service's own port, where the port's name alone says too little +SERVICE_PORTS = { + "webmail": "The webmail, behind your ingress or gateway", + "console": "The console, behind your ingress or gateway", + "metrics": "Prometheus scrapes each pod's `/metrics/prometheus`", +} + +LABEL_HELP = { + "inbuxa.org/serves-http": "the groups that serve HTTP", + "inbuxa.org/serves-mail": "the groups that take mail connections", +} + + +def render(): + out = subprocess.run( + ["helm", "template", "inbuxa", str(CHART), "-n", "inbuxa", "-f", str(VALUES)], + check=True, capture_output=True, text=True, + ).stdout + return [d for d in yaml.safe_load_all(out) if d] + + +def chart_version(): + chart = yaml.safe_load((CHART / "Chart.yaml").read_text()) + return chart["version"], chart["appVersion"] + + +def front(title, description): + version, app = chart_version() + return [ + "---", + f"title: {title}", + "description: >-", + f" {description}", + "---", + f"", + "", + ] + + +def values_page(): + entries = values_reference.read_values((CHART / "values.yaml").read_text()) + schema = json.loads((CHART / "values.schema.json").read_text()) + lines = front( + "Values reference", + "Every value the **inbuxa** chart takes, with its default and what it allows.", + ) + lines += [ + "Every value the chart takes, with its default and what the chart", + "allows. A value it doesn't name is refused, as is one outside these", + "limits, before anything is applied: `helm install` and `helm upgrade`", + "stop with the value's name and what's wrong with it.", + "", + ] + lines += values_reference.body(entries, schema) + return "\n".join(lines).rstrip() + "\n" + + +def component(labels): + return labels.get("app.kubernetes.io/component", "") + + +def workloads(docs): + """[(name, pod labels)] of every Deployment""" + return [ + (d["metadata"]["name"], d["spec"]["template"]["metadata"]["labels"]) + for d in docs if d["kind"] == "Deployment" + ] + + +def selects(selector, labels): + return all(labels.get(k) == v for k, v in (selector or {}).items()) + + +def who(selector, docs): + """The Deployments a selector picks, by name""" + names = [n for n, labels in workloads(docs) if selects(selector, labels)] + return ", ".join(f"`{n}`" for n in names) or "none" + + +def peer(p): + if "podSelector" in p and "namespaceSelector" not in p: + c = component(p["podSelector"].get("matchLabels", {})) + return COMPONENT.get(c, f"pods labelled {json.dumps(p['podSelector'])}") + " pods" + if "namespaceSelector" in p: + return f"namespaces matching `{json.dumps(p['namespaceSelector'])}`" + if "ipBlock" in p: + return f"`{p['ipBlock']['cidr']}`" + return json.dumps(p) + + +def ports_of(rule): + ports = rule.get("ports") + if not ports: + return "any port" + return ", ".join(f"{p['port']}/{p.get('protocol', 'TCP')}" for p in ports) + + +def rules(kind, items): + if items is None: + return [f"- {kind}: nothing (only what other policies allow)"] + if not items: + return [f"- {kind}: nothing"] + out = [] + for r in items: + peers = r.get("from") or r.get("to") + where = "anywhere" if not peers else ", ".join(peer(p) for p in peers) + out.append(f"- {kind}: {ports_of(r)}, {'from' if kind == 'In' else 'to'} {where}") + return out + + +def ports_page(docs): + lines = front( + "Ports, Services and network policies", + "The Services the **inbuxa** chart makes, the ports on each, and what its network policies let in and out.", + ) + lines += [ + "What an install with the webmail, the console, metrics and backups", + "on gets. The ports are the chart's defaults; `server.listeners`", + "moves them in the pods and `server.services` changes the Services.", + "", + "## Services", + "", + ] + for s in (d for d in docs if d["kind"] == "Service"): + spec = s["spec"] + kind = spec.get("type", "ClusterIP") + if spec.get("clusterIP") == "None": + kind += ", headless" + sel = {k: v for k, v in spec["selector"].items() if not k.startswith("app.kubernetes.io/") or k == "app.kubernetes.io/component"} + lines += [ + f"### `{s['metadata']['name']}`", + "", + f"{kind}. Sends to {who(spec['selector'], docs)}" + + "".join(f" ({LABEL_HELP[k]})" for k in sel if k in LABEL_HELP) + ".", + "", + "| Port | Name | Pod port | For |", + "|---|---|---|---|", + ] + own = SERVICE_PORTS.get(s["metadata"]["name"].rsplit("-", 1)[-1]) + for p in spec["ports"]: + use = own if own and len(spec["ports"]) == 1 else PORTS.get(p["name"], "") + lines.append(f"| {p['port']} | `{p['name']}` | `{p.get('targetPort', p['port'])}` | {use} |") + lines.append("") + lines += [ + "## Network policies", + "", + "The chart denies everything to and from its pods, then allows what", + "each part needs. `networkPolicy` narrows these (who may reach HTTP,", + "who may scrape metrics, where the server may connect).", + "", + ] + for p in (d for d in docs if d["kind"] == "NetworkPolicy"): + spec = p["spec"] + sel = spec["podSelector"] + c = component(sel.get("matchLabels", {})) + expr = [e for e in sel.get("matchExpressions", []) if e["key"] == "app.kubernetes.io/component"] + if expr: + pods = "the Jobs: " + ", ".join(f"`{v}`" for v in expr[0]["values"]) + elif c: + pods = COMPONENT.get(c, c) + else: + pods = "every pod of the release" + lines += [f"### `{p['metadata']['name']}`", "", f"Applies to {pods}.", ""] + types = spec.get("policyTypes", []) + if "Ingress" in types: + lines += rules("In", spec.get("ingress")) + if "Egress" in types: + lines += rules("Out", spec.get("egress")) + lines.append("") + return "\n".join(lines).rstrip() + "\n" + + +def alerts_page(docs): + lines = front( + "Prometheus alerts", + "The alert rules the **inbuxa** chart ships for Prometheus, and what each one means.", + ) + lines += [ + "With `server.metrics.prometheus.rules.enabled`, the chart ships", + "these as a PrometheusRule. Thresholds are the defaults; each is a", + "value under `server.metrics.prometheus.rules`. The ones from", + "kube-state-metrics need it running, and", + "`rules.kubeStateMetrics` (on by default).", + "", + "| Alert | Severity | After | Fires when | What to do |", + "|---|---|---|---|---|", + ] + for r in (d for d in docs if d["kind"] == "PrometheusRule"): + for group in r["spec"]["groups"]: + for rule in group["rules"]: + if "alert" not in rule: + continue + notes = rule.get("annotations", {}) + when = words(notes.get("summary", "")) + todo = " ".join( + t for t in re.split(r"(?<=[.;])\s+", " ".join(notes.get("description", "").split())) + if "{{" not in t + ) + lines.append( + f"| `{rule['alert']}` | {rule.get('labels', {}).get('severity', '')} " + f"| {rule.get('for', 'at once')} | {cell(when)} | {cell(todo)} |" + ) + return "\n".join(lines).rstrip() + "\n" + + +def words(summary): + """An alert's summary without Prometheus' templating: what fills each in""" + summary = summary.strip().strip('"') + summary = re.sub(r"\{\{\s*\$labels\.pod\s*\}\}", "A server pod", summary) + summary = re.sub(r"^(\w[\w ]*?) \{\{\s*\$labels\.job_name\s*\}\}", lambda m: "A " + m[1].lower() + " Job", summary) + summary = re.sub(r"\{\{\s*\$labels\.(\w+)\s*\}\}", lambda m: f"the {m[1]}", summary) + summary = re.sub(r"\{\{\s*\$value[^}]*\}\}", "N", summary) + summary = re.sub(r"\{\{[^}]*\}\}", "…", summary) + return summary[:1].upper() + summary[1:] + + +def cell(text): + return text.replace("|", "\\|") + + +def pages(): + docs = render() + return {"values.md": values_page(), "ports.md": ports_page(docs), "alerts.md": alerts_page(docs)} + + +def main(): + args = sys.argv[1:] + if len(args) != 2 or args[0] not in ("--out", "--check"): + sys.exit(__doc__) + out = Path(args[1]) + built = pages() + if args[0] == "--check": + stale = [n for n, text in built.items() if not (out / n).exists() or (out / n).read_text() != text] + if stale: + sys.exit(f"out of date in {out}: {', '.join(stale)}: run tools/docs-pages.py --out {out}") + print(f"{out}: the generated pages are current") + return + out.mkdir(parents=True, exist_ok=True) + for name, text in built.items(): + (out / name).write_text(text) + print(f"wrote {out / name}") + + +if __name__ == "__main__": + main() diff --git a/tools/values-reference.py b/tools/values-reference.py index 3216c79..f83bd32 100755 --- a/tools/values-reference.py +++ b/tools/values-reference.py @@ -147,18 +147,26 @@ def prose(comment): def render(entries, root): - out = [ - "", - "", - "# inbuxa chart values", - "", - "Every value the chart takes, with its default and what the values", - "schema allows. A value the schema doesn't name is refused, as is one", - "outside these limits, before anything is applied.", - "", - ] + return "\n".join(HEADER + body(entries, root)).rstrip() + "\n" + + +HEADER = [ + "", + "", + "# inbuxa chart values", + "", + "Every value the chart takes, with its default and what the values", + "schema allows. A value the schema doesn't name is refused, as is one", + "outside these limits, before anything is applied.", + "", +] + + +def body(entries, root): + """Every value's entry, as Markdown lines (the docs pages use these too)""" + out = [] for path, comment, value, block in entries: depth = path.count(".") s = schema_at(root, path) @@ -176,24 +184,28 @@ def render(entries, root): out += ["```yaml", *example, "```", ""] continue default = value if value not in (None, "") else None - out.append(f"- **`{path}`**" + (f" ({kind})" if kind else "")) - if default is not None: - out.append(f" Default: `{default}`.") - elif block: - out.append(" Default:") - out.append("") - out.append(" ```yaml") + # One line each for the name, the default, the limits and the + # comment: a backslash ends a line without starting a paragraph + head = f"- **`{path}`**" + (f" ({kind})" if kind else "") + rest = [] + if limits: + rest.append("Allowed: " + "; ".join(limits) + ".") + if paragraph: + rest.append(paragraph) + if default is not None or not block: + lines = [head] + ([f"Default: `{default}`."] if default is not None else []) + rest + out += [" " * (i > 0) + t + ("\\" if i < len(lines) - 1 else "") for i, t in enumerate(lines)] + else: + out += [head + "\\", " Default:", "", " ```yaml"] indent = min(len(b) - len(b.lstrip()) for b in block if b.strip()) out += [" " + b[indent:] for b in block if b.strip()] out.append(" ```") - if limits: - out.append(" Allowed: " + "; ".join(limits) + ".") - if paragraph: - out.append(" " + paragraph) + if rest: + out += [""] + [" " + t + ("\\" if i < len(rest) - 1 else "") for i, t in enumerate(rest)] if example: out += ["", " ```yaml", *[" " + e for e in example], " ```"] out.append("") - return "\n".join(out).rstrip() + "\n" + return out def main():