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