docs: infrastructure roles startup, secret namespace and per-cluster …

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

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