Docs/reference (#323)
Document operator command-line options and environment variables.
This commit is contained in:
Oleksii Kliukin
zerg-junior
parent
b518a31d0c
commit
5d02c57e04
25
README.md
25
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)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
# How to deploy PostgreSQL operator
|
||||
|
||||
## Create ConfigMap
|
||||
|
||||
ConfigMap is used to store the configuration of the operator
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
@ -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`).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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`.
|
||||
|
||||
12
docs/user.md
12
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue