From abaae95bac540f76c04bfedf730b3e758910f0a2 Mon Sep 17 00:00:00 2001 From: Felix Kunde Date: Wed, 23 Oct 2019 15:06:07 +0200 Subject: [PATCH] update documentation --- docs/administrator.md | 61 ++++++++++++++++++++------- docs/developer.md | 3 +- docs/quickstart.md | 7 +-- docs/reference/operator_parameters.md | 6 +-- 4 files changed, 54 insertions(+), 23 deletions(-) diff --git a/docs/administrator.md b/docs/administrator.md index ab5368e7d..9b0602b20 100644 --- a/docs/administrator.md +++ b/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 -`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 +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. diff --git a/docs/developer.md b/docs/developer.md index 490217362..6442e9154 100644 --- a/docs/developer.md +++ b/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 - diff --git a/docs/quickstart.md b/docs/quickstart.md index 500d4db30..ba5776b9a 100644 --- a/docs/quickstart.md +++ b/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) - -it can be used with kubectl 1.14 or newer as easy as: +manifest that [combines the mentioned resources](../manifests/kustomization.yaml) +(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 diff --git a/docs/reference/operator_parameters.md b/docs/reference/operator_parameters.md index a024aad1f..5b9b70f61 100644 --- a/docs/reference/operator_parameters.md +++ b/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