Skip to content

Commit 9cb48e0

Browse files
alexeyklyukinalexeyklyukin
authored
Document operator configuration parameters. (zalando#313)
1 parent c26962b commit 9cb48e0

File tree

2 files changed

+306
-1
lines changed

2 files changed

+306
-1
lines changed

‎docs/operator_parameters.md

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
Postgres Operator Configuration
2+
===============================
3+
4+
Postgres operator is configured via a ConfigMap defined by the
5+
`CONFIG_MAP_NAME` environment variable. Variable names are underscore-separated
6+
words.
7+
8+
Available Configuration Parameters
9+
----------------------------------
10+
11+
### General
12+
* **etcd_host**
13+
Etcd connection string for Patroni defined as `host:port`. Not required when
14+
Patroni native Kubernetes support is used. The default is empty (use
15+
Kubernetes-native DCS).
16+
17+
* **docker_image**
18+
Spilo docker image for postgres instances. For production, don't rely on the
19+
default image, as it might be not the most up-to-date one. Instead, build
20+
your own Spilo image from the [github
21+
repository](https://github.com/zalando/spilo).
22+
23+
* **workers**
24+
number of working routines the operator spawns to process requests to
25+
create/update/delete/sync clusters concurrently. The default is `4`.
26+
27+
* **max_instances**
28+
operator will cap the number of instances in any managed postgres cluster up
29+
to the value of this parameter. When `-1` is specified, no limits are applied.
30+
The default is `-1`.
31+
32+
* **min_instances**
33+
operator will run at least the number of instances for any given postgres
34+
cluster equal to the value of this parameter. When `-1` is specified, no limits
35+
are applied. The default is `-1`.
36+
37+
* **resync_period**
38+
period between consecutive sync requests. The default is `5m`.
39+
40+
### Postgres users
41+
* **super_username**
42+
postgres `superuser` name to be created by `initdb`. The default is
43+
`postgres`.
44+
45+
* **replication_username**
46+
postgres username used for replication between instances. The default is
47+
`standby`.
48+
49+
### Kubernetes resources
50+
* **pod_service_account_name**
51+
service account used by Patroni running on individual Pods to communicate
52+
with the operator. Required even if native Kubernetes support in Patroni is
53+
not used, because Patroni keeps pod labels in sync with the instance role.
54+
The default is `operator`.
55+
56+
* **pod_service_account_definition**
57+
The operator tries to create the pod Service Account in the namespace that
58+
doesn't define such an account using the YAML definition provided by this
59+
option. If not defined, a simple definition that contains only the name will
60+
be used. The default is empty.
61+
62+
* **pod_terminate_grace_period**
63+
Patroni pods are [terminated
64+
forcefully](https://kubernetes.io/docs/concepts/workloads/pods/pod/#termination-of-pods)
65+
after this timeout. The default is `5m`.
66+
67+
* **watched_namespace**
68+
The operator watches for postgres objects in the given namespace. If not
69+
specified, the value is taken from the operator namespace. A special `*`
70+
value makes it watch all namespaces. The default is empty (watch the operator pod
71+
namespace).
72+
73+
* **pdb_name_format**
74+
defines the template for PDB (Pod Disruption Budget) names created by the
75+
operator. The default is `postgres-{cluster}-pdb`, where `{cluster}` is
76+
replaced by the cluster name. Only the `{cluster}` placeholders is allowed in
77+
the template.
78+
79+
* **secret_name_template**
80+
a template for the name of the database user secrets generated by the
81+
operator. `{username}` is replaced with name of the secret, `{cluster}` with
82+
the name of the cluster, `{tprkind}` with the kind of CRD (formerly known as
83+
TPR) and `{tprgroup}` with the group of the CRD. No other placeholders are
84+
allowed. The default is
85+
`{username}.{cluster}.credentials.{tprkind}.{tprgroup}`.
86+
87+
* **oauth_token_secret_name**
88+
a name of the secret containing the `OAuth2` token to pass to the teams API.
89+
The default is `postgresql-operator`.
90+
91+
* **infrastructure_roles_secret_name**
92+
name of the secret containing infrastructure roles names and passwords.
93+
94+
* **pod_role_label**
95+
name of the label assigned to the postgres pods (and services/endpoints) by
96+
the operator. The default is `spilo-role`.
97+
98+
* **cluster_labels**
99+
list of `name:value` pairs for additional labels assigned to the cluster
100+
objects. The default is `application:spilo`.
101+
102+
* **cluster_name_label**
103+
name of the label assigned to Kubernetes objects created by the operator that
104+
indicates which cluster a given object belongs to. The default is
105+
`cluster-name`.
106+
107+
* **node_readiness_label**
108+
a set of labels that a running and active node should possess to be
109+
considered `ready`. The operator uses values of those labels to detect the
110+
start of the Kubernetes cluster upgrade procedure and move master pods off
111+
the nodes to be decommissioned. When the set is not empty, the operator also
112+
assigns the `Affinity` clause to the postgres pods to be scheduled only on
113+
`ready` nodes. The default is empty.
114+
115+
* **toleration**
116+
a dictionary that should contain `key`, `operator`, `value` and
117+
`effect` keys. In that case, the operator defines a pod toleration
118+
according to the values of those keys. See [kubernetes
119+
documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
120+
for details on taints and tolerations. The default is empty.
121+
122+
* **pod_environment_configmap**
123+
a name of the ConfigMap with environment variables to populate on every pod.
124+
Right now this ConfigMap is searched in the namespace of the postgres cluster.
125+
All variables from that ConfigMap are injected to the pod's environment, on
126+
conflicts they are overridden by the environment variables generated by the
127+
operator. The default is empty.
128+
129+
### Kubernetes resource requests
130+
* **default_cpu_request**
131+
CPU request value for the postgres containers, unless overridden by
132+
cluster-specific settings. The default is `100m`.
133+
134+
* **default_memory_request**
135+
memory request value for the postgres containers, unless overridden by
136+
cluster-specific settings. The default is `100Mi`.
137+
138+
* **default_cpu_limit**
139+
CPU limits for the postgres containers, unless overridden by cluster-specific
140+
settings. The default is `3`.
141+
142+
* **default_memory_limit**
143+
memory limits for the postgres containers, unless overridden by cluster-specific
144+
settings. The default is `1Gi`.
145+
146+
### Operator timeouts
147+
* **resource_check_interval**
148+
interval to wait between consecutive attempts to check for the presence of
149+
some Kubernetes resource (i.e. `StatefulSet` or `PodDisruptionBudget`). The
150+
default is `3s`.
151+
152+
* **resource_check_timeout**
153+
timeout when waiting for the presence of a certain Kubernetes resource (i.e.
154+
`StatefulSet` or `PodDisruptionBudget`) before declaring the operation
155+
unsuccessful. The default is `10m`.
156+
157+
* **pod_label_wait_timeout**
158+
timeout when waiting for the pod role and cluster labels. Bigger value gives
159+
Patroni more time to start the instance; smaller makes the operator detect
160+
possible issues faster. The default is `10m`.
161+
162+
* **pod_deletion_wait_timeout**
163+
timeout when waiting for the pods to be deleted when removing the cluster or
164+
recreating pods. The default is `10m`.
165+
166+
* **ready_wait_interval**
167+
the interval between consecutive attempts waiting for the postgres CRD to be
168+
created. The default is `5s`.
169+
170+
* **ready_wait_timeout**
171+
the timeout for the complete postgres CRD creation. The default is `30s`.
172+
173+
### Load balancer related options
174+
* **db_hosted_zone**
175+
DNS zone for the cluster DNS name when the load balancer is configured for
176+
the cluster. Only used when combined with
177+
[external-dns](https://github.com/kubernetes-incubator/external-dns) and with
178+
the cluster that has the load balancer enabled. The default is
179+
`db.example.com`.
180+
181+
* **enable_master_load_balancer**
182+
toggles service type load balancer pointing to the master pod of the cluster.
183+
Can be overridden by individual cluster settings. The default is `true`.
184+
185+
* **enable_replica_load_balancer**
186+
toggles service type load balancer pointing to the replica pod of the
187+
cluster. Can be overridden by individual cluster settings. The default is
188+
`false`.
189+
190+
* **master_dns_name_format** defines the DNS name string template for the
191+
master load balancer cluster. The default is
192+
`{cluster}.{team}.{hostedzone}`, where `{cluster}` is replaced by the cluster
193+
name, `{team}` is replaced with the team name and `{hostedzone}` is replaced
194+
with the hosted zone (the value of the `db_hosted_zone` parameter). No other
195+
placeholders are allowed.
196+
197+
** **replica_dns_name_format** defines the DNS name string template for the
198+
replica load balancer cluster. The default is
199+
`{cluster}-repl.{team}.{hostedzone}`, where `{cluster}` is replaced by the
200+
cluster name, `{team}` is replaced with the team name and `{hostedzone}` is
201+
replaced with the hosted zone (the value of the `db_hosted_zone` parameter).
202+
No other placeholders are allowed.
203+
204+
### AWS or GSC interaction
205+
* **wal_s3_bucket**
206+
S3 bucket to use for shipping WAL segments with WAL-E. A bucket has to be
207+
present and accessible by Patroni managed pods. At the moment, supported
208+
services by Spilo are S3 and GCS. The default is empty.
209+
210+
* **log_s3_bucket**
211+
S3 bucket to use for shipping postgres daily logs. Works only with S3 on AWS.
212+
The bucket has to be present and accessible by Patroni managed pods. At the
213+
moment Spilo does not yet support this. The default is empty.
214+
215+
* **kube_iam_role**
216+
AWS IAM role to supply in the `iam.amazonaws.com/role` annotation of Patroni
217+
pods. Only used when combined with
218+
[kube2iam](https://github.com/jtblin/kube2iam) project on AWS. The default is empty.
219+
220+
### Debugging the operator
221+
* **debug_logging**
222+
boolean parameter that toggles verbose debug logs from the operator. The
223+
default is `true`.
224+
225+
* **enable_db_access**
226+
boolean parameter that toggles the functionality of the operator that require
227+
access to the postgres database, i.e. creating databases and users. The default
228+
is `true`.
229+
230+
### Automatic creation of human users in the database
231+
* **enable_teams_api**
232+
boolean parameter that toggles usage of the Teams API by the operator.
233+
The default is `true`.
234+
235+
* **teams_api_url**
236+
contains the URL of the Teams API service. There is a [demo
237+
implementation](https://github.com/ikitiki/fake-teams-api). The default is
238+
`https://teams.example.com/api/`.
239+
240+
* **team_api_role_configuration**
241+
postgres parameters to apply to each team member role. The default is
242+
'*log_statement:all*'. It is possible to supply multiple options, separating
243+
them by commas. Options containing commas within the value are not supported,
244+
with the exception of the `search_path`. For instance:
245+
246+
```yaml
247+
teams_api_role_configuration: "log_statement:all,search_path:'data,public'"
248+
```
249+
The default is `"log_statement:all"`
250+
251+
* **enable_team_superuser**
252+
whether to grant superuser to team members created from the Teams API.
253+
The default is `false`.
254+
255+
* **team_admin_role**
256+
role name to grant to team members created from the Teams API. The default is
257+
`admin`, that role is created by Spilo as a `NOLOGIN` role.
258+
259+
* **pam_role_name**
260+
when set, the operator will add all team member roles to this group and add a
261+
`pg_hba` line to authenticate members of that role via `pam`. The default is
262+
`zalandos`.
263+
264+
* **pam_configuration**
265+
when set, should contain a URL to use for authentication against the username
266+
and the token supplied as the password. Used in conjunction with
267+
[pam_oauth2](https://github.com/CyberDem0n/pam-oauth2) module. The default is
268+
`https://info.example.com/oauth2/tokeninfo?access_token= uid
269+
realm=/employees`.
270+
271+
* **protected_roles**
272+
List of roles that cannot be overwritten by an application, team or
273+
infrastructure role. The default is `admin`.
274+
275+
### Logging and REST API
276+
* **api_port**
277+
REST API listener listens to this port. The default is `8080`.
278+
279+
* **ring_log_lines**
280+
number of lines in the ring buffer used to store cluster logs. The default is `100`.
281+
282+
* **cluster_history_entries**
283+
number of entries in the cluster history ring buffer. The default is `1000`.
284+
285+
## Scalyr options
286+
* **scalyr_api_key**
287+
API key for the Scalyr sidecar. The default is empty.
288+
289+
* **scalyr_image**
290+
Docker image for the Scalyr sidecar. The default is empty.
291+
292+
* **scalyr_server_url**
293+
server URL for the Scalyr sidecar. The default is `https://upload.eu.scalyr.com`.
294+
295+
* **scalyr_cpu_request**
296+
CPU request value for the Scalyr sidecar. The default is `100m`.
297+
298+
* **scalyr_memory_request**
299+
Memory request value for the Scalyr sidecar. The default is `50Mi`.
300+
301+
* **scalyr_cpu_limit**
302+
CPU limit value for the Scalyr sidecar. The default is `1`.
303+
304+
* **scalyr_memory_limit**
305+
Memory limit value for the Scalyr sidecar. The default is `1Gi`.
306+

‎pkg/util/config/config.go

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,6 @@ type Config struct {
7676
// value of this string must be valid JSON or YAML; see initPodServiceAccount
7777
PodServiceAccountDefinition string `name:"pod_service_account_definition" default:""`
7878
DbHostedZone string `name:"db_hosted_zone" default:"db.example.com"`
79-
EtcdScope string `name:"etcd_scope" default:"service"`
8079
WALES3Bucket string `name:"wal_s3_bucket"`
8180
LogS3Bucket string `name:"log_s3_bucket"`
8281
KubeIAMRole string `name:"kube_iam_role"`

0 commit comments

Comments
 (0)