From f6875b220a6e3f57cbc1d0102bce64b02e053361 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Thu, 19 Nov 2026 13:09:11 -0700 Subject: [PATCH 1/3] Values reference generated from values.yaml and the schema; bad values refused (K-C12) - tools/values-reference.py writes charts/inbuxa/VALUES.md: every value, its default, its type and what the schema allows, with the comment from values.yaml. Standard library only. CI (check.sh) fails when the committed copy is out of date; the job installs python3-minimal. - The schema checks resources (requests and limits of cpu, memory and ephemeral-storage, as quantities) and annotation, label and node-selector maps (strings only). - tools/bad-values: values the chart must refuse, each with the reason the refusal has to give. check.sh renders each with helm template, as an install does: helm lint passes over a template's own refusal. --- .gitea/workflows/ci.yml | 5 +- CHANGELOG.md | 6 + charts/inbuxa/VALUES.md | 931 +++++++++++++++++++ charts/inbuxa/values.schema.json | 125 ++- tools/bad-values/backup-url-not-s3.yaml | 3 + tools/bad-values/backup-without-bucket.yaml | 3 + tools/bad-values/core-two.yaml | 4 + tools/bad-values/label-not-string.yaml | 5 + tools/bad-values/listener-port-range.yaml | 3 + tools/bad-values/otlp-protocol.yaml | 4 + tools/bad-values/replicas-negative.yaml | 4 + tools/bad-values/resources-bad-quantity.yaml | 4 + tools/bad-values/resources-unknown-key.yaml | 4 + tools/bad-values/schedule-empty.yaml | 4 + tools/bad-values/unknown-nested-key.yaml | 4 + tools/bad-values/wrong-type.yaml | 3 + tools/check.sh | 21 + tools/values-reference.py | 213 +++++ 18 files changed, 1330 insertions(+), 16 deletions(-) create mode 100644 charts/inbuxa/VALUES.md create mode 100644 tools/bad-values/backup-url-not-s3.yaml create mode 100644 tools/bad-values/backup-without-bucket.yaml create mode 100644 tools/bad-values/core-two.yaml create mode 100644 tools/bad-values/label-not-string.yaml create mode 100644 tools/bad-values/listener-port-range.yaml create mode 100644 tools/bad-values/otlp-protocol.yaml create mode 100644 tools/bad-values/replicas-negative.yaml create mode 100644 tools/bad-values/resources-bad-quantity.yaml create mode 100644 tools/bad-values/resources-unknown-key.yaml create mode 100644 tools/bad-values/schedule-empty.yaml create mode 100644 tools/bad-values/unknown-nested-key.yaml create mode 100644 tools/bad-values/wrong-type.yaml create mode 100755 tools/values-reference.py diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 8a6c022..cd971bd 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -3,7 +3,8 @@ # # The chart's checks on every pull request and on main: helm lint under # Helm 4 and Helm 3, the values schema, kubeconform against the three newest -# Kubernetes minors, kube-linter, and helm-unittest. All of it is +# Kubernetes minors, kube-linter, helm-unittest, bad values refused, and +# the values reference (charts/inbuxa/VALUES.md) current. All of it is # tools/check.sh, so a contributor runs exactly this before pushing. # # Installs on a real cluster are the lab's job (inbuxa-k8s-lab), not this @@ -38,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 >/dev/null + apt-get install -y -qq --no-install-recommends ca-certificates curl git python3-minimal >/dev/null - uses: coffey-labs/actions/checkout@fab0c4d45e0162963965f1555df27b7bed5e20ec - run: tools/install-tools.sh - run: tools/check.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 91dee26..c27c31d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,12 @@ 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`. +- `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 + checks resources (requests and limits as quantities) and annotation and + node-selector maps (strings) too, and `tools/bad-values` holds values the + chart must refuse before anything is applied, each for a stated reason. - Backups and store checks on a schedule. `server.backup` exports the whole store nightly to an S3 bucket (`inbuxa --export s3://...`), streamed while the server runs, into a folder per export with `export.json` diff --git a/charts/inbuxa/VALUES.md b/charts/inbuxa/VALUES.md new file mode 100644 index 0000000..87d3476 --- /dev/null +++ b/charts/inbuxa/VALUES.md @@ -0,0 +1,931 @@ + + +# 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. + +- **`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])?)?$`. + Overrides the whole name (release name plus chart name). + +- **`imagePullSecrets`** (list of object) + Default: `[]`. + +## `server` + +### `server.image` + +- **`server.image.repository`** (string) + Default: `ghcr.io/inbuxa/inbuxa-server`. + Allowed: at least 1 character. + +- **`server.image.tag`** (string) + Default: `""`. + Defaults to the chart's appVersion + +- **`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`. + Allowed: one of `"Always"`, `"IfNotPresent"`, `"Never"`. + +- **`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 + "@type": PostgreSql + host: pg-rw.data.svc + port: 5432 + database: inbuxa + authUsername: inbuxa + authSecret: {"@type": File, filePath: /etc/inbuxa/secrets/pg-password} + useTls: true + ``` + +- **`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 + - secretName: inbuxa-data + items: [{key: pg-password, path: pg-password}] + ``` + +### `server.seed` + +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) + Default: `false`. + +- **`server.seed.request`** (object) + Default: `{}`. + The seed, as values + +- **`server.seed.existingConfigMap`** (string) + Default: `""`. + Or an existing ConfigMap with it under the key seed.json + +- **`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`. + Allowed: at least 30. + +- **`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) + Default: `true`. + +- **`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`. + 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`. + Allowed: at least 60. + +- **`server.upgrade.resources`** (object) + Default: `{}`. + Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +- **`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: `[]`. + 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`. + 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. + 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. + 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. + 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. + 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. + 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. + Plain HTTP, which the probes use, so it can't be left out. + +### `server.groups` + +The server's role groups, each a Deployment. INBUXA_ROLE names a role (a ClusterRole in the server's registry) that says which background tasks the group runs; an empty role runs them all. + +#### `server.groups.front` + +Client protocols, web and JMAP; no outbound delivery, no scheduler + +- **`server.groups.front.enabled`** (boolean) + Default: `true`. + +- **`server.groups.front.replicas`** (integer) + Default: `2`. + Allowed: at least 0. + +- **`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: `{}`. + Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +- **`server.groups.front.nodeSelector`** (map of string) + Default: `{}`. + +- **`server.groups.front.tolerations`** (list of object) + Default: `[]`. + +- **`server.groups.front.affinity`** (object) + Default: `{}`. + +- **`server.groups.front.podAnnotations`** (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) + 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) + Default: `true`. + +- **`server.groups.mta.replicas`** (integer) + Default: `2`. + Allowed: at least 0. + +- **`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: `{}`. + Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +- **`server.groups.mta.nodeSelector`** (map of string) + Default: `{}`. + +- **`server.groups.mta.tolerations`** (list of object) + Default: `[]`. + +- **`server.groups.mta.affinity`** (object) + Default: `{}`. + +- **`server.groups.mta.podAnnotations`** (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) + 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) + Default: `true`. + +- **`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: `""`. + The registry ClusterRole the group's pods run as; empty runs every task. + +- **`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) + Default: `{}`. + +- **`server.groups.core.tolerations`** (list of object) + Default: `[]`. + +- **`server.groups.core.affinity`** (object) + Default: `{}`. + +- **`server.groups.core.podAnnotations`** (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) + 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) + Default: `[]`. + +- **`server.egress.checkUrl`** (string) + Default: `""`. + Allowed: matching `^(https?://\S+)?$`. + +### `server.resources` + +Used for every group that sets no resources of its own + +#### `server.resources.requests` + +- **`server.resources.requests.cpu`** (string or number) + Default: `250m`. + +- **`server.resources.requests.memory`** (string or number) + Default: `512Mi`. + +#### `server.resources.limits` + +- **`server.resources.limits.cpu`** (string or number) + Default: `"2"`. + +- **`server.resources.limits.memory`** (string or number) + Default: `2Gi`. + +- **`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`. + Allowed: one of `"DoNotSchedule"`, `"ScheduleAnyway"`, `"off"`. + +- **`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) + Default: `true`. + +- **`server.podDisruptionBudget.maxUnavailable`** (integer) + Default: `1`. + Allowed: at least 1. + +### `server.services` + +#### `server.services.http` + +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`. + Allowed: one of `"ClusterIP"`, `"NodePort"`, `"LoadBalancer"`. + +- **`server.services.http.annotations`** (map of string) + Default: `{}`. + +- **`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) + Default: `true`. + +- **`server.services.mail.type`** (string) + Default: `LoadBalancer`. + Allowed: one of `"LoadBalancer"`, `"NodePort"`, `"ClusterIP"`. + +- **`server.services.mail.externalTrafficPolicy`** (string) + Default: `Local`. + Allowed: one of `"Local"`, `"Cluster"`. + +- **`server.services.mail.loadBalancerClass`** (string) + Default: `""`. + +- **`server.services.mail.loadBalancerIP`** (string) + Default: `""`. + +- **`server.services.mail.annotations`** (map of string) + Default: `{}`. + +- **`server.services.mail.groups`** (array) + Default: `[front, mta]`. + +#### `server.services.mail.ports` + +- **`server.services.mail.ports.smtp`** (integer) + Default: `25`. + Allowed: at least 0; at most 65535. + +- **`server.services.mail.ports.submissions`** (integer) + Default: `465`. + Allowed: at least 0; at most 65535. + +- **`server.services.mail.ports.imaps`** (integer) + Default: `993`. + Allowed: at least 0; at most 65535. + +- **`server.services.mail.ports.pop3s`** (integer) + Default: `995`. + Allowed: at least 0; at most 65535. + +- **`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) + Default: `false`. + +- **`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. + 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. + 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. + 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. + 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. + 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) + Default: `false`. + +- **`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) + Default: `""`. + +- **`server.backup.url`** (string) + Default: `""`. + Allowed: matching `^$|^s3://[^/]+(/.*)?$`. + s3://bucket/prefix + +- **`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`. + Allowed: at least 1 character. + +- **`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) + Default: `""`. + +- **`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. + Tries per night: a failed try leaves an unfinished folder behind + +- **`server.backup.successfulJobsHistoryLimit`** (integer) + Default: `3`. + Allowed: at least 0. + +- **`server.backup.failedJobsHistoryLimit`** (integer) + Default: `3`. + Allowed: at least 0. + +- **`server.backup.resources`** (object) + Default: `{}`. + Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +### `server.storeCheck` + +Store checks on a schedule (`inbuxa --store-check`): quick finds blobs the store names but doesn't have; full also reads every blob and checks its hash, paced to 20 MiB/s. Each is saved with the console's other store checks, and a check that finds problems fails its Job (exit 3), so kube-state-metrics, and the alerts, see it. Needs server 27.1-rc.34. + +#### `server.storeCheck.quick` + +- **`server.storeCheck.quick.enabled`** (boolean) + Default: `false`. + +- **`server.storeCheck.quick.schedule`** (string) + Default: `"15 3 * * *"`. + Allowed: at least 1 character. + +- **`server.storeCheck.quick.timeoutSeconds`** (integer) + Default: `21600`. + Allowed: at least 60. + +#### `server.storeCheck.full` + +- **`server.storeCheck.full.enabled`** (boolean) + Default: `false`. + +- **`server.storeCheck.full.schedule`** (string) + Default: `"15 4 * * 0"`. + Allowed: at least 1 character. + +- **`server.storeCheck.full.timeoutSeconds`** (integer) + Default: `172800`. + Allowed: at least 60. + +- **`server.storeCheck.timeZone`** (string) + Default: `""`. + +- **`server.storeCheck.successfulJobsHistoryLimit`** (integer) + Default: `3`. + Allowed: at least 0. + +- **`server.storeCheck.failedJobsHistoryLimit`** (integer) + Default: `3`. + Allowed: at least 0. + +- **`server.storeCheck.resources`** (object) + Default: `{}`. + Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +### `server.metrics` + +Metrics, for Prometheus or an OpenTelemetry collector. Needs server 27.1-rc.34; an older server ignores these settings. + +#### `server.metrics.prometheus` + +- **`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`. + Allowed: matching `^[^:\s]+$`. + +- **`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) + Default: `false`. + +- **`server.metrics.prometheus.serviceMonitor.interval`** (string) + Default: `30s`. + Allowed: matching `^[0-9]+(ms|s|m|h)$`. + +- **`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) + Default: `false`. + +- **`server.metrics.prometheus.rules.labels`** (map of string) + Default: `{}`. + +- **`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. + Messages in the queue + +- **`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. + Share of deliveries that bounce, over half an hour, once at least deliveryFailureMinimum have + +- **`server.metrics.prometheus.rules.deliveryFailureMinimum`** (integer) + Default: `10`. + Allowed: at least 1. + +- **`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. + 99th-percentile data store read or write, in milliseconds + +- **`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) + Default: `false`. + +- **`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"`. + http/protobuf or grpc + +- **`server.metrics.otlp.intervalSeconds`** (integer) + Default: `60`. + Allowed: at least 1. + +- **`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) + Default: `false`. + +- **`server.metrics.grafanaDashboard.labels`** (map of string) + The label the sidecar looks for + +- **`server.metrics.grafanaDashboard.labels.grafana_dashboard`** (string) + Default: `"1"`. + +- **`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) + Default: `false`. + +### `webmail.image` + +- **`webmail.image.repository`** (string) + Default: `ghcr.io/inbuxa/inbuxa-webmail`. + Allowed: at least 1 character. + +- **`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: `""`. + Allowed: matching `^(sha256:[0-9a-f]{64})?$`. + +- **`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]+)?/?)?$`. + Where browsers reach it, as https://host. Required. The server registers it as an OAuth client with this address. + +- **`webmail.replicas`** (integer) + Default: `2`. + Allowed: at least 1. + +- **`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`. + 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: `[]`. + 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) + Default: `false`. + +- **`webmail.autoscaling.minReplicas`** (integer) + Default: `2`. + Allowed: at least 1. + +- **`webmail.autoscaling.maxReplicas`** (integer) + Default: `6`. + Allowed: at least 1. + +- **`webmail.autoscaling.targetCPUUtilizationPercentage`** (integer) + Default: `70`. + Allowed: at least 1; at most 100. + +### `webmail.resources` + +Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +#### `webmail.resources.requests` + +- **`webmail.resources.requests.cpu`** (string or number) + Default: `100m`. + +- **`webmail.resources.requests.memory`** (string or number) + Default: `128Mi`. + +#### `webmail.resources.limits` + +- **`webmail.resources.limits.cpu`** (string or number) + Default: `"1"`. + +- **`webmail.resources.limits.memory`** (string or number) + Default: `512Mi`. + +### `webmail.podDisruptionBudget` + +- **`webmail.podDisruptionBudget.enabled`** (boolean) + Default: `true`. + +- **`webmail.podDisruptionBudget.maxUnavailable`** (integer or string) + Default: `1`. + +- **`webmail.nodeSelector`** (map of string) + Default: `{}`. + +- **`webmail.tolerations`** (array) + Default: `[]`. + +- **`webmail.affinity`** (object) + Default: `{}`. + +- **`webmail.podAnnotations`** (map of string) + Default: `{}`. + +- **`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) + Default: `false`. + +### `console.image` + +- **`console.image.repository`** (string) + Default: `ghcr.io/inbuxa/inbuxa-admin`. + Allowed: at least 1 character. + +- **`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: `""`. + Allowed: matching `^(sha256:[0-9a-f]{64})?$`. + +- **`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]+)?/?)?$`. + 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`. + Allowed: at least 1. + +### `console.autoscaling` + +- **`console.autoscaling.enabled`** (boolean) + Default: `false`. + +- **`console.autoscaling.minReplicas`** (integer) + Default: `2`. + Allowed: at least 1. + +- **`console.autoscaling.maxReplicas`** (integer) + Default: `4`. + Allowed: at least 1. + +- **`console.autoscaling.targetCPUUtilizationPercentage`** (integer) + Default: `70`. + Allowed: at least 1; at most 100. + +### `console.resources` + +Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +#### `console.resources.requests` + +- **`console.resources.requests.cpu`** (string or number) + Default: `20m`. + +- **`console.resources.requests.memory`** (string or number) + Default: `32Mi`. + +#### `console.resources.limits` + +- **`console.resources.limits.cpu`** (string or number) + Default: `500m`. + +- **`console.resources.limits.memory`** (string or number) + Default: `128Mi`. + +### `console.podDisruptionBudget` + +- **`console.podDisruptionBudget.enabled`** (boolean) + Default: `true`. + +- **`console.podDisruptionBudget.maxUnavailable`** (integer or string) + Default: `1`. + +- **`console.nodeSelector`** (map of string) + Default: `{}`. + +- **`console.tolerations`** (array) + Default: `[]`. + +- **`console.affinity`** (object) + Default: `{}`. + +- **`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) + Default: `true`. + +- **`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 + - namespaceSelector: + matchLabels: {kubernetes.io/metadata.name: ingress-nginx} + ``` + +- **`networkPolicy.metricsFrom`** (list of object) + Default: `[]`. + Prometheus, when httpFrom is set: it scrapes the server pods' http port. As NetworkPolicy peers, e.g. + + ```yaml + - namespaceSelector: + matchLabels: {kubernetes.io/metadata.name: monitoring} + ``` + +- **`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`. + The webmail fetches remote images in mail and subscribed calendars over HTTP and HTTPS. Off: only the server. + +## `routes` + +Routes from outside to the server's publicUrl, the webmail's and the console's, each by its host name. Gateway API where the cluster has it; an Ingress where it doesn't. TLS is the Gateway's or the Ingress's. + +### `routes.gateway` + +- **`routes.gateway.enabled`** (boolean) + Default: `false`. + +- **`routes.gateway.parentRefs`** (array) + Default: `[]`. + The Gateway listeners to attach to, e.g. [{name: public, namespace: gateway}] + +- **`routes.gateway.annotations`** (map of string) + Default: `{}`. + +### `routes.ingress` + +- **`routes.ingress.enabled`** (boolean) + Default: `false`. + +- **`routes.ingress.className`** (string) + Default: `""`. + +- **`routes.ingress.annotations`** (map of string) + 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/values.schema.json b/charts/inbuxa/values.schema.json index ec63d4c..f615db4 100644 --- a/charts/inbuxa/values.schema.json +++ b/charts/inbuxa/values.schema.json @@ -40,7 +40,7 @@ "type": "string" }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" }, "nodeSelector": { "type": "object", @@ -142,6 +142,103 @@ } } } + }, + "resources": { + "description": "Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi).", + "type": "object", + "additionalProperties": false, + "properties": { + "requests": { + "type": "object", + "additionalProperties": false, + "properties": { + "cpu": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + }, + "memory": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + }, + "ephemeral-storage": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + } + } + }, + "limits": { + "type": "object", + "additionalProperties": false, + "properties": { + "cpu": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + }, + "memory": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + }, + "ephemeral-storage": { + "anyOf": [ + { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei|e[0-9]+)?$" + }, + { + "type": "number", + "minimum": 0 + } + ] + } + } + } + } + }, + "stringMap": { + "type": "object", + "additionalProperties": { + "type": "string" + } } }, "properties": { @@ -242,7 +339,7 @@ "minimum": 30 }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" } } }, @@ -315,7 +412,7 @@ "minimum": 60 }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" } } }, @@ -403,7 +500,7 @@ } }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" }, "terminationGracePeriodSeconds": { "type": "integer", @@ -742,7 +839,7 @@ "minimum": 0 }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" } } }, @@ -796,7 +893,7 @@ "minimum": 0 }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" } } } @@ -864,7 +961,7 @@ } }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" }, "podDisruptionBudget": { "type": "object", @@ -882,7 +979,7 @@ } }, "nodeSelector": { - "type": "object" + "$ref": "#/definitions/stringMap" }, "tolerations": { "type": "array" @@ -891,7 +988,7 @@ "type": "object" }, "podAnnotations": { - "type": "object" + "$ref": "#/definitions/stringMap" }, "existingSecret": { "type": "string" @@ -972,7 +1069,7 @@ } }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" }, "podDisruptionBudget": { "type": "object", @@ -990,7 +1087,7 @@ } }, "nodeSelector": { - "type": "object" + "$ref": "#/definitions/stringMap" }, "tolerations": { "type": "array" @@ -999,7 +1096,7 @@ "type": "object" }, "podAnnotations": { - "type": "object" + "$ref": "#/definitions/stringMap" } } }, @@ -1048,7 +1145,7 @@ "type": "array" }, "annotations": { - "type": "object" + "$ref": "#/definitions/stringMap" } } }, @@ -1063,7 +1160,7 @@ "type": "string" }, "annotations": { - "type": "object" + "$ref": "#/definitions/stringMap" }, "tls": { "type": "array" diff --git a/tools/bad-values/backup-url-not-s3.yaml b/tools/bad-values/backup-url-not-s3.yaml new file mode 100644 index 0000000..5b35f3d --- /dev/null +++ b/tools/bad-values/backup-url-not-s3.yaml @@ -0,0 +1,3 @@ +# refuses: url +server: + backup: {enabled: true, url: "https://backups.example.com/inbuxa"} diff --git a/tools/bad-values/backup-without-bucket.yaml b/tools/bad-values/backup-without-bucket.yaml new file mode 100644 index 0000000..eaa9b6c --- /dev/null +++ b/tools/bad-values/backup-without-bucket.yaml @@ -0,0 +1,3 @@ +# refuses: name the bucket +server: + backup: {enabled: true} diff --git a/tools/bad-values/core-two.yaml b/tools/bad-values/core-two.yaml new file mode 100644 index 0000000..dea49a5 --- /dev/null +++ b/tools/bad-values/core-two.yaml @@ -0,0 +1,4 @@ +# refuses: replicas.*(maximum|less than or equal) +server: + groups: + core: {replicas: 2} diff --git a/tools/bad-values/label-not-string.yaml b/tools/bad-values/label-not-string.yaml new file mode 100644 index 0000000..e8f88b6 --- /dev/null +++ b/tools/bad-values/label-not-string.yaml @@ -0,0 +1,5 @@ +# refuses: release.*string|string.*release|labels +server: + metrics: + prometheus: + serviceMonitor: {labels: {release: 1}} diff --git a/tools/bad-values/listener-port-range.yaml b/tools/bad-values/listener-port-range.yaml new file mode 100644 index 0000000..e4060ae --- /dev/null +++ b/tools/bad-values/listener-port-range.yaml @@ -0,0 +1,3 @@ +# refuses: smtp +server: + listeners: {smtp: 70000} diff --git a/tools/bad-values/otlp-protocol.yaml b/tools/bad-values/otlp-protocol.yaml new file mode 100644 index 0000000..7db64ea --- /dev/null +++ b/tools/bad-values/otlp-protocol.yaml @@ -0,0 +1,4 @@ +# refuses: protocol +server: + metrics: + otlp: {enabled: true, endpoint: "http://otel:4318", protocol: http/json} diff --git a/tools/bad-values/replicas-negative.yaml b/tools/bad-values/replicas-negative.yaml new file mode 100644 index 0000000..2cee80b --- /dev/null +++ b/tools/bad-values/replicas-negative.yaml @@ -0,0 +1,4 @@ +# refuses: replicas.*(minimum|greater than or equal) +server: + groups: + front: {replicas: -1} diff --git a/tools/bad-values/resources-bad-quantity.yaml b/tools/bad-values/resources-bad-quantity.yaml new file mode 100644 index 0000000..9f05cb5 --- /dev/null +++ b/tools/bad-values/resources-bad-quantity.yaml @@ -0,0 +1,4 @@ +# refuses: memory +server: + resources: + requests: {memory: lots} diff --git a/tools/bad-values/resources-unknown-key.yaml b/tools/bad-values/resources-unknown-key.yaml new file mode 100644 index 0000000..bdb0cc0 --- /dev/null +++ b/tools/bad-values/resources-unknown-key.yaml @@ -0,0 +1,4 @@ +# refuses: gpu|additional propert +server: + resources: + requests: {gpu: 1} diff --git a/tools/bad-values/schedule-empty.yaml b/tools/bad-values/schedule-empty.yaml new file mode 100644 index 0000000..3421ce5 --- /dev/null +++ b/tools/bad-values/schedule-empty.yaml @@ -0,0 +1,4 @@ +# refuses: schedule +server: + storeCheck: + quick: {enabled: true, schedule: ""} diff --git a/tools/bad-values/unknown-nested-key.yaml b/tools/bad-values/unknown-nested-key.yaml new file mode 100644 index 0000000..bcf565f --- /dev/null +++ b/tools/bad-values/unknown-nested-key.yaml @@ -0,0 +1,4 @@ +# refuses: replica\b|additional propert +server: + groups: + front: {replica: 2} diff --git a/tools/bad-values/wrong-type.yaml b/tools/bad-values/wrong-type.yaml new file mode 100644 index 0000000..ab35964 --- /dev/null +++ b/tools/bad-values/wrong-type.yaml @@ -0,0 +1,3 @@ +# refuses: stopServers.*(boolean|bool) +server: + upgrade: {stopServers: "yes"} diff --git a/tools/check.sh b/tools/check.sh index 4fd011f..0010543 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -28,6 +28,27 @@ for helm in helm helm3; do done done +step "the values reference is current (tools/values-reference.py)" +python3 tools/values-reference.py --check + +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. +for bad in tools/bad-values/*.yaml; do + want=$(sed -n '1s/^# refuses: //p' "$bad") + [ -n "$want" ] || { echo "!! $bad: no '# refuses:' line" >&2; exit 1; } + if helm template t "$CHART" -f "$CHART/ci/defaults-values.yaml" -f "$bad" >"$OUT/bad.log" 2>&1; then + echo "!! accepted: $bad" >&2 + exit 1 + fi + grep -Eq "$want" "$OUT/bad.log" || { + echo "!! $bad refused, but not for /$want/:" >&2 + cat "$OUT/bad.log" >&2 + exit 1 + } + echo "refused: $(basename "$bad" .yaml)" +done + step "the values schema rejects a key it doesn't know" if helm lint --strict "$CHART" -f "$CHART/ci/defaults-values.yaml" --set notAValue=1 >"$OUT/reject.log" 2>&1; then echo "!! an unknown value was accepted" >&2 diff --git a/tools/values-reference.py b/tools/values-reference.py new file mode 100755 index 0000000..3216c79 --- /dev/null +++ b/tools/values-reference.py @@ -0,0 +1,213 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Coffey Labs LLC +# SPDX-License-Identifier: Apache-2.0 +"""The chart's values reference, charts/inbuxa/VALUES.md, from values.yaml +(each value's comment and default) and values.schema.json (its type and +limits). CI checks the committed copy is current: + + tools/values-reference.py writes it + tools/values-reference.py --check fails when it's out of date + +Standard library only: values.yaml is read line by line, which is how its +comments are kept, and the chart's values.yaml keeps to the plain block +style this reads (one key per line; lists and maps inline, or as a block +under their key). +""" +import json, re, sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +CHART = ROOT / "charts" / "inbuxa" +OUT = CHART / "VALUES.md" +KEY = re.compile(r"^(?P *)(?P[A-Za-z0-9_.\"-]+):(?: (?P.*))?$") + + +def read_values(text): + """[(path, comment lines, default or None for a section, block lines)]""" + entries, stack, comment, current = [], [], [], None + for raw in text.splitlines(): + line = raw.rstrip() + stripped = line.strip() + if stripped.startswith("#"): + comment.append(re.sub(r"^# ?", "", stripped)) + continue + if not stripped: + # A blank line ends a comment that belongs to nothing below it + comment = [] if comment and not entries else comment + continue + m = KEY.match(line) + if m and not stripped.startswith("- "): + indent = len(m["indent"]) + while stack and stack[-1][0] >= indent: + stack.pop() + key = m["key"].strip('"') + stack.append((indent, key)) + path = ".".join(k for _, k in stack) + value = m["value"] + if value is not None and " #" in value: + value = value.split(" #", 1)[0].rstrip() + current = [path, comment, value, []] + entries.append(current) + comment = [] + elif current is not None: + # A list item or a nested line under the last key + current[3].append(raw) + comment = [] + return entries + + +def resolve(schema, root): + while isinstance(schema, dict): + if "$ref" in schema: + schema = dict(walk_ref(root, schema["$ref"]), **{k: v for k, v in schema.items() if k != "$ref"}) + continue + if "allOf" in schema: + merged = {k: v for k, v in schema.items() if k != "allOf"} + for part in schema["allOf"]: + part = resolve(part, root) + for k, v in part.items(): + if k == "properties": + merged.setdefault("properties", {}) + for name, sub in v.items(): + merged["properties"][name] = ( + {"allOf": [merged["properties"][name], sub]} + if name in merged["properties"] else sub + ) + else: + merged.setdefault(k, v) + schema = merged + continue + return schema + return schema or {} + + +def walk_ref(root, ref): + node = root + for part in ref.lstrip("#/").split("/"): + node = node[part] + return node + + +def schema_at(root, path): + node = resolve(root, root) + for key in path.split("."): + props = node.get("properties", {}) + if key in props: + node = resolve(props[key], root) + elif isinstance(node.get("additionalProperties"), dict): + node = resolve(node["additionalProperties"], root) + else: + return {} + return node + + +def describe_type(s): + if "anyOf" in s or "oneOf" in s: + kinds = [] + for alt in s.get("anyOf", s.get("oneOf")): + kinds.append(alt.get("type", "object")) + kind = " or ".join(dict.fromkeys(str(k) for k in kinds)) + else: + kind = s.get("type", "") + if not kind and s.get("enum"): + # An enum alone: the type its values have + names = {bool: "boolean", int: "integer", float: "number", str: "string"} + kind = " or ".join(dict.fromkeys(names.get(type(v), "value") for v in s["enum"])) + if isinstance(kind, list): + kind = " or ".join(kind) + if kind == "array" and isinstance(s.get("items"), dict) and s["items"].get("type"): + kind = f"list of {s['items']['type']}" + if kind == "object" and isinstance(s.get("additionalProperties"), dict) and not s.get("properties"): + kind = f"map of {s['additionalProperties'].get('type', 'object')}" + limits = [] + if "enum" in s: + limits.append("one of " + ", ".join(f"`{json.dumps(v)}`" for v in s["enum"])) + for word, key in (("at least", "minimum"), ("more than", "exclusiveMinimum"), + ("at most", "maximum")): + if key in s: + limits.append(f"{word} {s[key]}") + for word, key in (("at least", "minLength"), ("at most", "maxLength")): + if key in s: + limits.append(f"{word} {s[key]} character" + ("" if s[key] == 1 else "s")) + if "pattern" in s: + limits.append(f"matching `{s['pattern']}`") + return kind, limits + + +def prose(comment): + """The comment's prose, and its indented lines (examples) as a block""" + text, example = [], [] + for line in comment: + if line.startswith(" ") or (example and line.startswith("-")): + example.append(line[2:] if line.startswith(" ") else line) + else: + text.append(line) + paragraph = " ".join(t for t in text if t).strip() + return paragraph, example + + +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.", + "", + ] + for path, comment, value, block in entries: + depth = path.count(".") + s = schema_at(root, path) + kind, limits = describe_type(s) + paragraph, example = prose(comment) + if not paragraph and s.get("description"): + paragraph = s["description"] + is_section = (value is None or value == "") and not block and s.get("properties") + if is_section or (value is None and not block and kind == "object" and s.get("properties")): + out.append(f"{'#' * min(depth + 2, 4)} `{path}`") + out.append("") + if paragraph: + out += [paragraph, ""] + if example: + 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") + 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 example: + out += ["", " ```yaml", *[" " + e for e in example], " ```"] + out.append("") + return "\n".join(out).rstrip() + "\n" + + +def main(): + values = (CHART / "values.yaml").read_text() + schema = json.loads((CHART / "values.schema.json").read_text()) + text = render(read_values(values), schema) + if "--check" in sys.argv[1:]: + if not OUT.exists() or OUT.read_text() != text: + sys.exit(f"{OUT.relative_to(ROOT)} is out of date: run tools/values-reference.py") + print(f"{OUT.relative_to(ROOT)} is current") + return + OUT.write_text(text) + print(f"wrote {OUT.relative_to(ROOT)}") + + +if __name__ == "__main__": + main() -- 2.54.0 From 4264c1bace215e2bac2c68311c02b2d24ef52891 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Thu, 19 Nov 2026 13:48:34 -0700 Subject: [PATCH 2/3] publicUrl: https only, for the server, webmail and console --- CHANGELOG.md | 2 ++ charts/inbuxa/VALUES.md | 6 +++--- charts/inbuxa/templates/_helpers.tpl | 4 ++-- charts/inbuxa/values.schema.json | 6 +++--- tools/bad-values/public-url-http.yaml | 3 +++ tools/bad-values/webmail-url-http.yaml | 6 ++++++ 6 files changed, 19 insertions(+), 8 deletions(-) create mode 100644 tools/bad-values/public-url-http.yaml create mode 100644 tools/bad-values/webmail-url-http.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index c27c31d..b699455 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,6 +84,8 @@ runs, pinned by digest. checks resources (requests and limits as quantities) and annotation and node-selector maps (strings) too, and `tools/bad-values` holds values the chart must refuse before anything is applied, each for a stated reason. +- The server's, the webmail's and the console's `publicUrl` must be + `https://`; plain `http://` is refused. - Backups and store checks on a schedule. `server.backup` exports the whole store nightly to an S3 bucket (`inbuxa --export s3://...`), streamed while the server runs, into a folder per export with `export.json` diff --git a/charts/inbuxa/VALUES.md b/charts/inbuxa/VALUES.md index 87d3476..5cbacd3 100644 --- a/charts/inbuxa/VALUES.md +++ b/charts/inbuxa/VALUES.md @@ -118,7 +118,7 @@ Before an upgrade rolls new pods out, a Job on the new image asks the server wha - **`server.publicUrl`** (string) Default: `""`. - Allowed: matching `^(https?://[^/\s]+)?$`. + 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) @@ -696,7 +696,7 @@ The webmail, signing people in through the server's own page (OAuth). Off by def - **`webmail.publicUrl`** (string) Default: `""`. - Allowed: matching `^(https?://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`. + 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) @@ -802,7 +802,7 @@ INBUXA Admin, the console, served as static files; the browser talks to the serv - **`console.publicUrl`** (string) Default: `""`. - Allowed: matching `^(https?://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$`. + 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) diff --git a/charts/inbuxa/templates/_helpers.tpl b/charts/inbuxa/templates/_helpers.tpl index 74b305d..c89b39c 100644 --- a/charts/inbuxa/templates/_helpers.tpl +++ b/charts/inbuxa/templates/_helpers.tpl @@ -115,14 +115,14 @@ webmail and the console are versioned apart from the server. Call with {{- end -}} {{/* -Checks a front end's publicUrl: required, and http(s)://host with no path. +Checks a front end's publicUrl: required, and https://host with no path. Call with (dict "url" .Values.webmail.publicUrl "name" "webmail"). */}} {{- define "inbuxa.frontEnd.checkUrl" -}} {{- if not .url -}} {{- fail (printf "%s.publicUrl: set where browsers reach the %s, as https://host" .name .name) -}} {{- end -}} -{{- if not (regexMatch "^https?://[A-Za-z0-9.-]+(:[0-9]+)?/?$" .url) -}} +{{- if not (regexMatch "^https://[A-Za-z0-9.-]+(:[0-9]+)?/?$" .url) -}} {{- fail (printf "%s.publicUrl: %q should be https://host, with no path" .name .url) -}} {{- end -}} {{- end -}} diff --git a/charts/inbuxa/values.schema.json b/charts/inbuxa/values.schema.json index f615db4..1a19d3b 100644 --- a/charts/inbuxa/values.schema.json +++ b/charts/inbuxa/values.schema.json @@ -430,7 +430,7 @@ }, "publicUrl": { "type": "string", - "pattern": "^(https?://[^/\\s]+)?$" + "pattern": "^(https://[^/\\s]+)?$" }, "trustedProxies": { "type": "array", @@ -932,7 +932,7 @@ }, "publicUrl": { "type": "string", - "pattern": "^(https?://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$" + "pattern": "^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$" }, "replicas": { "type": "integer", @@ -1040,7 +1040,7 @@ }, "publicUrl": { "type": "string", - "pattern": "^(https?://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$" + "pattern": "^(https://[A-Za-z0-9.-]+(:[0-9]+)?/?)?$" }, "replicas": { "type": "integer", diff --git a/tools/bad-values/public-url-http.yaml b/tools/bad-values/public-url-http.yaml new file mode 100644 index 0000000..beea565 --- /dev/null +++ b/tools/bad-values/public-url-http.yaml @@ -0,0 +1,3 @@ +# refuses: publicUrl +server: + publicUrl: http://mail.example.com diff --git a/tools/bad-values/webmail-url-http.yaml b/tools/bad-values/webmail-url-http.yaml new file mode 100644 index 0000000..cc82e61 --- /dev/null +++ b/tools/bad-values/webmail-url-http.yaml @@ -0,0 +1,6 @@ +# refuses: publicUrl +webmail: + enabled: true + publicUrl: http://webmail.example.com +server: + publicUrl: https://mail.example.com -- 2.54.0 From d9e51f433f3fcf62f536d36f103cc6fc375a30f1 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Thu, 19 Nov 2026 14:09:43 -0700 Subject: [PATCH 3/3] Values reference: server.check from main; its resources checked like the others --- charts/inbuxa/VALUES.md | 62 ++++++++++++++++++++++++++++++++ charts/inbuxa/values.schema.json | 43 +++++++++++++++++----- 2 files changed, 96 insertions(+), 9 deletions(-) diff --git a/charts/inbuxa/VALUES.md b/charts/inbuxa/VALUES.md index 5cbacd3..9e47a5e 100644 --- a/charts/inbuxa/VALUES.md +++ b/charts/inbuxa/VALUES.md @@ -116,6 +116,30 @@ Before an upgrade rolls new pods out, a Job on the new image asks the server wha 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) + Default: `true`. + +#### `server.check.resources` + +Kubernetes resources: requests and limits of cpu, memory and ephemeral-storage, as quantities (100m, 256Mi). + +#### `server.check.resources.requests` + +- **`server.check.resources.requests.cpu`** (string or number) + Default: `50m`. + +- **`server.check.resources.requests.memory`** (string or number) + Default: `64Mi`. + +#### `server.check.resources.limits` + +- **`server.check.resources.limits.memory`** (string or number) + Default: `256Mi`. + - **`server.publicUrl`** (string) Default: `""`. Allowed: matching `^(https://[^/\s]+)?$`. @@ -294,6 +318,44 @@ The addresses outbound mail should leave from: the ones with reverse DNS (PTR) r Default: `""`. Allowed: matching `^(https?://\S+)?$`. +### `server.certificates` + +Certificates for the mail ports (SMTP STARTTLS, submissions, IMAPS, POP3S, ManageSieve). HTTPS from outside is the Gateway's or the Ingress's (routes below). Two ways: - The server's own ACME (an ACME provider set up in the seed or the + +```yaml +console): certificates are kept in the store, and every pod uses them. +DNS-01 needs nothing here. For HTTP-01, name the hosts in acmeHosts: +the routes send their /.well-known/acme-challenge/ to the server. +- TLS Secrets (kubernetes.io/tls), mounted in every server pod and used +as they are: existing ones in secrets, or certManager to have the +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) + 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) + Default: `false`. + +- **`server.certificates.certManager.issuerRef`** (object) + Default: `{}`. + The Issuer or ClusterIssuer, e.g. {name: letsencrypt, kind: ClusterIssuer} + +- **`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: `""`. + Renew this long before expiry; empty is cert-manager's default + ### `server.resources` Used for every group that sets no resources of its own diff --git a/charts/inbuxa/values.schema.json b/charts/inbuxa/values.schema.json index 1a19d3b..e950e8f 100644 --- a/charts/inbuxa/values.schema.json +++ b/charts/inbuxa/values.schema.json @@ -349,28 +349,53 @@ "properties": { "acmeHosts": { "type": "array", - "items": {"type": "string", "pattern": "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$"} + "items": { + "type": "string", + "pattern": "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$" + } }, "secrets": { "type": "array", - "items": {"type": "string", "pattern": "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$"} + "items": { + "type": "string", + "pattern": "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$" + } }, "certManager": { "type": "object", "additionalProperties": false, "properties": { - "enabled": {"type": "boolean"}, + "enabled": { + "type": "boolean" + }, "issuerRef": { "type": "object", "additionalProperties": false, "properties": { - "name": {"type": "string"}, - "kind": {"type": "string", "enum": ["Issuer", "ClusterIssuer"]}, - "group": {"type": "string"} + "name": { + "type": "string" + }, + "kind": { + "type": "string", + "enum": [ + "Issuer", + "ClusterIssuer" + ] + }, + "group": { + "type": "string" + } } }, - "dnsNames": {"type": "array", "items": {"type": "string"}}, - "renewBefore": {"type": "string"} + "dnsNames": { + "type": "array", + "items": { + "type": "string" + } + }, + "renewBefore": { + "type": "string" + } } } } @@ -424,7 +449,7 @@ "type": "boolean" }, "resources": { - "type": "object" + "$ref": "#/definitions/resources" } } }, -- 2.54.0