From b518a31d0c19f6563281dba5c16854bf2462bc58 Mon Sep 17 00:00:00 2001 From: Oleksii Kliukin Date: Tue, 12 Jun 2018 11:57:00 +0200 Subject: [PATCH] Document cluster manifests. (#320) Document cluster manifests options. Review by @erthalion and @zerg-junior. --- docs/cluster_manifest.md | 218 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/cluster_manifest.md diff --git a/docs/cluster_manifest.md b/docs/cluster_manifest.md new file mode 100644 index 000000000..db7ce17c1 --- /dev/null +++ b/docs/cluster_manifest.md @@ -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.