Merge pull request #285 from zalando-incubator/readme-changes-1

README and deployment manifest updates

README.md

@@ -6,32 +6,32 @@
 
 The Postgres operator manages PostgreSQL clusters on Kubernetes using the [operator pattern](https://coreos.com/blog/introducing-operators.html).
 During the initial run it registers the [Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions) for Postgres.
-The PostgreSQL CRD is essentially the schema that describes the contents of the manifests for deploying individual
+The `postgresql` CRD is essentially the schema that describes the contents of the manifests for deploying individual
-PostgreSQL clusters using StatefulSets and [Patroni](https://github.com/zalando/patroni).
+Postgres clusters using StatefulSets and [Patroni](https://github.com/zalando/patroni).
 
 Once the operator is running, it performs the following actions:
 
-* watches for new PostgreSQL cluster manifests and deploys corresponding clusters
+* watches for new `postgresql` manifests and deploys new clusters
 * watches for updates to existing manifests and changes corresponding properties of the running clusters
 * watches for deletes of the existing manifests and deletes corresponding clusters
-* acts on an update to the operator definition itself and changes the running clusters when necessary
+* acts on an update to the operator configuration itself and changes the running clusters when necessary
-  (i.e. when the docker image inside the operator definition has been updated)
+  (i.e. the Docker image changes for a minor release update)
-* periodically checks running clusters against the manifests and acts on the differences found
+* periodically checks running clusters against the manifests and syncs changes
 
-For instance, when the user creates a new custom object of type ``postgresql`` by submitting a new manifest with
+Example: When a user creates a new custom object of type ``postgresql`` by submitting a new manifest with
-``kubectl``, the operator fetches that object and creates the corresponding Kubernetes structures
+``kubectl``, the operator fetches that object and creates the required Kubernetes entities to spawn a new Postgres cluster
-(StatefulSets, Services, Secrets) according to its definition.
+(StatefulSets, Services, Secrets).
 
-Another example is changing the docker image inside the operator. In this case, the operator first goes to all StatefulSets
+Update example: After changing the Docker image inside the operator's configuration, the operator first goes to all StatefulSets
-it manages and updates them with the new docker images; afterwards, all pods from each StatefulSet are killed one by one
+it manages and updates them with the new Docker image; afterwards, all pods from each StatefulSet are killed one by one
-(rolling upgrade) and the replacements are spawned automatically by each StatefulSet with the new docker image.
+and the replacements are spawned automatically by each StatefulSet with the new Docker image. This is called the Rolling update.
 
 ## Scope
 
 The scope of the postgres operator is on provisioning, modifying configuration and cleaning up Postgres clusters that use Patroni, basically to make it easy and convenient to run Patroni based clusters on Kubernetes.
 The provisioning and modifying includes Kubernetes resources on one side but also e.g. database and role provisioning once the cluster is up and running.
 We try to leave as much work as possible to Kubernetes and to Patroni where it fits, especially the cluster bootstrap and high availability.
-The operator is however involved in some overarching orchestration, like rolling upgrades to improve the user experience.
+The operator is however involved in some overarching orchestration, like rolling updates to improve the user experience.
 
 Monitoring of clusters is not in scope, for this good tools already exist from ZMON to Prometheus and more Postgres specific options.
 
@@ -147,9 +147,9 @@ We can use the generated secret of the `postgres` robot user to connect to our `
 The `manifests/operator-rbac.yaml` defines cluster roles and bindings needed for the operator 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/configmap.yaml
 kubectl create -f manifests/operator-rbac.yaml
-kubectl create -f manifests/postgres-operator.yaml 
+kubectl create -f manifests/postgres-operator.yaml
 kubectl create -f manifests/minimal-postgres-manifest.yaml
 ```
 
@@ -158,7 +158,7 @@ the `operator` default that is created in the `serviceaccount.yaml`. So you will
 
 This is done intentionally, as 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. 
+`zalando-postgres-operator` service account.
 
 The service account defined in  `operator-rbac.yaml` acquires some privileges not really
 used by the operator (i.e. we only need list and watch on configmaps),
@@ -274,7 +274,7 @@ As a preventive measure, one can restrict the minimum and the maximum number of
 If either `min_instances` or `max_instances` is set to a non-zero value, the operator may adjust the number of instances specified in the cluster manifest to match either the min or the max boundary.
 For instance, of a cluster manifest has 1 instance and the min_instances is set to 3, the cluster will be created with 3 instances. By default, both parameters are set to -1.
 
-### Load balancers 
+### Load balancers
 
 For any Postgresql/Spilo cluster an operator creates two separate k8s 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 is omitted from the manifest, the operator configmap's settings `enable_master_load_balancer` and `enable_replica_load_balancer` apply. Note that the operator settings affect all Postgresql services running in a namespace watched by the operator.
 

manifests/configmap.yaml

@@ -2,26 +2,41 @@ apiVersion: v1
 kind: ConfigMap
 metadata:
   name: postgres-operator
-data:
+data:  
-  # the env var with the same name in the operator pod may overwrite this value
-  # if neither is set or evaluates to the empty string, listen to the operator's own namespace
   # if set to the "*", listen to all namespaces
   # watched_namespace: development
   cluster_labels: application:spilo
   cluster_name_label: version
   pod_role_label: spilo-role
-  db_hosted_zone: db.example.com
+
   debug_logging: "true"
-  master_dns_name_format: '{cluster}.{team}.staging.{hostedzone}'
+  workers: "4"
-  replica_dns_name_format: '{cluster}-repl.{team}.staging.{hostedzone}'
   docker_image: registry.opensource.zalan.do/acid/demospilo-10:1.3-p3
   secret_name_template: '{username}.{cluster}.credentials'
-  etcd_host: ""
+  # etcd_host: ""
-  infrastructure_roles_secret_name: postgresql-infrastructure-roles
+  super_username: postgres
-  oauth_token_secret_name: postgresql-operator
+  enable_teams_api: "false"
-  pam_configuration: |
+  # enable_team_superuser: "false"
-    https://info.example.com/oauth2/tokeninfo?access_token= uid realm=/employees
+  # team_admin_role: "admin"
-  pam_role_name: zalandos
+  # teams_api_url: http://fake-teams-api.default.svc.cluster.local
+  # team_api_role_configuration: "log_statement:all"
+  # infrastructure_roles_secret_name: postgresql-infrastructure-roles
+  # oauth_token_secret_name: postgresql-operator
+  # pam_role_name: zalandos
+  # pam_configuration: |
+  #  https://info.example.com/oauth2/tokeninfo?access_token= uid realm=/employees
+  db_hosted_zone: db.example.com
+  master_dns_name_format: '{cluster}.{team}.staging.{hostedzone}'
+  replica_dns_name_format: '{cluster}-repl.{team}.staging.{hostedzone}'
+  enable_master_load_balancer: "false"
+  enable_replica_load_balancer: "false"
+
+  pdb_name_format: "postgres-{cluster}-pdb"
+
+  api_port: "8080"
+  ring_log_lines: "100"
+  cluster_history_entries: "1000"
+  pod_terminate_grace_period: 5m
   pod_deletion_wait_timeout: 10m
   pod_label_wait_timeout: 10m
   ready_wait_interval: 3s
@@ -30,21 +45,3 @@ data:
   resource_check_interval: 3s
   resource_check_timeout: 10m
   resync_period: 5m
-  super_username: postgres
-  enable_teams_api: "false"
-  enable_team_superuser: "false"
-  team_admin_role: "admin"
-  teams_api_url: http://fake-teams-api.default.svc.cluster.local
-  workers: "4"
-  # turn on/off load balancers for all Postgres clusters managed by the operator
-  # LB settings in cluster manifests take priority over these settings
-  enable_master_load_balancer: "true"
-  enable_replica_load_balancer: "false"
-  api_port: "8080"
-  ring_log_lines: "100"
-  cluster_history_entries: "1000"
-  pod_terminate_grace_period: 5m
-  pdb_name_format: "postgres-{cluster}-pdb"
-  node_eol_label: "lifecycle-status:pending-decommission"
-  node_readiness_label: ""
-  team_api_role_configuration: "log_statement:all"

manifests/postgres-operator.yaml

@@ -12,15 +12,9 @@ spec:
       serviceAccountName: operator
       containers:
       - name: postgres-operator
-        image: registry.opensource.zalan.do/acid/postgres-operator:0f392c2
+        image: registry.opensource.zalan.do/acid/postgres-operator:4c8dfd7
         imagePullPolicy: IfNotPresent
         env:
-        # uncomment to overwrite a similar setting from operator configmap
+        # provided additional ENV vars can overwrite individual config map entries  
-        # if set to the empty string, watch the operator's own namespace
-        # if set to the "*", listen to all namespaces
-        # - name: WATCHED_NAMESPACE
-        #  valueFrom:
-        #    fieldRef:
-        #      fieldPath: metadata.namespace
         - name: CONFIG_MAP_NAME
           value: "postgres-operator"