From 5d02c57e042ec75b5f8b849e1c3f8396e863250b Mon Sep 17 00:00:00 2001 From: Oleksii Kliukin Date: Tue, 12 Jun 2018 19:12:11 +0200 Subject: [PATCH] Docs/reference (#323) Document operator command-line options and environment variables. --- README.md | 25 ++++++--- docs/administrator.md | 2 - docs/developer.md | 6 +-- docs/{concepts.md => index.md} | 28 ++++++++-- docs/quickstart.md | 54 +++++++++++++++++++ docs/reference.md | 23 -------- docs/{ => reference}/cluster_manifest.md | 19 +++---- .../reference/command_line_and_environment.md | 50 +++++++++++++++++ docs/{ => reference}/operator_parameters.md | 23 ++++---- docs/user.md | 12 ++--- mkdocs.yml | 16 ++++++ 11 files changed, 187 insertions(+), 71 deletions(-) rename docs/{concepts.md => index.md} (58%) create mode 100644 docs/quickstart.md delete mode 100644 docs/reference.md rename docs/{ => reference}/cluster_manifest.md (96%) create mode 100644 docs/reference/command_line_and_environment.md rename docs/{ => reference}/operator_parameters.md (97%) create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 48f269f8b..e7b486087 100644 --- a/README.md +++ b/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) diff --git a/docs/administrator.md b/docs/administrator.md index ef64dd224..bb775ed02 100644 --- a/docs/administrator.md +++ b/docs/administrator.md @@ -1,5 +1,3 @@ -# How to deploy PostgreSQL operator - ## Create ConfigMap ConfigMap is used to store the configuration of the operator diff --git a/docs/developer.md b/docs/developer.md index 5235c57dd..407af6439 100644 --- a/docs/developer.md +++ b/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 -driver](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md#xhyve-driver) -instead of the default docker-machine one for performance reasons. +Note: if you are running on a Mac, you may also use Docker for Mac Kubernetes instead of a docker-machine. Once you have it started successfully, use [the quickstart guide](https://github.com/kubernetes/minikube#quickstart) in order to test your diff --git a/docs/concepts.md b/docs/index.md similarity index 58% rename from docs/concepts.md rename to docs/index.md index e93d5fc9c..c3327eae7 100644 --- a/docs/concepts.md +++ b/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/) diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 000000000..7b9c667e1 --- /dev/null +++ b/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`). diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index d27ef3f0c..000000000 --- a/docs/reference.md +++ /dev/null @@ -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. diff --git a/docs/cluster_manifest.md b/docs/reference/cluster_manifest.md similarity index 96% rename from docs/cluster_manifest.md rename to docs/reference/cluster_manifest.md index db7ce17c1..44ab99c83 100644 --- a/docs/cluster_manifest.md +++ b/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 diff --git a/docs/reference/command_line_and_environment.md b/docs/reference/command_line_and_environment.md new file mode 100644 index 000000000..1c4a6e8d7 --- /dev/null +++ b/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. diff --git a/docs/operator_parameters.md b/docs/reference/operator_parameters.md similarity index 97% rename from docs/operator_parameters.md rename to docs/reference/operator_parameters.md index 6d277c589..115cb055e 100644 --- a/docs/operator_parameters.md +++ b/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`. diff --git a/docs/user.md b/docs/user.md index 2420a2681..b17cfc784 100644 --- a/docs/user.md +++ b/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 -the cluster is called test, then the connection string will look like host=test -port=5432), which means that you can clone only from clusters running in the -default namespace. +`pg_basebackup` from it. The operator will setup the cluster to be cloned to +connect to the service of the source cluster by name (if the cluster is called +test, then the connection string will look like host=test port=5432), which +means that you can clone only from clusters within the same namespace. ### Clone from S3 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..e50107eed --- /dev/null +++ b/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 + +