Document cluster manifests. (#320)
Document cluster manifests options. Review by @erthalion and @zerg-junior.
This commit is contained in:
Oleksii Kliukin
GitHub
parent
9cb48e0889
commit
b518a31d0c
|
|
@ -0,0 +1,218 @@
|
|||
Postgres Cluster Manifest
|
||||
=========================
|
||||
|
||||
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.
|
||||
Loading…
Reference in New Issue