Docs/reference (#323)

Document operator command-line options and environment variables.

README.md

@@ -26,6 +26,20 @@ manages PostgreSQL clusters on Kubernetes:
 3. Finally, the operator periodically synchronizes the actual state of each
    Postgres cluster with the desired state defined in the cluster's manifest.
 
+There is a browser-friendly version of this documentation at
+[postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
+
+## Table of contents
+
+* [concepts](docs/index.md)
+* [user documentation](docs/user.md)
+* [administrator documentation](docs/administrator.md)
+* [developer documentation](docs/developer.md)
+* [operator configuration reference](docs/reference/operator_parameters.md)
+* [cluster manifest reference](docs/reference/cluster_manifest.md)
+* [command-line options and environment variables](docs/reference/command_line_and_environment.md)
+
+the rest of the document is a tutorial to get you up and running with the operator on Minikube.
 
 ## Quickstart
 
@@ -34,6 +48,11 @@ Prerequisites:
 * [minikube](https://github.com/kubernetes/minikube/releases)
 * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
 
+Note that you can also use built-in Kubernetes support in the Docker Desktop
+for Mac to follow the steps of this tutorial. You would have to replace
+`minikube start` and `minikube delete` with your launch actionsfor the Docker
+built-in Kubernetes support.
+
 ### Local execution
 
 ```bash
@@ -77,10 +96,4 @@ Minikube is a tool to run Kubernetes cluster locally.
 
 The operator can be configured with the provided ConfigMap (`manifests/configmap.yaml`).
 
-## Table of contents
 
-* [concepts](docs/concepts.md)
-* [user documentation](docs/user.md)
-* [administrator documentation](docs/administrator.md)
-* [developer documentation](docs/developer.md)
-* [reference](docs/reference.md)

docs/administrator.md

@@ -1,5 +1,3 @@
-# How to deploy PostgreSQL operator
-
 ## Create ConfigMap
 
 ConfigMap is used to store the configuration of the operator

docs/developer.md

@@ -1,5 +1,3 @@
-# Installing and starting minikube
-
 ## Intro
 
 See [minikube installation guide](https://github.com/kubernetes/minikube/releases)
@@ -12,9 +10,7 @@ After the installation, issue
     $ minikube start
 ```
 
-Note: if you are running on a Mac, make sure to use the [xhyve
+Note: if you are running on a Mac, you may also use Docker for Mac Kubernetes instead of a docker-machine.
-driver](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md#xhyve-driver)
-instead of the default docker-machine one for performance reasons.
 
 Once you have it started successfully, use [the quickstart
 guide](https://github.com/kubernetes/minikube#quickstart) in order to test your

docs/index.md

@@ -1,6 +1,28 @@
-# Concepts
+# Introduction
 
-## Scope
+The Postgres [operator](https://coreos.com/blog/introducing-operators.html)
+manages PostgreSQL clusters on Kubernetes:
+
+1. The operator watches additions, updates, and deletions of PostgreSQL cluster
+   manifests and changes the running clusters accordingly.  For example, when a
+   user submits a new manifest, the operator fetches that manifest and spawns a
+   new Postgres cluster along with all necessary entities such as Kubernetes
+   StatefulSets and Postgres roles.  See this
+   [Postgres cluster manifest](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/complete-postgres-manifest.yaml)
+   for settings that a manifest may contain.
+
+2. The operator also watches updates to [its own configuration](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/configmap.yaml)
+   and alters running Postgres clusters if necessary.  For instance, if a pod
+   docker image is changed, the operator carries out the rolling update.  That
+   is, the operator re-spawns one-by-one pods of each StatefulSet it manages
+   with the new Docker image.
+
+3. Finally, the operator periodically synchronizes the actual state of each
+   Postgres cluster with the desired state defined in the cluster's manifest.
+
+## Concepts
+
+### 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
@@ -15,7 +37,7 @@ experience.
 Monitoring of clusters is not in scope, for this good tools already exist from
 ZMON to Prometheus and more Postgres specific options.
 
-## Status
+### Status
 
 This project is currently in active development. It is however already
 [used internally by Zalando](https://jobs.zalando.com/tech/blog/postgresql-in-a-time-of-kubernetes/)

docs/quickstart.md

@@ -0,0 +1,54 @@
+## Prerequisites:
+
+In order to run the Postgres operator locally in minikube you need to install the following tools:
+
+* [minikube](https://github.com/kubernetes/minikube/releases)
+* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
+
+Note that you can also use built-in Kubernetes support in the Docker Desktop
+for Mac to follow the steps of this tutorial. You would have to replace
+`minikube start` and `minikube delete` with your launch actionsfor the Docker
+built-in Kubernetes support.
+
+## Local execution
+
+```bash
+git clone https://github.com/zalando-incubator/postgres-operator.git
+cd postgres-operator
+
+minikube start
+
+# start the operator; may take a few seconds
+kubectl create -f manifests/configmap.yaml  # configuration
+kubectl create -f manifests/operator-service-account-rbac.yaml  # identity and permissions
+kubectl create -f manifests/postgres-operator.yaml  # deployment
+
+# create a Postgres cluster
+kubectl create -f manifests/minimal-postgres-manifest.yaml
+
+# connect to the Postgres master via psql
+# operator creates the relevant k8s secret
+export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,')
+export PGHOST=$(echo $HOST_PORT | cut -d: -f 1)
+export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
+export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
+psql -U postgres
+
+# tear down cleanly
+minikube delete
+```
+
+We have automated starting the operator and submitting the `acid-minimal-cluster` for you:
+```bash
+cd postgres-operator
+./run_operator_locally.sh
+```
+
+## Running and testing the operator
+
+The best way to test the operator is to run it in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/).
+Minikube is a tool to run Kubernetes cluster locally.
+
+### Configuration Options
+
+The operator can be configured with the provided ConfigMap (`manifests/configmap.yaml`).

docs/reference.md

@@ -1,23 +0,0 @@
-# Reference
-
-## Deprecated parameters
-
-Parameters `useLoadBalancer` and `replicaLoadBalancer` in the PostgreSQL
-manifest are deprecated. To retain compatibility with the old manifests they
-take effect in the absense of new `enableMasterLoadBalancer` and
-`enableReplicaLoadBalancer` parameters (that is, if either of the new ones is
-present - all deprecated parameters are ignored). The operator configuration
-parameter `enable_load_balancer` is ignored in all cases.
-
-## Operator Configuration Parameters
-
-* team_api_role_configuration - a map represented as
-  *"key1:value1,key2:value2"* of configuration parameters applied to the roles
-  fetched from the API. For instance, `team_api_role_configuration:
-  log_statement:all,search_path:'public,"$user"'`. By default is set to
-  *"log_statement:all"*. See
-  [PostgreSQL documentation on ALTER ROLE .. SET](https://www.postgresql.org/docs/current/static/sql-alterrole.html)
-  for to learn about the available options.
-* protected_role_names - a list of role names that should be forbidden as the
-  manifest, infrastructure and teams API roles. The default value is `admin`.
-  Operator will also disallow superuser and replication roles to be redefined.

docs/reference/cluster_manifest.md

@@ -1,5 +1,3 @@
-Postgres Cluster Manifest
-=========================
 
 Individual postgres clusters are described by the Kubernetes *cluster manifest*
 that has the structure defined by the `postgres CRD` (custom resource
@@ -16,14 +14,13 @@ measurements. Please, refer to the [Kubernetes
 documentation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
 for the possible values of those.
 
-Manifest structure
+## Manifest structure
-------------------
 
 A postgres manifest is a `YAML` document. On the top level both individual
 parameters and parameter groups can be defined. Parameter names are written
 in camelCase.
 
-### Cluster metadata
+## Cluster metadata
 
 Those parameters are grouped under the `metadata` top-level key.
 
@@ -38,7 +35,7 @@ Those parameters are grouped under the `metadata` top-level key.
   namespace. Optional (if present, should match the namespace where the
   manifest is applied). 
 
-### Top-level parameters
+## Top-level parameters
 
 Those are parameters grouped directly under  the `spec` key in the manifest.
 
@@ -93,7 +90,7 @@ Those are parameters grouped directly under  the `spec` key in the manifest.
   for details on tolerations and possible values of those keys. When set, this
   value overrides the `pod_toleration` setting from the operator. Optional.
 
-### Postgres parameters
+## Postgres parameters
 
 Those parameters are grouped under the `postgresql` top-level key.
 
@@ -108,7 +105,7 @@ Those parameters are grouped under the `postgresql` top-level key.
   cluster. Optional (Spilo automatically sets reasonable defaults for
   parameters like work_mem or max_connections).
 
-### Patroni parameters
+## Patroni parameters
 
 Those parameters are grouped under the `patroni` top-level key. See the [patroni
 documentation](https://patroni.readthedocs.io/en/latest/SETTINGS.html) for the
@@ -147,14 +144,14 @@ explanation of `ttl` and `loop_wait` parameters.
   patroni `maximum_lag_on_failover` parameter value, optional. The default is
   set by the Spilo docker image. Optional.
 
-### Postgres container resources
+## Postgres container resources
 
 Those parameters define [CPU and memory requests and
 limits](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
 for the postgres container. They are grouped under the `resources` top-level
 key. There are two subgroups, `requests` and `limits`.
 
-#### Requests
+### Requests
 
 CPU and memory requests for the postgres container.
 
@@ -178,7 +175,7 @@ CPU and memory limits for the postgres container.
   memory limits for the postgres container. Optional, overrides the
   `default_memory_limits` operator configuration parameter. Optional.
 
-### Parameters defining how to clone the cluster from another one
+## Parameters defining how to clone the cluster from another one
 
 Those parameters are applied when the cluster should be a clone of another one
 that is either already running or has a basebackup on S3. They are grouped

docs/reference/command_line_and_environment.md

@@ -0,0 +1,50 @@
+## Command-line options
+
+The following command-line options are supported for the operator:
+
+* **-kubeconfig**
+  the path to the kubeconfig file. Usually named config, it contains
+  authorization information as well as the URL of the Kubernetes master.
+
+* **-outofcluster**
+  run the operator on a client machine, as opposed to a within the cluster.
+  When running in this mode, the operator cannot connect to databases inside
+  the cluster, as well as call URLs of in-cluster objects (i.e. teams api
+  server). Mostly useful for debugging, it also requires setting the
+  `OPERATOR_NAMESPACE` environment variable for the operator own namespace.
+
+* **-nodatabaseaccess**
+  disable database access from the operator. Equivalent to the
+  `enable_database_access` set to off and can be overridden by the
+  aforementioned operator configuration option.
+
+* **-noteamsapi**
+  disable access to the teams API. Equivalent to the `enable_teams_api` set to
+  off can can be overridden by the aforementioned operator configuration
+  option.
+
+In addition to that, standard [glog
+flags](https://godoc.org/github.com/golang/glog) are also supported. For
+instance, one may want to add `-alsologtostderr` and `-v=8` to debug the
+operator REST calls.
+
+## Environment variables
+
+The following environment variables are accepted by the operator:
+
+* **CONFIG_MAP_NAME**
+  name of the config map where the operator should look for its configuration.
+  Must be present.
+
+* **OPERATOR_NAMESPACE**
+  name of the namespace the operator runs it. Overrides autodetection by the
+  operator itself.
+
+* **WATCHED_NAMESPACE**
+  the name of the namespace the operator watches. Special '*' character denotes
+  all namespaces. Empty value defaults to the operator namespace. Overrides the
+  `watched_namespace` operator parameter.
+
+* **SCALYR_API_KEY**
+  the value of the Scalyr API key to supply to the pods. Overrides the
+  `scalyr_api_key` operator parameter.

docs/reference/operator_parameters.md

@@ -1,14 +1,9 @@
-Postgres Operator Configuration
-===============================
 
 Postgres operator is configured via a ConfigMap defined by the
 `CONFIG_MAP_NAME` environment variable. Variable names are underscore-separated
 words.
 
-Available Configuration Parameters
+## General
-----------------------------------
-
-### General
 * **etcd_host**
   Etcd connection string for Patroni defined as `host:port`. Not required when
   Patroni native Kubernetes support is used. The default is empty (use
@@ -37,7 +32,7 @@ Available Configuration Parameters
 * **resync_period**
   period between consecutive sync requests. The default is `5m`.
 
-### Postgres users
+## Postgres users
 * **super_username**
   postgres `superuser` name to be created by `initdb`. The default is
   `postgres`.
@@ -46,7 +41,7 @@ Available Configuration Parameters
   postgres username used for replication between instances. The default is
   `standby`.
 
-### Kubernetes resources
+## Kubernetes resources
 * **pod_service_account_name**
   service account used by Patroni running on individual Pods to communicate
   with the operator. Required even if native Kubernetes support in Patroni is
@@ -126,7 +121,7 @@ Available Configuration Parameters
   conflicts they are overridden by the environment variables generated by the
   operator. The default is empty.
 
-### Kubernetes resource requests
+## Kubernetes resource requests
 * **default_cpu_request**
   CPU request value for the postgres containers, unless overridden by
   cluster-specific settings. The default is `100m`.
@@ -143,7 +138,7 @@ Available Configuration Parameters
   memory limits for the postgres containers, unless overridden by cluster-specific
   settings. The default is `1Gi`.
 
-### Operator timeouts
+## Operator timeouts
 * **resource_check_interval**
   interval to wait between consecutive attempts to check for the presence of
   some Kubernetes resource (i.e. `StatefulSet` or `PodDisruptionBudget`). The
@@ -170,7 +165,7 @@ Available Configuration Parameters
 * **ready_wait_timeout**
   the timeout for the complete postgres CRD creation. The default is `30s`.
 
-### Load balancer related options
+## Load balancer related options
 * **db_hosted_zone**
   DNS zone for the cluster DNS name when the load balancer is configured for
   the cluster. Only used when combined with
@@ -201,7 +196,7 @@ Available Configuration Parameters
   replaced with the hosted zone (the value of the `db_hosted_zone` parameter).
   No other placeholders are allowed.
 
-### AWS or GSC interaction
+## AWS or GSC interaction
 * **wal_s3_bucket**
   S3 bucket to use for shipping WAL segments with WAL-E. A bucket has to be
   present and accessible by Patroni managed pods. At the moment, supported
@@ -217,7 +212,7 @@ Available Configuration Parameters
   pods. Only used when combined with
   [kube2iam](https://github.com/jtblin/kube2iam) project on AWS. The default is empty.
 
-### Debugging the operator
+## Debugging the operator
 * **debug_logging**
   boolean parameter that toggles verbose debug logs from the operator. The
   default is `true`.
@@ -272,7 +267,7 @@ Available Configuration Parameters
   List of roles that cannot be overwritten by an application, team or
   infrastructure role. The default is `admin`.
 
-### Logging and REST API
+## Logging and REST API
 * **api_port**
   REST API listener listens to this port. The default is `8080`.
 

docs/user.md

@@ -1,9 +1,7 @@
-# How to create a new PostgreSQL cluster
-
 ## Create a manifest for a new PostgreSQL cluster
 
 As an example you can take this
-[minimal example](manifests/minimal-postgres-manifest.yaml):
+[minimal example](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/minimal-postgres-manifest.yaml):
 
 ```yaml
 apiVersion: "acid.zalan.do/v1"
@@ -206,10 +204,10 @@ spec:
 
 Here `cluster` is a name of a source cluster that is going to be cloned. The
 cluster to clone is assumed to be running and the clone procedure invokes
-`pg_basebackup` from it. The operator will connect to the service by name (if
+`pg_basebackup` from it. The operator will setup the cluster to be cloned to
-the cluster is called test, then the connection string will look like host=test
+connect to the service of the source cluster by name (if the cluster is called
-port=5432), which means that you can clone only from clusters running in the
+test, then the connection string will look like host=test port=5432), which
-default namespace.
+means that you can clone only from clusters within the same namespace.
 
 ### Clone from S3
 

mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: Postgres Operator
+repo_url: https://github.com/zalando-incubator/postgres-operator
+theme: readthedocs
+
+pages:
+  - Introduction: index.md
+  - Quickstart: quickstart.md
+  - Administrator Guide: administrator.md
+  - User Guide: user.md
+  - Developer Guide: developer.md
+  - Reference:
+    - Operator Configuration: reference/operator_parameters.md
+    - Cluster Manifest description: reference/cluster_manifest.md
+    - Command-line options and environment: reference/command_line_and_environment.md
+    
+