Sketch operator conf/docs

docs/administrator.md

@@ -226,3 +226,13 @@ The operator is capable of maintaining roles of multiple kinds within a Postgres
 ## Understanding rolling update of Spilo pods
 
 The operator logs reasons for a rolling update with the `info` level and a diff between the old and new StatefulSet specs with the `debug` level. To benefit from numerous escape characters in the latter log entry, view it in CLI with `echo -e`. Note that the resultant message will contain some noise because the `PodTemplate` used by the operator is yet to be updated with the default values used internally in Kubernetes.
+
+## Logical backups
+
+The operator can launch k8s cron jobs to do periodic logical backups of all PG clusters under its control. The cron job spawns a separate pod with a single container that connects to one of the Postgres replicas for a backup. The operator updates cron jobs during Sync if a schedule or a docker image of a job changes. Notes:
+
+1. The provided  `registry.opensource.zalan.do/acid/logical-backup` image implements the backup via `pg_dumpall` and upload of (compressed) results to an S3 bucket; `pg_dumpall` requires a `superuser` access to a DB.
+
+2. Due to the [limitation of Kubernetes cron jobs](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-job-limitations) it is highly advisable to set up additional monitoring for this feature; such monitoring is outside of the scope of operator responsibilities. 
+
+3. The operator does not remove old backups: it is the responsibility of a k8s cluster administrator to define and implement a retention policy for backups.

docs/reference/cluster_manifest.md

@@ -261,6 +261,6 @@ defined in the sidecar dictionary:
 
  Those parameters are defined under the `logical_backup` key:
   *   **enable_logical_backup**
-     determines if the logical backup of this cluster should be uploaded to S3. Default: false.
+     determines if the logical backup of this cluster should be taken and uploaded to S3. Default: false.
   *   **logical_backup_schedule**
      backup schedule in Cron format. Default: "30 00 * * *"

docs/reference/operator_parameters.md

@@ -443,4 +443,22 @@ scalyr sidecar. In the CRD-based configuration they are grouped under the
   Memory limit value for the Scalyr sidecar. The default is `1Gi`.
 
 
+## Logical backup
+
+  These parameters configure a k8s cron job spawned by the operator to produce Postgres logical backups.
+  In the CRD-based configuration those parameters are grouped under the `logical_backup` key.
+
+  * **enable_logical_backup**
+    Determines if the operator should initiate the backup of all Postgres clusters it controls. Default: false.
+  
+  * **logical_backup_schedule**
+    Backup schedule in the cron format. Default: "30 00 * * *"
+  
+  * **logical_backup_docker_image**
+    Docker image for the pods of the cron job. Must implement backup/uploading logic. Default: empty.
+
+  * **logical_backup_s3_bucket**
+    S3 bucket to store backup results. Default: same as the bucket as for WAL.
+
+
 For the configmap operator configuration, the [default parameter values](https://github.com/zalando-incubator/postgres-operator/blob/master/pkg/util/config/config.go#L14) mentioned here are likely to be overwritten in your local operator installation via your local version of the operator configmap. In the case you use the operator CRD, all the CRD defaults are provided in the [operator's default configuration manifest](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/postgresql-operator-default-configuration.yaml)