Skip to content

Commit b518a31

Browse files
alexeyklyukinalexeyklyukin
authored
Document cluster manifests. (zalando#320)
Document cluster manifests options. Review by @erthalion and @zerg-junior.
1 parent 9cb48e0 commit b518a31

File tree

1 file changed

+218
-0
lines changed

1 file changed

+218
-0
lines changed

‎docs/cluster_manifest.md

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
Postgres Cluster Manifest
2+
=========================
3+
4+
Individual postgres clusters are described by the Kubernetes *cluster manifest*
5+
that has the structure defined by the `postgres CRD` (custom resource
6+
definition). The following section describes the structure of the manifest and
7+
the purpose of individual keys. You can take a look at the examples of the
8+
[minimal](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/minimal-postgres-manifest.yaml)
9+
and the
10+
[complete](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/complete-postgres-manifest.yaml)
11+
cluster manifests.
12+
13+
When Kubernetes resources, such as memory, CPU or volumes, are configured,
14+
their amount is usually described as a string together with the units of
15+
measurements. Please, refer to the [Kubernetes
16+
documentation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
17+
for the possible values of those.
18+
19+
Manifest structure
20+
------------------
21+
22+
A postgres manifest is a `YAML` document. On the top level both individual
23+
parameters and parameter groups can be defined. Parameter names are written
24+
in camelCase.
25+
26+
### Cluster metadata
27+
28+
Those parameters are grouped under the `metadata` top-level key.
29+
30+
* **name**
31+
the name of the cluster. Must start with the `teamId` followed by a dash.
32+
Changing it after the cluster creation is not supported. Required field.
33+
34+
* **namespace**
35+
the namespace where the operator creates Kubernetes objects (i.e. pods,
36+
services, secrets) for the cluster. Changing it after the cluster creation
37+
results in deploying or updating a completely separate cluster in the target
38+
namespace. Optional (if present, should match the namespace where the
39+
manifest is applied).
40+
41+
### Top-level parameters
42+
43+
Those are parameters grouped directly under the `spec` key in the manifest.
44+
45+
* **teamId**
46+
name of the team the cluster belongs to. Changing it after the cluster
47+
creation is not supported. Required field.
48+
49+
* **dockerImage**
50+
custom docker image that overrides the **docker_image** operator parameter.
51+
It should be a [Spilo](https://github.com/zalando/spilo) image. Optional.
52+
53+
* **enableMasterLoadBalancer**
54+
boolean flag to override the operator defaults (set by the
55+
`enable_master_load_balancer` parameter) to define whether to enable the load
56+
balancer pointing to the postgres primary. Optional.
57+
58+
* **enableReplicaLoadBalancer**
59+
boolean flag to override the operator defaults (set by the
60+
`enable_replica_load_balancer` parameter) to define whether to enable the
61+
load balancer pointing to the postgres standby instances. Optional.
62+
63+
* **allowedSourceRanges**
64+
when one or more load balancers are enabled for the cluster, this parameter
65+
defines the comma-separated range of IP networks (in CIDR-notation). The
66+
corresponding load balancer is accessible only to the networks defined by
67+
this parameter. Optional, when empty the load balancer service becomes
68+
inaccessible from outside of the Kubernetes cluster.
69+
70+
* **numberOfInstances**
71+
total number of instances for a given cluster. The operator parameters
72+
`max_instances` and `min_instances` may also adjust this number. Required
73+
field.
74+
75+
* **users**
76+
a map of usernames to user flags for the users that should be created in the
77+
cluster by the operator. User flags are a list, allowed elements are
78+
`SUPERUSER` `REPLICATION` `INHERIT`, `LOGIN`, `NOLOGIN`, `CREATEROLE`,
79+
`CREATEDB`, `BYPASSURL`. A login user is created by default unless NOLOGIN is
80+
specified, in which case the operator creates a role. One can specify empty
81+
flags by providing a JSON empty array '*[]*'. Optional.
82+
83+
* **databases**
84+
a map of database names to database owners for the databases that should be
85+
created by the operator. The owner users should already exist on the cluster
86+
(i.e. mentioned in the `user` parameter). Optional.
87+
88+
* **tolerations**
89+
a list of tolerations that apply to the cluster pods. Each element of that
90+
list is a dictionary with the following fields: `key`, `operator`, `value`,
91+
`effect` and `tolerationSeconds`. Each field is optional. See [Kubernetes
92+
examples](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
93+
for details on tolerations and possible values of those keys. When set, this
94+
value overrides the `pod_toleration` setting from the operator. Optional.
95+
96+
### Postgres parameters
97+
98+
Those parameters are grouped under the `postgresql` top-level key.
99+
100+
* **version**
101+
the postgres major version of the cluster. Looks at the [Spilo
102+
project](https://github.com/zalando/spilo/releases) for the list of supported
103+
versions. Changing the cluster version once the cluster has been bootstrapped
104+
is not supported. Required field.
105+
106+
* **parameters**
107+
a dictionary of postgres parameter names and values to apply to the resulting
108+
cluster. Optional (Spilo automatically sets reasonable defaults for
109+
parameters like work_mem or max_connections).
110+
111+
### Patroni parameters
112+
113+
Those parameters are grouped under the `patroni` top-level key. See the [patroni
114+
documentation](https://patroni.readthedocs.io/en/latest/SETTINGS.html) for the
115+
explanation of `ttl` and `loop_wait` parameters.
116+
117+
* **initdb**
118+
a map of key-value pairs describing initdb parameters. For `data-checksum`,
119+
`debug`, `no-locale`, `noclean`, `nosync` and `sync-only` parameters use
120+
`true` as the value if you want to set them. Changes to this option do not
121+
affect the already initialized clusters. Optional.
122+
123+
* **pg_hba**
124+
list of custom `pg_hba` lines to replace default ones. Note that the default
125+
ones include
126+
127+
```
128+
hostsll all +pamrole all pam
129+
```
130+
, where pamrole is the name of the role for the pam authentication; any
131+
custom `pg_hba` should include the pam line to avoid breaking pam
132+
authentication. Optional.
133+
134+
* **ttl**
135+
patroni `ttl` parameter value, optional. The default is set by the Spilo
136+
docker image. Optional.
137+
138+
* **loop_wait**
139+
patroni `loop_wait` parameter value, optional. The default is set by the
140+
Spilo docker image. Optional.
141+
142+
* **retry_timeout**
143+
patroni `retry_timeout` parameter value, optional. The default is set by the
144+
Spilo docker image. Optional.
145+
146+
* **maximum_lag_on_failover**
147+
patroni `maximum_lag_on_failover` parameter value, optional. The default is
148+
set by the Spilo docker image. Optional.
149+
150+
### Postgres container resources
151+
152+
Those parameters define [CPU and memory requests and
153+
limits](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
154+
for the postgres container. They are grouped under the `resources` top-level
155+
key. There are two subgroups, `requests` and `limits`.
156+
157+
#### Requests
158+
159+
CPU and memory requests for the postgres container.
160+
161+
* **cpu**
162+
CPU requests for the postgres container. Optional, overrides the
163+
`default_cpu_requests` operator configuration parameter. Optional.
164+
165+
* **memory**
166+
memory requests for the postgres container. Optional, overrides the
167+
`default_memory_request` operator configuration parameter. Optional.
168+
169+
#### Limits
170+
171+
CPU and memory limits for the postgres container.
172+
173+
* **cpu**
174+
CPU limits for the postgres container. Optional, overrides the
175+
`default_cpu_limits` operator configuration parameter. Optional.
176+
177+
* **memory**
178+
memory limits for the postgres container. Optional, overrides the
179+
`default_memory_limits` operator configuration parameter. Optional.
180+
181+
### Parameters defining how to clone the cluster from another one
182+
183+
Those parameters are applied when the cluster should be a clone of another one
184+
that is either already running or has a basebackup on S3. They are grouped
185+
under the `clone` top-level key and do not affect the already running cluster.
186+
187+
* **cluster**
188+
name of the cluster to clone from. Translated to either the service name or
189+
the key inside the S3 bucket containing base backups. Required when the
190+
`clone` section is present.
191+
192+
* **uid**
193+
Kubernetes UID of the cluster to clone from. Since cluster name is not a
194+
unique identifier of the cluster (as identically named clusters may exist in
195+
different namespaces) , the operator uses UID in the S3 bucket name in order
196+
to guarantee uniqueness. Has no effect when cloning from the running
197+
clusters. Optional.
198+
199+
* **timestamp**
200+
the timestamp up to which the recovery should proceed. The operator always
201+
configures non-inclusive recovery target, stopping right before the given
202+
timestamp. When this parameter is set the operator will not consider cloning
203+
from the live cluster, even if it is running, and instead goes to S3. Optional.
204+
205+
### EBS volume resizing
206+
207+
Those parameters are grouped under the `volume` top-level key and define the
208+
properties of the persistent storage that stores postgres data.
209+
210+
* **size**
211+
the size of the target EBS volume. Usual Kubernetes size modifiers, i.e. `Gi`
212+
or `Mi`, apply. Required.
213+
214+
* **storageClass**
215+
the name of the Kubernetes storage class to draw the persistent volume from.
216+
See [Kubernetes
217+
documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/)
218+
for the details on storage classes. Optional.

0 commit comments

Comments
 (0)