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
-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 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.
 

manifests/configmap.yaml

@@ -3,25 +3,40 @@ 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
   # 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"
+
+  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
-        # 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"