update documentation

docs/administrator.md

@@ -32,7 +32,7 @@ By default, the operator watches the namespace it is deployed to. You can
 change this by setting the `WATCHED_NAMESPACE` var in the `env` section of the
 [operator deployment](../manifests/postgres-operator.yaml) manifest or by
 altering the `watched_namespace` field in the operator
-[ConfigMap](../manifests/configmap.yaml#L79).
+[configuration](../manifests/postgresql-operator-default-configuration.yaml#L45).
 In the case both are set, the env var takes the precedence. To make the
 operator listen to all namespaces, explicitly set the field/env var to "`*`".
 
@@ -79,7 +79,8 @@ to function under access control restrictions. To deploy the operator with this
 RBAC policy use:
 
 ```bash
-kubectl create -f manifests/configmap.yaml
+kubectl create -f manifests/operatorconfiguration.crd.yaml
+kubectl create -f manifests/postgresql-operator-default-configuration
 kubectl create -f manifests/operator-service-account-rbac.yaml
 kubectl create -f manifests/postgres-operator.yaml
 kubectl create -f manifests/minimal-postgres-manifest.yaml
@@ -115,7 +116,7 @@ that are aggregated into the K8s [default roles](https://kubernetes.io/docs/refe
 
 To ensure Postgres pods are running on nodes without any other application pods,
 you can use [taints and tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
-and configure the required toleration in the operator ConfigMap.
+and configure the required toleration in the operator configuration.
 
 As an example you can set following node taint:
 
@@ -136,6 +137,21 @@ data:
   ...
 ```
 
+For an OperatorConfiguration resource the toleration should be defined like
+this:
+
+```yaml
+apiVersion: "acid.zalan.do/v1"
+kind: OperatorConfiguration
+metadata:
+  name: postgresql-configuration
+configuration:
+  kubernetes:
+    toleration:
+      postgres: "key:postgres,operator:Exists,effect:NoSchedule"
+  ...
+```
+
 Note that the K8s version 1.13 brings [taint-based eviction](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/#taint-based-evictions)
 to the beta stage and enables it by default. Postgres pods by default receive
 tolerations for `unreachable` and `noExecute` taints with the timeout of `5m`.
@@ -148,7 +164,7 @@ completely, specify the toleration by leaving out the `tolerationSeconds` value
 
 To ensure Postgres pods are running on different topologies, you can use
 [pod anti affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/)
-and configure the required topology in the operator ConfigMap.
+and configure the required topology in the operator configuration.
 
 Enable pod anti affinity by adding following line to the operator ConfigMap:
 
@@ -161,21 +177,22 @@ data:
   enable_pod_antiaffinity: "true"
 ```
 
-By default the topology key for the pod anti affinity is set to
+Likewise, when using an OperatorConfiguration resource add:
-`kubernetes.io/hostname`, you can set another topology key e.g.
-`failure-domain.beta.kubernetes.io/zone` by adding following line to the
-operator ConfigMap, see [built-in node labels](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#interlude-built-in-node-labels) for available topology keys:
 
 ```yaml
-apiVersion: v1
+apiVersion: "acid.zalan.do/v1"
-kind: ConfigMap
+kind: OperatorConfiguration
 metadata:
-  name: postgres-operator
+  name: postgresql-configuration
-data:
+configuration:
-  enable_pod_antiaffinity: "true"
+  kubernetes:
-  pod_antiaffinity_topology_key: "failure-domain.beta.kubernetes.io/zone"
+    enable_pod_antiaffinity: true
 ```
 
+By default the topology key for the pod anti affinity is set to
+`kubernetes.io/hostname`, you can set another topology key e.g.
+`failure-domain.beta.kubernetes.io/zone`. See [built-in node labels](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#interlude-built-in-node-labels) for available topology keys.
+
 ## Pod Disruption Budget
 
 By default the operator uses a PodDisruptionBudget (PDB) to protect the cluster
@@ -280,6 +297,20 @@ data:
   ...
 ```
 
+**OperatorConfiguration**
+
+```yaml
+apiVersion: "acid.zalan.do/v1"
+kind: OperatorConfiguration
+metadata:
+  name: postgresql-operator-configuration
+configuration:
+  kubernetes:
+    # referencing config map with custom settings
+    pod_environment_configmap: postgres-pod-config
+    ...
+```
+
 **referenced ConfigMap `postgres-pod-config`**
 
 ```yaml
@@ -312,7 +343,7 @@ services: one for the master pod and one for replica pods. To expose these
 services to an outer network, one can attach load balancers to them by setting
 `enableMasterLoadBalancer` and/or `enableReplicaLoadBalancer` to `true` in the
 cluster manifest. In the case any of these variables are omitted from the
-manifest, the operator configmap's settings `enable_master_load_balancer` and
+manifest, the operator configuration settings `enable_master_load_balancer` and
 `enable_replica_load_balancer` apply. Note that the operator settings affect
 all Postgresql services running in all namespaces watched by the operator.
 

docs/developer.md

@@ -80,7 +80,8 @@ manifest but replace the version and tag. Don't forget to also apply
 configuration and RBAC manifests first, e.g.:
 
 ```bash
-kubectl create -f manifests/configmap.yaml
+kubectl create -f manifests/operatorconfiguration.crd.yaml
+kubectl create -f manifests/postgresql-operator-default-configuration
 kubectl create -f manifests/operator-service-account-rbac.yaml
 sed -e "s/\(image\:.*\:\).*$/\1$TAG/" manifests/postgres-operator.yaml | kubectl create  -f -
 

docs/quickstart.md

@@ -49,14 +49,15 @@ git clone https://github.com/zalando/postgres-operator.git
 cd postgres-operator
 
 # apply the manifests in the following order
-kubectl create -f manifests/configmap.yaml  # configuration
+kubectl create -f manifests/operatorconfiguration.crd.yaml  # configuration CRD
+kubectl create -f manifests/postgresql-operator-default-configuration  # default configuration
 kubectl create -f manifests/operator-service-account-rbac.yaml  # identity and permissions
 kubectl create -f manifests/postgres-operator.yaml  # deployment
 ```
 
 There is a [Kustomization](https://github.com/kubernetes-sigs/kustomize)
-manifest that [combines the mentioned resources](../manifests/kustomization.yaml) -
+manifest that [combines the mentioned resources](../manifests/kustomization.yaml)
-it can be used with kubectl 1.14 or newer as easy as:
+(except for the CRD) - it can be used with kubectl 1.14 or newer as easy as:
 
 ```bash
 kubectl apply -k github.com/zalando/postgres-operator/manifests

docs/reference/operator_parameters.md

@@ -29,15 +29,13 @@ configuration.
 
   To test the CRD-based configuration locally, use the following
   ```bash
+  kubectl create -f manifests/operatorconfiguration.crd.yaml # registers the CRD
   kubectl create -f manifests/operator-service-account-rbac.yaml
   kubectl create -f manifests/postgres-operator.yaml # set the env var as mentioned above
   kubectl create -f manifests/postgresql-operator-default-configuration.yaml
   kubectl get operatorconfigurations postgresql-operator-default-configuration -o yaml
   ```
-  Note that the operator first attempts to register the CRD of the
+
-  `OperatorConfiguration` and then waits for an instance to be created. In
-  between these two event the operator pod may be failing since it cannot fetch
-  the not-yet-existing `OperatorConfiguration` instance.
 
 The CRD-based configuration is more powerful than the one based on ConfigMaps
 and should be used unless there is a compatibility requirement to use an already