improve RBAC setup for postgres pods

changed the default name, updated helm chart and docs
allow role to use privileged podsecurtitypolicies

docs/administrator.md

@@ -47,6 +47,12 @@ patching the CRD manifest:
 zk8 patch crd postgresqls.acid.zalan.do -p '{"spec":{"validation": null}}'
 ```
 
+## Non-default cluster domain
+
+If your cluster uses a DNS domain other than the default `cluster.local`, this
+needs to be set in the operator configuration (`cluster_domain` variable). This
+is used by the operator to connect to the clusters after creation.
+
 ## Namespaces
 
 ### Select the namespace to deploy to
@@ -89,30 +95,6 @@ lacks access rights to any of them (except K8s system namespaces like
 'list pods' execute at the cluster scope and fail at the first violation of
 access rights.
 
-The watched namespace also needs to have a (possibly different) service account
-in the case database pods need to talk to the K8s API (e.g. when using
-K8s-native configuration of Patroni). The operator checks that the
-`pod_service_account_name` exists in the target namespace, and, if not, deploys
-there the `pod_service_account_definition` from the operator
-[`Config`](../pkg/util/config/config.go) with the default value of:
-
-```yaml
-apiVersion: v1
-kind: ServiceAccount
-metadata:
- name: operator
-```
-
-In this definition, the operator overwrites the account's name to match
-`pod_service_account_name` and the `default` namespace to match the target
-namespace. The operator performs **no** further syncing of this account.
-
-## Non-default cluster domain
-
-If your cluster uses a DNS domain other than the default `cluster.local`, this
-needs to be set in the operator configuration (`cluster_domain` variable). This
-is used by the operator to connect to the clusters after creation.
-
 ## Role-based access control for the operator
 
 The manifest [`operator-service-account-rbac.yaml`](../manifests/operator-service-account-rbac.yaml)
@@ -127,14 +109,19 @@ kubectl create -f manifests/postgres-operator.yaml
 kubectl create -f manifests/minimal-postgres-manifest.yaml
 ```
 
-### Service account and cluster roles
+### Namespaced service account and roles
 
-Note that the service account is named `zalando-postgres-operator`. You may have
-to change the `service_account_name` in the operator ConfigMap and
-`serviceAccountName` in the `postgres-operator` deployment appropriately. This
-is done intentionally to avoid breaking those setups that already work with the
-default `operator` account. In the future the operator should ideally be run
-under the `zalando-postgres-operator` service account.
+For each namespace the operator watches it creates (or reads) a service account
+to be used by the Postgres Pods when a new cluster is deployed. This service
+account is bound to a namespaced Role via RoleBinding, which are also created
+(or read) by the operator. The name and definitions of these resources can be
+[configured](reference/operator_parameters.md#kubernetes-resources).
+Note, that the operator performs **no** further syncing of them.
+
+Until v1.3.1, RoleBindings pointed to the operator ClusterRole by default. This
+can still be configured but is not recommended as the Postgres Pods should only
+run with the least privileges required for Patroni to work. By default, the
+namespaced RBAC resources are named `postgres-pod`.
 
 ### Give K8s users access to create/list `postgresqls`
 

docs/reference/operator_parameters.md

@@ -152,21 +152,29 @@ configuration they are grouped under the `kubernetes` key.
   service account used by Patroni running on individual Pods to communicate
   with the operator. Required even if native Kubernetes support in Patroni is
   not used, because Patroni keeps pod labels in sync with the instance role.
-  The default is `operator`.
+  The default is `postgres-pod`.
 
 * **pod_service_account_definition**
-  The operator tries to create the pod Service Account in the namespace that
-  doesn't define such an account using the YAML definition provided by this
-  option. If not defined, a simple definition that contains only the name will
-  be used. The default is empty.
+  on Postgres cluster creation the operator tries to create the service account
+  for the Postgres pods if it does not exist in the namespace. The internal
+  default service account definition (defines only the name) can be overwritten
+  with this parameter. Make sure to provide a valid YAML or JSON string. The
+  default is empty.
+
+* **pod_service_account_role_definition**
+  operator will try to create a role in the namespace to be used by pod service
+  account. The internal default definition contains permissions to manage pods
+  and endpoints necessary for Patroni to work. Therefore, when overwriting the
+  definition with this parameter make sure to provide sufficient access rights
+  in a valid YAML/JSON string. The default is empty.
 
 * **pod_service_account_role_binding_definition**
-  This definition must bind pod service account to a role with permission
-  sufficient for the pods to start and for Patroni to access K8s endpoints;
-  service account on its own lacks any such rights starting with K8s v1.8. If
-  not explicitly defined by the user, a simple definition that binds the
-  account to the operator's own 'zalando-postgres-operator' cluster role will
-  be used. The default is empty.
+  the created service account and role are referenced with a role binding. When
+  overwriting its definition with this parameters using a valid YAML/JSON string
+  check that the specified service account and role either exist in the K8s
+  cluster or will be created by the operator. While it's possible to also
+  reference cluster roles, the binding itself can only be of kind `RoleBinding`,
+  not `ClusterRoleBinding`. The default is empty.
 
 * **pod_terminate_grace_period**
   Postgres pods are [terminated forcefully](https://kubernetes.io/docs/concepts/workloads/pods/pod/#termination-of-pods)