Merge branch 'master' into global_and_per_cluster_sidecards
# Conflicts: # docs/user.md
This commit is contained in:
Oleksii Kliukin
commit
2a32eb4129
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
|
3. Finally, the operator periodically synchronizes the actual state of each
|
||||||
Postgres cluster with the desired state defined in the cluster's manifest.
|
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
|
## Quickstart
|
||||||
|
|
||||||
|
|
@ -34,6 +48,11 @@ Prerequisites:
|
||||||
* [minikube](https://github.com/kubernetes/minikube/releases)
|
* [minikube](https://github.com/kubernetes/minikube/releases)
|
||||||
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
|
* [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
|
### Local execution
|
||||||
|
|
||||||
```bash
|
```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`).
|
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
|
## Create ConfigMap
|
||||||
|
|
||||||
ConfigMap is used to store the configuration of the operator
|
ConfigMap is used to store the configuration of the operator
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,3 @@
|
||||||
# Installing and starting minikube
|
|
||||||
|
|
||||||
## Intro
|
## Intro
|
||||||
|
|
||||||
See [minikube installation guide](https://github.com/kubernetes/minikube/releases)
|
See [minikube installation guide](https://github.com/kubernetes/minikube/releases)
|
||||||
|
|
@ -12,9 +10,7 @@ After the installation, issue
|
||||||
$ minikube start
|
$ 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
|
Once you have it started successfully, use [the quickstart
|
||||||
guide](https://github.com/kubernetes/minikube#quickstart) in order to test your
|
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
|
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 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
|
Monitoring of clusters is not in scope, for this good tools already exist from
|
||||||
ZMON to Prometheus and more Postgres specific options.
|
ZMON to Prometheus and more Postgres specific options.
|
||||||
|
|
||||||
## Status
|
### Status
|
||||||
|
|
||||||
This project is currently in active development. It is however already
|
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/)
|
[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.
|
|
||||||
|
|
@ -0,0 +1,215 @@
|
||||||
|
|
||||||
|
Individual postgres clusters are described by the Kubernetes *cluster manifest*
|
||||||
|
that has the structure defined by the `postgres CRD` (custom resource
|
||||||
|
definition). The following section describes the structure of the manifest and
|
||||||
|
the purpose of individual keys. You can take a look at the examples of the
|
||||||
|
[minimal](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/minimal-postgres-manifest.yaml)
|
||||||
|
and the
|
||||||
|
[complete](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/complete-postgres-manifest.yaml)
|
||||||
|
cluster manifests.
|
||||||
|
|
||||||
|
When Kubernetes resources, such as memory, CPU or volumes, are configured,
|
||||||
|
their amount is usually described as a string together with the units of
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
Those parameters are grouped under the `metadata` top-level key.
|
||||||
|
|
||||||
|
* **name**
|
||||||
|
the name of the cluster. Must start with the `teamId` followed by a dash.
|
||||||
|
Changing it after the cluster creation is not supported. Required field.
|
||||||
|
|
||||||
|
* **namespace**
|
||||||
|
the namespace where the operator creates Kubernetes objects (i.e. pods,
|
||||||
|
services, secrets) for the cluster. Changing it after the cluster creation
|
||||||
|
results in deploying or updating a completely separate cluster in the target
|
||||||
|
namespace. Optional (if present, should match the namespace where the
|
||||||
|
manifest is applied).
|
||||||
|
|
||||||
|
## Top-level parameters
|
||||||
|
|
||||||
|
Those are parameters grouped directly under the `spec` key in the manifest.
|
||||||
|
|
||||||
|
* **teamId**
|
||||||
|
name of the team the cluster belongs to. Changing it after the cluster
|
||||||
|
creation is not supported. Required field.
|
||||||
|
|
||||||
|
* **dockerImage**
|
||||||
|
custom docker image that overrides the **docker_image** operator parameter.
|
||||||
|
It should be a [Spilo](https://github.com/zalando/spilo) image. Optional.
|
||||||
|
|
||||||
|
* **enableMasterLoadBalancer**
|
||||||
|
boolean flag to override the operator defaults (set by the
|
||||||
|
`enable_master_load_balancer` parameter) to define whether to enable the load
|
||||||
|
balancer pointing to the postgres primary. Optional.
|
||||||
|
|
||||||
|
* **enableReplicaLoadBalancer**
|
||||||
|
boolean flag to override the operator defaults (set by the
|
||||||
|
`enable_replica_load_balancer` parameter) to define whether to enable the
|
||||||
|
load balancer pointing to the postgres standby instances. Optional.
|
||||||
|
|
||||||
|
* **allowedSourceRanges**
|
||||||
|
when one or more load balancers are enabled for the cluster, this parameter
|
||||||
|
defines the comma-separated range of IP networks (in CIDR-notation). The
|
||||||
|
corresponding load balancer is accessible only to the networks defined by
|
||||||
|
this parameter. Optional, when empty the load balancer service becomes
|
||||||
|
inaccessible from outside of the Kubernetes cluster.
|
||||||
|
|
||||||
|
* **numberOfInstances**
|
||||||
|
total number of instances for a given cluster. The operator parameters
|
||||||
|
`max_instances` and `min_instances` may also adjust this number. Required
|
||||||
|
field.
|
||||||
|
|
||||||
|
* **users**
|
||||||
|
a map of usernames to user flags for the users that should be created in the
|
||||||
|
cluster by the operator. User flags are a list, allowed elements are
|
||||||
|
`SUPERUSER`, `REPLICATION`, `INHERIT`, `LOGIN`, `NOLOGIN`, `CREATEROLE`,
|
||||||
|
`CREATEDB`, `BYPASSURL`. A login user is created by default unless NOLOGIN is
|
||||||
|
specified, in which case the operator creates a role. One can specify empty
|
||||||
|
flags by providing a JSON empty array '*[]*'. Optional.
|
||||||
|
|
||||||
|
* **databases**
|
||||||
|
a map of database names to database owners for the databases that should be
|
||||||
|
created by the operator. The owner users should already exist on the cluster
|
||||||
|
(i.e. mentioned in the `user` parameter). Optional.
|
||||||
|
|
||||||
|
* **tolerations**
|
||||||
|
a list of tolerations that apply to the cluster pods. Each element of that
|
||||||
|
list is a dictionary with the following fields: `key`, `operator`, `value`,
|
||||||
|
`effect` and `tolerationSeconds`. Each field is optional. See [Kubernetes
|
||||||
|
examples](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
|
||||||
|
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
|
||||||
|
|
||||||
|
Those parameters are grouped under the `postgresql` top-level key.
|
||||||
|
|
||||||
|
* **version**
|
||||||
|
the postgres major version of the cluster. Looks at the [Spilo
|
||||||
|
project](https://github.com/zalando/spilo/releases) for the list of supported
|
||||||
|
versions. Changing the cluster version once the cluster has been bootstrapped
|
||||||
|
is not supported. Required field.
|
||||||
|
|
||||||
|
* **parameters**
|
||||||
|
a dictionary of postgres parameter names and values to apply to the resulting
|
||||||
|
cluster. Optional (Spilo automatically sets reasonable defaults for
|
||||||
|
parameters like work_mem or max_connections).
|
||||||
|
|
||||||
|
## 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
|
||||||
|
explanation of `ttl` and `loop_wait` parameters.
|
||||||
|
|
||||||
|
* **initdb**
|
||||||
|
a map of key-value pairs describing initdb parameters. For `data-checksum`,
|
||||||
|
`debug`, `no-locale`, `noclean`, `nosync` and `sync-only` parameters use
|
||||||
|
`true` as the value if you want to set them. Changes to this option do not
|
||||||
|
affect the already initialized clusters. Optional.
|
||||||
|
|
||||||
|
* **pg_hba**
|
||||||
|
list of custom `pg_hba` lines to replace default ones. Note that the default
|
||||||
|
ones include
|
||||||
|
|
||||||
|
```
|
||||||
|
hostsll all +pamrole all pam
|
||||||
|
```
|
||||||
|
, where pamrole is the name of the role for the pam authentication; any
|
||||||
|
custom `pg_hba` should include the pam line to avoid breaking pam
|
||||||
|
authentication. Optional.
|
||||||
|
|
||||||
|
* **ttl**
|
||||||
|
patroni `ttl` parameter value, optional. The default is set by the Spilo
|
||||||
|
docker image. Optional.
|
||||||
|
|
||||||
|
* **loop_wait**
|
||||||
|
patroni `loop_wait` parameter value, optional. The default is set by the
|
||||||
|
Spilo docker image. Optional.
|
||||||
|
|
||||||
|
* **retry_timeout**
|
||||||
|
patroni `retry_timeout` parameter value, optional. The default is set by the
|
||||||
|
Spilo docker image. Optional.
|
||||||
|
|
||||||
|
* **maximum_lag_on_failover**
|
||||||
|
patroni `maximum_lag_on_failover` parameter value, optional. The default is
|
||||||
|
set by the Spilo docker image. Optional.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
CPU and memory requests for the postgres container.
|
||||||
|
|
||||||
|
* **cpu**
|
||||||
|
CPU requests for the postgres container. Optional, overrides the
|
||||||
|
`default_cpu_requests` operator configuration parameter. Optional.
|
||||||
|
|
||||||
|
* **memory**
|
||||||
|
memory requests for the postgres container. Optional, overrides the
|
||||||
|
`default_memory_request` operator configuration parameter. Optional.
|
||||||
|
|
||||||
|
#### Limits
|
||||||
|
|
||||||
|
CPU and memory limits for the postgres container.
|
||||||
|
|
||||||
|
* **cpu**
|
||||||
|
CPU limits for the postgres container. Optional, overrides the
|
||||||
|
`default_cpu_limits` operator configuration parameter. Optional.
|
||||||
|
|
||||||
|
* **memory**
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
under the `clone` top-level key and do not affect the already running cluster.
|
||||||
|
|
||||||
|
* **cluster**
|
||||||
|
name of the cluster to clone from. Translated to either the service name or
|
||||||
|
the key inside the S3 bucket containing base backups. Required when the
|
||||||
|
`clone` section is present.
|
||||||
|
|
||||||
|
* **uid**
|
||||||
|
Kubernetes UID of the cluster to clone from. Since cluster name is not a
|
||||||
|
unique identifier of the cluster (as identically named clusters may exist in
|
||||||
|
different namespaces) , the operator uses UID in the S3 bucket name in order
|
||||||
|
to guarantee uniqueness. Has no effect when cloning from the running
|
||||||
|
clusters. Optional.
|
||||||
|
|
||||||
|
* **timestamp**
|
||||||
|
the timestamp up to which the recovery should proceed. The operator always
|
||||||
|
configures non-inclusive recovery target, stopping right before the given
|
||||||
|
timestamp. When this parameter is set the operator will not consider cloning
|
||||||
|
from the live cluster, even if it is running, and instead goes to S3. Optional.
|
||||||
|
|
||||||
|
### EBS volume resizing
|
||||||
|
|
||||||
|
Those parameters are grouped under the `volume` top-level key and define the
|
||||||
|
properties of the persistent storage that stores postgres data.
|
||||||
|
|
||||||
|
* **size**
|
||||||
|
the size of the target EBS volume. Usual Kubernetes size modifiers, i.e. `Gi`
|
||||||
|
or `Mi`, apply. Required.
|
||||||
|
|
||||||
|
* **storageClass**
|
||||||
|
the name of the Kubernetes storage class to draw the persistent volume from.
|
||||||
|
See [Kubernetes
|
||||||
|
documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/)
|
||||||
|
for the details on storage classes. Optional.
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -0,0 +1,301 @@
|
||||||
|
|
||||||
|
Postgres operator is configured via a ConfigMap defined by the
|
||||||
|
`CONFIG_MAP_NAME` environment variable. Variable names are underscore-separated
|
||||||
|
words.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
Kubernetes-native DCS).
|
||||||
|
|
||||||
|
* **docker_image**
|
||||||
|
Spilo docker image for postgres instances. For production, don't rely on the
|
||||||
|
default image, as it might be not the most up-to-date one. Instead, build
|
||||||
|
your own Spilo image from the [github
|
||||||
|
repository](https://github.com/zalando/spilo).
|
||||||
|
|
||||||
|
* **workers**
|
||||||
|
number of working routines the operator spawns to process requests to
|
||||||
|
create/update/delete/sync clusters concurrently. The default is `4`.
|
||||||
|
|
||||||
|
* **max_instances**
|
||||||
|
operator will cap the number of instances in any managed postgres cluster up
|
||||||
|
to the value of this parameter. When `-1` is specified, no limits are applied.
|
||||||
|
The default is `-1`.
|
||||||
|
|
||||||
|
* **min_instances**
|
||||||
|
operator will run at least the number of instances for any given postgres
|
||||||
|
cluster equal to the value of this parameter. When `-1` is specified, no limits
|
||||||
|
are applied. The default is `-1`.
|
||||||
|
|
||||||
|
* **resync_period**
|
||||||
|
period between consecutive sync requests. The default is `5m`.
|
||||||
|
|
||||||
|
## Postgres users
|
||||||
|
* **super_username**
|
||||||
|
postgres `superuser` name to be created by `initdb`. The default is
|
||||||
|
`postgres`.
|
||||||
|
|
||||||
|
* **replication_username**
|
||||||
|
postgres username used for replication between instances. The default is
|
||||||
|
`standby`.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
not used, because Patroni keeps pod labels in sync with the instance role.
|
||||||
|
The default is `operator`.
|
||||||
|
|
||||||
|
* **pod_service_account_definition**
|
||||||
|
The operator tries to create the pod Service Account in the namespace that
|
||||||
|
doesn't define such an account using the YAML definition provided by this
|
||||||
|
option. If not defined, a simple definition that contains only the name will
|
||||||
|
be used. The default is empty.
|
||||||
|
|
||||||
|
* **pod_terminate_grace_period**
|
||||||
|
Patroni pods are [terminated
|
||||||
|
forcefully](https://kubernetes.io/docs/concepts/workloads/pods/pod/#termination-of-pods)
|
||||||
|
after this timeout. The default is `5m`.
|
||||||
|
|
||||||
|
* **watched_namespace**
|
||||||
|
The operator watches for postgres objects in the given namespace. If not
|
||||||
|
specified, the value is taken from the operator namespace. A special `*`
|
||||||
|
value makes it watch all namespaces. The default is empty (watch the operator pod
|
||||||
|
namespace).
|
||||||
|
|
||||||
|
* **pdb_name_format**
|
||||||
|
defines the template for PDB (Pod Disruption Budget) names created by the
|
||||||
|
operator. The default is `postgres-{cluster}-pdb`, where `{cluster}` is
|
||||||
|
replaced by the cluster name. Only the `{cluster}` placeholders is allowed in
|
||||||
|
the template.
|
||||||
|
|
||||||
|
* **secret_name_template**
|
||||||
|
a template for the name of the database user secrets generated by the
|
||||||
|
operator. `{username}` is replaced with name of the secret, `{cluster}` with
|
||||||
|
the name of the cluster, `{tprkind}` with the kind of CRD (formerly known as
|
||||||
|
TPR) and `{tprgroup}` with the group of the CRD. No other placeholders are
|
||||||
|
allowed. The default is
|
||||||
|
`{username}.{cluster}.credentials.{tprkind}.{tprgroup}`.
|
||||||
|
|
||||||
|
* **oauth_token_secret_name**
|
||||||
|
a name of the secret containing the `OAuth2` token to pass to the teams API.
|
||||||
|
The default is `postgresql-operator`.
|
||||||
|
|
||||||
|
* **infrastructure_roles_secret_name**
|
||||||
|
name of the secret containing infrastructure roles names and passwords.
|
||||||
|
|
||||||
|
* **pod_role_label**
|
||||||
|
name of the label assigned to the postgres pods (and services/endpoints) by
|
||||||
|
the operator. The default is `spilo-role`.
|
||||||
|
|
||||||
|
* **cluster_labels**
|
||||||
|
list of `name:value` pairs for additional labels assigned to the cluster
|
||||||
|
objects. The default is `application:spilo`.
|
||||||
|
|
||||||
|
* **cluster_name_label**
|
||||||
|
name of the label assigned to Kubernetes objects created by the operator that
|
||||||
|
indicates which cluster a given object belongs to. The default is
|
||||||
|
`cluster-name`.
|
||||||
|
|
||||||
|
* **node_readiness_label**
|
||||||
|
a set of labels that a running and active node should possess to be
|
||||||
|
considered `ready`. The operator uses values of those labels to detect the
|
||||||
|
start of the Kubernetes cluster upgrade procedure and move master pods off
|
||||||
|
the nodes to be decommissioned. When the set is not empty, the operator also
|
||||||
|
assigns the `Affinity` clause to the postgres pods to be scheduled only on
|
||||||
|
`ready` nodes. The default is empty.
|
||||||
|
|
||||||
|
* **toleration**
|
||||||
|
a dictionary that should contain `key`, `operator`, `value` and
|
||||||
|
`effect` keys. In that case, the operator defines a pod toleration
|
||||||
|
according to the values of those keys. See [kubernetes
|
||||||
|
documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
|
||||||
|
for details on taints and tolerations. The default is empty.
|
||||||
|
|
||||||
|
* **pod_environment_configmap**
|
||||||
|
a name of the ConfigMap with environment variables to populate on every pod.
|
||||||
|
Right now this ConfigMap is searched in the namespace of the postgres cluster.
|
||||||
|
All variables from that ConfigMap are injected to the pod's environment, on
|
||||||
|
conflicts they are overridden by the environment variables generated by the
|
||||||
|
operator. The default is empty.
|
||||||
|
|
||||||
|
## Kubernetes resource requests
|
||||||
|
* **default_cpu_request**
|
||||||
|
CPU request value for the postgres containers, unless overridden by
|
||||||
|
cluster-specific settings. The default is `100m`.
|
||||||
|
|
||||||
|
* **default_memory_request**
|
||||||
|
memory request value for the postgres containers, unless overridden by
|
||||||
|
cluster-specific settings. The default is `100Mi`.
|
||||||
|
|
||||||
|
* **default_cpu_limit**
|
||||||
|
CPU limits for the postgres containers, unless overridden by cluster-specific
|
||||||
|
settings. The default is `3`.
|
||||||
|
|
||||||
|
* **default_memory_limit**
|
||||||
|
memory limits for the postgres containers, unless overridden by cluster-specific
|
||||||
|
settings. The default is `1Gi`.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
default is `3s`.
|
||||||
|
|
||||||
|
* **resource_check_timeout**
|
||||||
|
timeout when waiting for the presence of a certain Kubernetes resource (i.e.
|
||||||
|
`StatefulSet` or `PodDisruptionBudget`) before declaring the operation
|
||||||
|
unsuccessful. The default is `10m`.
|
||||||
|
|
||||||
|
* **pod_label_wait_timeout**
|
||||||
|
timeout when waiting for the pod role and cluster labels. Bigger value gives
|
||||||
|
Patroni more time to start the instance; smaller makes the operator detect
|
||||||
|
possible issues faster. The default is `10m`.
|
||||||
|
|
||||||
|
* **pod_deletion_wait_timeout**
|
||||||
|
timeout when waiting for the pods to be deleted when removing the cluster or
|
||||||
|
recreating pods. The default is `10m`.
|
||||||
|
|
||||||
|
* **ready_wait_interval**
|
||||||
|
the interval between consecutive attempts waiting for the postgres CRD to be
|
||||||
|
created. The default is `5s`.
|
||||||
|
|
||||||
|
* **ready_wait_timeout**
|
||||||
|
the timeout for the complete postgres CRD creation. The default is `30s`.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
[external-dns](https://github.com/kubernetes-incubator/external-dns) and with
|
||||||
|
the cluster that has the load balancer enabled. The default is
|
||||||
|
`db.example.com`.
|
||||||
|
|
||||||
|
* **enable_master_load_balancer**
|
||||||
|
toggles service type load balancer pointing to the master pod of the cluster.
|
||||||
|
Can be overridden by individual cluster settings. The default is `true`.
|
||||||
|
|
||||||
|
* **enable_replica_load_balancer**
|
||||||
|
toggles service type load balancer pointing to the replica pod of the
|
||||||
|
cluster. Can be overridden by individual cluster settings. The default is
|
||||||
|
`false`.
|
||||||
|
|
||||||
|
* **master_dns_name_format** defines the DNS name string template for the
|
||||||
|
master load balancer cluster. The default is
|
||||||
|
`{cluster}.{team}.{hostedzone}`, where `{cluster}` is replaced by the cluster
|
||||||
|
name, `{team}` is replaced with the team name and `{hostedzone}` is replaced
|
||||||
|
with the hosted zone (the value of the `db_hosted_zone` parameter). No other
|
||||||
|
placeholders are allowed.
|
||||||
|
|
||||||
|
** **replica_dns_name_format** defines the DNS name string template for the
|
||||||
|
replica load balancer cluster. The default is
|
||||||
|
`{cluster}-repl.{team}.{hostedzone}`, where `{cluster}` is replaced by the
|
||||||
|
cluster name, `{team}` is replaced with the team name and `{hostedzone}` is
|
||||||
|
replaced with the hosted zone (the value of the `db_hosted_zone` parameter).
|
||||||
|
No other placeholders are allowed.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
services by Spilo are S3 and GCS. The default is empty.
|
||||||
|
|
||||||
|
* **log_s3_bucket**
|
||||||
|
S3 bucket to use for shipping postgres daily logs. Works only with S3 on AWS.
|
||||||
|
The bucket has to be present and accessible by Patroni managed pods. At the
|
||||||
|
moment Spilo does not yet support this. The default is empty.
|
||||||
|
|
||||||
|
* **kube_iam_role**
|
||||||
|
AWS IAM role to supply in the `iam.amazonaws.com/role` annotation of Patroni
|
||||||
|
pods. Only used when combined with
|
||||||
|
[kube2iam](https://github.com/jtblin/kube2iam) project on AWS. The default is empty.
|
||||||
|
|
||||||
|
## Debugging the operator
|
||||||
|
* **debug_logging**
|
||||||
|
boolean parameter that toggles verbose debug logs from the operator. The
|
||||||
|
default is `true`.
|
||||||
|
|
||||||
|
* **enable_db_access**
|
||||||
|
boolean parameter that toggles the functionality of the operator that require
|
||||||
|
access to the postgres database, i.e. creating databases and users. The default
|
||||||
|
is `true`.
|
||||||
|
|
||||||
|
### Automatic creation of human users in the database
|
||||||
|
* **enable_teams_api**
|
||||||
|
boolean parameter that toggles usage of the Teams API by the operator.
|
||||||
|
The default is `true`.
|
||||||
|
|
||||||
|
* **teams_api_url**
|
||||||
|
contains the URL of the Teams API service. There is a [demo
|
||||||
|
implementation](https://github.com/ikitiki/fake-teams-api). The default is
|
||||||
|
`https://teams.example.com/api/`.
|
||||||
|
|
||||||
|
* **team_api_role_configuration**
|
||||||
|
postgres parameters to apply to each team member role. The default is
|
||||||
|
'*log_statement:all*'. It is possible to supply multiple options, separating
|
||||||
|
them by commas. Options containing commas within the value are not supported,
|
||||||
|
with the exception of the `search_path`. For instance:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
teams_api_role_configuration: "log_statement:all,search_path:'data,public'"
|
||||||
|
```
|
||||||
|
The default is `"log_statement:all"`
|
||||||
|
|
||||||
|
* **enable_team_superuser**
|
||||||
|
whether to grant superuser to team members created from the Teams API.
|
||||||
|
The default is `false`.
|
||||||
|
|
||||||
|
* **team_admin_role**
|
||||||
|
role name to grant to team members created from the Teams API. The default is
|
||||||
|
`admin`, that role is created by Spilo as a `NOLOGIN` role.
|
||||||
|
|
||||||
|
* **pam_role_name**
|
||||||
|
when set, the operator will add all team member roles to this group and add a
|
||||||
|
`pg_hba` line to authenticate members of that role via `pam`. The default is
|
||||||
|
`zalandos`.
|
||||||
|
|
||||||
|
* **pam_configuration**
|
||||||
|
when set, should contain a URL to use for authentication against the username
|
||||||
|
and the token supplied as the password. Used in conjunction with
|
||||||
|
[pam_oauth2](https://github.com/CyberDem0n/pam-oauth2) module. The default is
|
||||||
|
`https://info.example.com/oauth2/tokeninfo?access_token= uid
|
||||||
|
realm=/employees`.
|
||||||
|
|
||||||
|
* **protected_roles**
|
||||||
|
List of roles that cannot be overwritten by an application, team or
|
||||||
|
infrastructure role. The default is `admin`.
|
||||||
|
|
||||||
|
## Logging and REST API
|
||||||
|
* **api_port**
|
||||||
|
REST API listener listens to this port. The default is `8080`.
|
||||||
|
|
||||||
|
* **ring_log_lines**
|
||||||
|
number of lines in the ring buffer used to store cluster logs. The default is `100`.
|
||||||
|
|
||||||
|
* **cluster_history_entries**
|
||||||
|
number of entries in the cluster history ring buffer. The default is `1000`.
|
||||||
|
|
||||||
|
## Scalyr options
|
||||||
|
* **scalyr_api_key**
|
||||||
|
API key for the Scalyr sidecar. The default is empty.
|
||||||
|
|
||||||
|
* **scalyr_image**
|
||||||
|
Docker image for the Scalyr sidecar. The default is empty.
|
||||||
|
|
||||||
|
* **scalyr_server_url**
|
||||||
|
server URL for the Scalyr sidecar. The default is `https://upload.eu.scalyr.com`.
|
||||||
|
|
||||||
|
* **scalyr_cpu_request**
|
||||||
|
CPU request value for the Scalyr sidecar. The default is `100m`.
|
||||||
|
|
||||||
|
* **scalyr_memory_request**
|
||||||
|
Memory request value for the Scalyr sidecar. The default is `50Mi`.
|
||||||
|
|
||||||
|
* **scalyr_cpu_limit**
|
||||||
|
CPU limit value for the Scalyr sidecar. The default is `1`.
|
||||||
|
|
||||||
|
* **scalyr_memory_limit**
|
||||||
|
Memory limit value for the Scalyr sidecar. The default is `1Gi`.
|
||||||
|
|
||||||
49
docs/user.md
49
docs/user.md
|
|
@ -1,9 +1,7 @@
|
||||||
# How to create a new PostgreSQL cluster
|
|
||||||
|
|
||||||
## Create a manifest for a new PostgreSQL cluster
|
## Create a manifest for a new PostgreSQL cluster
|
||||||
|
|
||||||
As an example you can take this
|
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
|
```yaml
|
||||||
apiVersion: "acid.zalan.do/v1"
|
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
|
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
|
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
|
### Clone from S3
|
||||||
|
|
||||||
|
|
@ -274,3 +272,40 @@ are always passed to sidecars:
|
||||||
- `POSTGRES_PASSWORD` - the password for the superuser
|
- `POSTGRES_PASSWORD` - the password for the superuser
|
||||||
|
|
||||||
The PostgreSQL volume is shared with sidecars and is mounted at `/home/postgres/pgdata`.
|
The PostgreSQL volume is shared with sidecars and is mounted at `/home/postgres/pgdata`.
|
||||||
|
|
||||||
|
## Increase volume size
|
||||||
|
|
||||||
|
PostgreSQL operator supports statefulset volume resize if you're using the
|
||||||
|
operator on top of AWS. For that you need to change the size field of the
|
||||||
|
volume description in the cluster manifest and apply the change:
|
||||||
|
|
||||||
|
```
|
||||||
|
apiVersion: "acid.zalan.do/v1"
|
||||||
|
kind: postgresql
|
||||||
|
|
||||||
|
metadata:
|
||||||
|
name: acid-test-cluster
|
||||||
|
spec:
|
||||||
|
volume:
|
||||||
|
size: 5Gi # new volume size
|
||||||
|
```
|
||||||
|
|
||||||
|
The operator compares the new value of the size field with the previous one and
|
||||||
|
acts on differences.
|
||||||
|
|
||||||
|
You can only enlarge the volume with the process described above, shrinking is
|
||||||
|
not supported and will emit a warning. After this update all the new volumes in
|
||||||
|
the statefulset are allocated according to the new size. To enlarge persistent
|
||||||
|
volumes attached to the running pods, the operator performs the following
|
||||||
|
actions:
|
||||||
|
|
||||||
|
* call AWS API to change the volume size
|
||||||
|
|
||||||
|
* connect to the pod using `kubectl exec` and resize the filesystem with
|
||||||
|
`resize2fs`.
|
||||||
|
|
||||||
|
Fist step has a limitation, AWS rate-limits this operation to no more than once
|
||||||
|
every 6 hours.
|
||||||
|
Note that if the statefulset is scaled down before resizing the size changes
|
||||||
|
are only applied to the volumes attached to the running pods. The size of the
|
||||||
|
volumes that correspond to the previously running pods is not changed.
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -76,7 +76,6 @@ type Config struct {
|
||||||
// value of this string must be valid JSON or YAML; see initPodServiceAccount
|
// value of this string must be valid JSON or YAML; see initPodServiceAccount
|
||||||
PodServiceAccountDefinition string `name:"pod_service_account_definition" default:""`
|
PodServiceAccountDefinition string `name:"pod_service_account_definition" default:""`
|
||||||
DbHostedZone string `name:"db_hosted_zone" default:"db.example.com"`
|
DbHostedZone string `name:"db_hosted_zone" default:"db.example.com"`
|
||||||
EtcdScope string `name:"etcd_scope" default:"service"`
|
|
||||||
WALES3Bucket string `name:"wal_s3_bucket"`
|
WALES3Bucket string `name:"wal_s3_bucket"`
|
||||||
LogS3Bucket string `name:"log_s3_bucket"`
|
LogS3Bucket string `name:"log_s3_bucket"`
|
||||||
KubeIAMRole string `name:"kube_iam_role"`
|
KubeIAMRole string `name:"kube_iam_role"`
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue