extend docs and polish manifest examples (#762)

Author: FxKu

docs/administrator.md

@@ -3,6 +3,26 @@
 Learn how to configure and manage the Postgres Operator in your Kubernetes (K8s)
 environment.
 
+## Minor and major version upgrade
+
+Minor version upgrades for PostgreSQL are handled via updating the Spilo Docker
+image. The operator will carry out a rolling update of Pods which includes a
+switchover (planned failover) of the master to the Pod with new minor version.
+The switch should usually take less than 5 seconds, still clients have to
+reconnect.
+
+Major version upgrades are supported via [cloning](user.md#clone-directly). The
+new cluster manifest must have a higher `version` string than the source cluster
+and will be created from a basebackup. Depending of the cluster size, downtime
+in this case can be significant as writes to the database should be stopped and
+all WAL files should be archived first before cloning is started.
+
+Note, that simply changing the version string in the `postgresql` manifest does
+not work at present and leads to errors. Neither Patroni nor Postgres Operator
+can do in place `pg_upgrade`. Still, it can be executed manually in the Postgres
+container, which is tricky (i.e. systems need to be stopped, replicas have to be
+synced) but of course faster than cloning.
+
 ## CRD Validation
 
 [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
@@ -95,8 +115,6 @@ is used by the operator to connect to the clusters after creation.
 
 ## Role-based access control for the operator
 
-### Service account and cluster roles
-
 The manifest [`operator-service-account-rbac.yaml`](../manifests/operator-service-account-rbac.yaml)
 defines the service account, cluster roles and bindings needed for the operator
 to function under access control restrictions. To deploy the operator with this
@@ -109,19 +127,15 @@ kubectl create -f manifests/postgres-operator.yaml
 kubectl create -f manifests/minimal-postgres-manifest.yaml
 ```
 
+### Service account and cluster 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.
 
-The service account defined in `operator-service-account-rbac.yaml` acquires
-some privileges not used by the operator (i.e. we only need `list` and `watch`
-on `configmaps` resources). This is also done intentionally to avoid breaking
-things if someone decides to configure the same service account in the
-operator's ConfigMap to run Postgres clusters.
-
 ### Give K8s users access to create/list `postgresqls`
 
 By default `postgresql` custom resources can only be listed and changed by
@@ -157,7 +171,6 @@ metadata:
   name: postgres-operator
 data:
   toleration: "key:postgres,operator:Exists,effect:NoSchedule"
-  ...
 ```
 
 For an OperatorConfiguration resource the toleration should be defined like
@@ -172,7 +185,6 @@ 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)
@@ -250,7 +262,6 @@ metadata:
   name: postgres-operator
 data:
   inherited_labels: application,environment
-  ...
 ```
 
 **OperatorConfiguration**
@@ -265,7 +276,6 @@ configuration:
     inherited_labels:
     - application
     - environment
-...
 ```
 
 **cluster manifest**
@@ -279,7 +289,7 @@ metadata:
     application: my-app
     environment: demo
 spec:
-...
+  ...
 ```
 
 **network policy**
@@ -294,7 +304,6 @@ spec:
     matchLabels:
       application: my-app
       environment: demo
-...
 ```
 
 
@@ -317,7 +326,6 @@ metadata:
 data:
   # referencing config map with custom settings
   pod_environment_configmap: postgres-pod-config
-  ...
 ```
 
 **OperatorConfiguration**
@@ -331,7 +339,6 @@ configuration:
   kubernetes:
     # referencing config map with custom settings
     pod_environment_configmap: postgres-pod-config
-    ...
 ```
 
 **referenced ConfigMap `postgres-pod-config`**
@@ -412,12 +419,12 @@ external systems but defined for an individual Postgres cluster in its manifest.
 A typical example is a role for connections from an application that uses the
 database.
 
-* **Human users** originate from the Teams API that returns a list of the team
-members given a team id. The operator differentiates between (a) product teams
-that own a particular Postgres cluster and are granted admin rights to maintain
-it, and (b) Postgres superuser teams that get the superuser access to all
-Postgres databases running in a K8s cluster for the purposes of maintaining and
-troubleshooting.
+* **Human users** originate from the [Teams API](user.md#teams-api-roles) that
+returns a list of the team members given a team id. The operator differentiates
+between (a) product teams that own a particular Postgres cluster and are granted
+admin rights to maintain it, and (b) Postgres superuser teams that get the
+superuser access to all Postgres databases running in a K8s cluster for the
+purposes of maintaining and troubleshooting.
 
 ## Understanding rolling update of Spilo pods
 
@@ -481,7 +488,7 @@ A secret can be pre-provisioned in different ways:
 
 With the v1.2 release the Postgres Operator is shipped with a browser-based
 configuration user interface (UI) that simplifies managing Postgres clusters
-with the operator. The UI runs with Node.js and comes with it's own docker
+with the operator. The UI runs with Node.js and comes with it's own Docker
 image.
 
 Run NPM to continuously compile `tags/js` code. Basically, it creates an
@@ -493,14 +500,14 @@ Run NPM to continuously compile `tags/js` code. Basically, it creates an
 
 To build the Docker image open a shell and change to the `ui` folder. Then run:
 
-```
+```bash
 docker build -t registry.opensource.zalan.do/acid/postgres-operator-ui:v1.2.0 .
 ```
 
 Apply all manifests for the `ui/manifests` folder to deploy the Postgres
 Operator UI on K8s. For local tests you don't need the Ingress resource.
 
-```
+```bash
 kubectl apply -f ui/manifests
 ```
 
@@ -510,6 +517,6 @@ to the K8s and Postgres Operator REST API. You can use the provided
 `run_local.sh` script for this. Make sure it uses the correct URL to your K8s
 API server, e.g. for minikube it would be `https://192.168.99.100:8443`.
 
-```
+```bash
 ./run_local.sh
 ```

docs/developer.md

@@ -40,7 +40,7 @@ This would take a while to complete. You have to redo `make deps` every time
 your dependencies list changes, i.e. after adding a new library dependency.
 
 Build the operator with the `make docker` command. You may define the TAG
-variable to assign an explicit tag to your docker image and the IMAGE to set
+variable to assign an explicit tag to your Docker image and the IMAGE to set
 the image name. By default, the tag is computed with
 `git describe --tags --always --dirty` and the image is
 `registry.opensource.zalan.do/acid/postgres-operator`
@@ -60,10 +60,10 @@ The binary will be placed into the build directory.
 
 ## Deploying self build image
 
-The fastest way to run and test your docker image locally is to reuse the docker
-from [minikube](https://github.com/kubernetes/minikube/releases) or use the
-`load docker-image` from [kind](https://kind.sigs.k8s.io/). The following steps
-will get you the docker image built and deployed.
+The fastest way to run and test your Docker image locally is to reuse the Docker
+environment from [minikube](https://github.com/kubernetes/minikube/releases)
+or use the `load docker-image` from [kind](https://kind.sigs.k8s.io/). The
+following steps will get you the Docker image built and deployed.
 
 ```bash
 # minikube
@@ -162,7 +162,7 @@ The operator also supports pprof endpoints listed at the
 * /debug/pprof/trace
 
 It's possible to attach a debugger to troubleshoot postgres-operator inside a
-docker container. It's possible with [gdb](https://www.gnu.org/software/gdb/)
+Docker container. It's possible with [gdb](https://www.gnu.org/software/gdb/)
 and [delve](https://github.com/derekparker/delve). Since the latter one is a
 specialized debugger for Go, we will use it as an example. To use it you need:
 

docs/index.md

@@ -13,7 +13,7 @@ manages PostgreSQL clusters on Kubernetes (K8s):
 
 2. The operator also watches updates to [its own configuration](../manifests/configmap.yaml)
    and alters running Postgres clusters if necessary.  For instance, if the
-   docker image in a pod is changed, the operator carries out the rolling
+   Docker image in a pod is changed, the operator carries out the rolling
    update, which means it re-spawns pods of each managed StatefulSet one-by-one
    with the new Docker image.
 

docs/quickstart.md

@@ -155,9 +155,12 @@ export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
 ```
 
 Retrieve the password from the K8s Secret that is created in your cluster.
+Non-encrypted connections are rejected by default, so set the SSL mode to
+require:
 
 ```bash
 export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
+export PGSSLMODE=require
 psql -U postgres
 ```
 

docs/reference/cluster_manifest.md

@@ -62,7 +62,7 @@ These parameters are grouped directly under  the `spec` key in the manifest.
   field.
 
 * **dockerImage**
-  custom docker image that overrides the **docker_image** operator parameter.
+  custom Docker image that overrides the **docker_image** operator parameter.
   It should be a [Spilo](https://github.com/zalando/spilo) image. Optional.
 
 * **spiloFSGroup**
@@ -124,7 +124,7 @@ These parameters are grouped directly under  the `spec` key in the manifest.
 
 
 * **enableShmVolume**
-  Start a database pod without limitations on shm memory. By default docker
+  Start a database pod without limitations on shm memory. By default Docker
   limit `/dev/shm` to `64M` (see e.g. the [docker
   issue](https://github.com/docker-library/postgres/issues/416), which could be
   not enough if PostgreSQL uses parallel workers heavily. If this option is
@@ -185,19 +185,19 @@ explanation of `ttl` and `loop_wait` parameters.
 
 * **ttl**
   Patroni `ttl` parameter value, optional. The default is set by the Spilo
-  docker image. Optional.
+  Docker image. Optional.
 
 * **loop_wait**
   Patroni `loop_wait` parameter value, optional. The default is set by the
-  Spilo docker image. Optional.
+  Spilo Docker image. Optional.
 
 * **retry_timeout**
   Patroni `retry_timeout` parameter value, optional. The default is set by the
-  Spilo docker image. Optional.
+  Spilo Docker image. Optional.
 
 * **maximum_lag_on_failover**
   Patroni `maximum_lag_on_failover` parameter value, optional. The default is
-  set by the Spilo docker image. Optional.
+  set by the Spilo Docker image. Optional.
 
 * **slots**
   permanent replication slots that Patroni preserves after failover by
@@ -320,7 +320,7 @@ defined in the sidecar dictionary:
   name of the sidecar. Required.
 
 * **image**
-  docker image of the sidecar. Required.
+  Docker image of the sidecar. Required.
 
 * **env**
   a dictionary of environment variables. Use usual Kubernetes definition

docs/reference/operator_parameters.md

@@ -81,13 +81,13 @@ Those are top-level keys, containing both leaf keys and groups.
   Kubernetes-native DCS).
 
 * **docker_image**
-  Spilo docker image for Postgres instances. For production, don't rely on the
+  Spilo Docker image for Postgres instances. For production, don't rely on the
   default image, as it might be not the most up-to-date one. Instead, build
   your own Spilo image from the [github
   repository](https://github.com/zalando/spilo).
 
 * **sidecar_docker_images**
-  a map of sidecar names to docker images to run with Spilo. In case of the name
+  a map of sidecar names to Docker images to run with Spilo. In case of the name
   conflict with the definition in the cluster manifest the cluster-specific one
   is preferred.