Slimming out README and config map, targeting easy first time deployers to minicube.

Author: Jan-M

README.md

@@ -6,25 +6,25 @@
 
 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
-PostgreSQL clusters using StatefulSets and [Patroni](https://github.com/zalando/patroni).
+The `postgresql` CRD is essentially the schema that describes the contents of the manifests for deploying individual
+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
-  (i.e. when the docker image inside the operator definition has been updated)
-* periodically checks running clusters against the manifests and acts on the differences found
+* acts on an update to the operator configuration itself and changes the running clusters when necessary
+  (i.e. the Docker image changes for a minor release update)
+* 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
-``kubectl``, the operator fetches that object and creates the corresponding Kubernetes structures
-(StatefulSets, Services, Secrets) according to its definition.
+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 required Kubernetes entities to spawn a new Postgres cluster
+(StatefulSets, Services, Secrets).
 
-Another example is changing the docker image inside the operator. In this case, 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
-(rolling upgrade) and the replacements are spawned automatically by each StatefulSet with the new docker image.
+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 image; afterwards, all pods from each StatefulSet are killed one by one
+and the replacements are spawned automatically by each StatefulSet with the new Docker image. This is called the rolling upgrade.
 
 ## Scope
 
@@ -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,43 @@ apiVersion: v1
 kind: ConfigMap
 metadata:
   name: postgres-operator
-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
+data:  
   # 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}'
-  replica_dns_name_format: '{cluster}-repl.{team}.staging.{hostedzone}'
+  workers: "4"
   docker_image: registry.opensource.zalan.do/acid/demospilo-10:1.3-p3
   secret_name_template: '{username}.{cluster}.credentials'
-  etcd_host: ""
-  infrastructure_roles_secret_name: postgresql-infrastructure-roles
-  oauth_token_secret_name: postgresql-operator
-  pam_configuration: |
-    https://info.example.com/oauth2/tokeninfo?access_token= uid realm=/employees
-  pam_role_name: zalandos
+  # etcd_host: ""
+  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
+  # 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"
+  node_eol_label: "lifecycle-status:pending-decommission"
+  node_readiness_label: ""
+
+  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 +47,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
-        # 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
+        # provided additional ENV vars can overwrite individual config map entries  
         - name: CONFIG_MAP_NAME
           value: "postgres-operator"