From 2c26e9858701ce6e679590e4de6cf0c3cf60ec55 Mon Sep 17 00:00:00 2001 From: Yves Galante Date: Sat, 7 Nov 2026 09:55:25 +0100 Subject: [PATCH] docs: infrastructure roles startup, secret namespace and per-cluster secret Document behaviour only visible in the code: the roles are read at operator start, the default secret namespace differs between the CRD and the ConfigMap configuration, defaultuservalue / defaultrolevalue, and the per-cluster credentials secret usable by sidecars or exporters. --- docs/reference/operator_parameters.md | 5 ++++- docs/user.md | 27 +++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/reference/operator_parameters.md b/docs/reference/operator_parameters.md index 44a015cee..e2295bf98 100644 --- a/docs/reference/operator_parameters.md +++ b/docs/reference/operator_parameters.md @@ -455,7 +455,10 @@ configuration they are grouped under the `kubernetes` key. array of infrastructure role definitions which reference existing secrets and specify the key names from which user name, password and role membership are extracted. For the ConfigMap this has to be a string which allows - referencing only one infrastructure roles secret. The default is empty. + referencing only one infrastructure roles secret, e.g. + `secretname:namespace/name,userkey:user,passwordkey:password,rolekey:inrole`. + Read at operator start only, see [infrastructure roles](../user.md#infrastructure-roles). + The default is empty. * **inherited_annotations** list of annotation keys that can be inherited from the cluster manifest, and diff --git a/docs/user.md b/docs/user.md index cbca284f7..66974c0e6 100644 --- a/docs/user.md +++ b/docs/user.md @@ -289,6 +289,33 @@ See [infrastructure roles secret](https://github.com/zalando/postgres-operator/b and [infrastructure roles configmap](https://github.com/zalando/postgres-operator/blob/master/manifests/infrastructure-roles-configmap.yaml) for the examples. +#### Good to know + +* Infrastructure roles are read when the operator starts. Restart the operator + after creating or changing the referenced secrets, e.g. to rotate a password. +* A `secretname` without namespace refers to the operator namespace in the CRD + configuration, but to the `default` namespace in the ConfigMap. Use the + `namespace/name` format to be explicit. +* `defaultuservalue` and `defaultrolevalue` set the user name and role + membership when the secret does not contain them, so the secret only needs + the password. +* For each cluster, the operator stores the role credentials in a secret in + the cluster namespace, named after `secret_name_template`, and updates it + when the password changes. Sidecars or exporters running next to the cluster + can read it. + +Example of a monitoring role for the [postgres_exporter](https://github.com/prometheus-community/postgres_exporter), +whose password is the only key of the secret: + +```yaml +# ConfigMap +infrastructure_roles_secrets: "secretname:postgres-operator/monitoring-role,passwordkey:password,defaultuservalue:postgres_exporter,defaultrolevalue:pg_monitor" +``` + +The exporter of the cluster `acid-minimal-cluster` then reads the user name +and password from the `postgres-exporter.acid-minimal-cluster.credentials.postgresql.acid.zalan.do` +secret, with the default `secret_name_template`. + ### Teams API roles These roles are meant for database activity of human users. It's possible to