Add CRD validation (#599)

* add CRD manifests with validation
* update documentation
* patroni slots is not an array but a nested hash map
* make deps call tools
* cover validation in docs and export it in crds.go
* add toggle to disable creation of CRD validation and document it
* use templated service account also for CRD-configured helm deployment

docs/administrator.md

@@ -3,6 +3,30 @@
 Learn how to configure and manage the Postgres Operator in your Kubernetes (K8s)
 environment.
 
+## CRD Validation
+
+[CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
+will be registered with schema validation by default when the operator is
+deployed. The `OperatorConfiguration` CRD will only get created if the
+`POSTGRES_OPERATOR_CONFIGURATION_OBJECT` [environment variable](../manifests/postgres-operator.yaml#L36)
+in the deployment yaml is set and not empty.
+
+When submitting manifests of [`postgresql`](../manifests/postgresql.crd.yaml) or
+[`OperatorConfiguration`](../manifests/operatorconfiguration.crd.yaml) custom
+resources with kubectl, validation can be bypassed with `--validate=false`. The
+operator can also be configured to not register CRDs with validation on `ADD` or
+`UPDATE` events. Running instances are not affected when enabling the validation
+afterwards unless the manifests is not changed then. Note, that the provided CRD
+manifests contain the validation for users to understand what schema is
+enforced.
+
+Once the validation is enabled it can only be disabled manually by editing or
+patching the CRD manifest:
+
+```bash
+zk8 patch crd postgresqls.acid.zalan.do -p '{"spec":{"validation": null}}'
+```
+
 ## Namespaces
 
 ### Select the namespace to deploy to
@@ -32,7 +56,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#L49).
 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 "`*`".
 
@@ -115,7 +139,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 +160,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 +187,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 +200,22 @@ data:
   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` 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:
+Likewise, when using an OperatorConfiguration resource add:
 
 ```yaml
-apiVersion: v1
-kind: ConfigMap
+apiVersion: "acid.zalan.do/v1"
+kind: OperatorConfiguration
 metadata:
-  name: postgres-operator
-data:
-  enable_pod_antiaffinity: "true"
-  pod_antiaffinity_topology_key: "failure-domain.beta.kubernetes.io/zone"
+  name: postgresql-configuration
+configuration:
+  kubernetes:
+    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 +320,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 +366,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.