operator_parameters.md

Configuration parameters

There are two mutually-exclusive methods to set the Postgres Operator configuration.

• ConfigMaps-based, the legacy one. The configuration is supplied in a key-value configmap, defined by the CONFIG_MAP_NAME environment variable. Non-scalar values, i.e. lists or maps, are encoded in the value strings using the comma-based syntax for lists and coma-separated key:value syntax for maps. String values containing ':' should be enclosed in quotes. The configuration is flat, parameter group names below are not reflected in the configuration structure. There is an example

• CRD-based configuration. The configuration is stored in a custom YAML manifest. The manifest is an instance of the custom resource definition (CRD) called OperatorConfiguration. The operator registers this CRD during the start and uses it for configuration if the operator deployment manifest sets the POSTGRES_OPERATOR_CONFIGURATION_OBJECT env variable to a non-empty value. The variable should point to the postgresql-operator-configuration object in the operator's namespace.

  The CRD-based configuration is a regular YAML document; non-scalar keys are simply represented in the usual YAML way. There are no default values built-in in the operator, each parameter that is not supplied in the configuration receives an empty value. In order to create your own configuration just copy the default one and change it.

  To test the CRD-based configuration locally, use the following

  kubectl create -f manifests/operatorconfiguration.crd.yaml # registers the CRD
  kubectl create -f manifests/postgresql-operator-default-configuration.yaml
  
  kubectl create -f manifests/operator-service-account-rbac.yaml
  kubectl create -f manifests/postgres-operator.yaml # set the env var as mentioned above
  
  kubectl get operatorconfigurations postgresql-operator-default-configuration -o yaml

The CRD-based configuration is more powerful than the one based on ConfigMaps and should be used unless there is a compatibility requirement to use an already existing configuration. Even in that case, it should be rather straightforward to convert the ConfigMap-based configuration into the CRD-based one and restart the operator. The ConfigMap-based configuration will be deprecated and subsequently removed in future releases.

Note that for the CRD-based configuration groups of configuration options below correspond to the non-leaf keys in the target YAML (i.e. for the Kubernetes resources the key is kubernetes). The key is mentioned alongside the group description. The ConfigMap-based configuration is flat and does not allow non-leaf keys.

Since in the CRD-based case the operator needs to create a CRD first, which is controlled by the resource_check_interval and resource_check_timeout parameters, those parameters have no effect and are replaced by the CRD_READY_WAIT_INTERVAL and CRD_READY_WAIT_TIMEOUT environment variables. They will be deprecated and removed in the future.

For the configmap configuration, the default parameter values mentioned here are likely to be overwritten in your local operator installation via your local version of the operator configmap. In the case you use the operator CRD, all the CRD defaults are provided in the operator's default configuration manifest

Variable names are underscore-separated words.

General

Those are top-level keys, containing both leaf keys and groups.

• enable_crd_validation toggles if the operator will create or update CRDs with OpenAPI v3 schema validation The default is true.

• enable_lazy_spilo_upgrade Instruct operator to update only the statefulsets with new images (Spilo and InitContainers) without immediately doing the rolling update. The assumption is pods will be re-started later with new images, for example due to the node rotation. The default is false.

• enable_pgversion_env_var With newer versions of Spilo, it is preferable to use PGVERSION pod environment variable instead of the setting postgresql.bin_dir in the SPILO_CONFIGURATION env variable. When this option is true, the operator sets PGVERSION and omits postgresql.bin_dir from SPILO_CONFIGURATION. When false, the postgresql.bin_dir is set. This setting takes precedence over PGVERSION; see PR 222 in Spilo. The default is true.

• enable_spilo_wal_path_compat enables backwards compatible path between Spilo 12 and Spilo 13 images. The default is false.

• etcd_host Etcd connection string for Patroni defined as host:port. Not required when Patroni native Kubernetes support is used. The default is empty (use Kubernetes-native DCS).

• kubernetes_use_configmaps Select if setup uses endpoints (default), or configmaps to manage leader when DCS is kubernetes (not etcd or similar). In OpenShift it is not possible to use endpoints option, and configmaps is required. By default, kubernetes_use_configmaps: false, meaning endpoints will be used.

• docker_image Spilo Docker image for Postgres instances. For production, don't rely on the default image, as it might be not the most up-to-date one. Instead, build your own Spilo image from the github repository.

• sidecar_docker_images deprecated: use sidecars instead. A map of sidecar names to Docker images to run with Spilo. In case of the name conflict with the definition in the cluster manifest the cluster-specific one is preferred.

• sidecars a list of sidecars to run with Spilo, for any cluster (i.e. globally defined sidecars). Each item in the list is of type Container. Globally defined sidecars can be overwritten by specifying a sidecar in the Postgres manifest with the same name. Note: This field is not part of the schema validation. If the container specification is invalid, then the operator fails to create the statefulset.

• enable_shm_volume Instruct operator to start any new database pod without limitations on shm memory. If this option is enabled, to the target database pod will be mounted a new tmpfs volume to remove shm memory limitation (see e.g. the docker issue). This option is global for an operator object, and can be overwritten by enableShmVolume parameter from Postgres manifest. The default is true.

• workers number of working routines the operator spawns to process requests to create/update/delete/sync clusters concurrently. The default is 8.

• max_instances operator will cap the number of instances in any managed Postgres cluster up to the value of this parameter. When -1 is specified, no limits are applied. The default is -1.

• min_instances operator will run at least the number of instances for any given Postgres cluster equal to the value of this parameter. Standby clusters can still run with numberOfInstances: 1 as this is the recommended setup. When -1 is specified for min_instances, no limits are applied. The default is -1.

• resync_period period between consecutive sync requests. The default is 30m.

• repair_period period between consecutive repair requests. The default is 5m.

• set_memory_request_to_limit Set memory_request to memory_limit for all Postgres clusters (the default value is also increased). This prevents certain cases of memory overcommitment at the cost of overprovisioning memory and potential scheduling problems for containers with high memory limits due to the lack of memory on Kubernetes cluster nodes. This affects all containers created by the operator (Postgres, Scalyr sidecar, and other sidecars except sidecars defined in the operator configuration); to set resources for the operator's own container, change the operator deployment manually. The default is false.

Postgres users

Parameters describing Postgres users. In a CRD-configuration, they are grouped under the users key.

• super_username Postgres superuser name to be created by initdb. The default is postgres.

• replication_username Postgres username used for replication between instances. The default is standby.

Major version upgrades

Parameters configuring automatic major version upgrades. In a CRD-configuration, they are grouped under the major_version_upgrade key.

• major_version_upgrade_mode Postgres Operator supports in-place major version upgrade with three different modes: "off" = no upgrade by the operator, "manual" = manifest triggers action, "full" = manifest and minimal version violation trigger upgrade. Note, that with all three modes increasing the version in the manifest will trigger a rolling update of the pods. The default is "off".

• minimal_major_version The minimal Postgres major version that will not automatically be upgraded when major_version_upgrade_mode is set to "full". The default is "9.5".

• target_major_version The target Postgres major version when upgrading clusters automatically which violate the configured allowed minimal_major_version when major_version_upgrade_mode is set to "full". The default is "13".

Kubernetes resources

Parameters to configure cluster-related Kubernetes objects created by the operator, as well as some timeouts associated with them. In a CRD-based configuration they are grouped under the kubernetes key.

• pod_service_account_name service account used by Patroni running on individual Pods to communicate with the operator. Required even if native Kubernetes support in Patroni is not used, because Patroni keeps pod labels in sync with the instance role. The default is postgres-pod.

• pod_service_account_definition On Postgres cluster creation the operator tries to create the service account for the Postgres pods if it does not exist in the namespace. The internal default service account definition (defines only the name) can be overwritten with this parameter. Make sure to provide a valid YAML or JSON string. The default is empty.

• pod_service_account_role_binding_definition This definition must bind the pod service account to a role with permission sufficient for the pods to start and for Patroni to access K8s endpoints; service account on its own lacks any such rights starting with K8s v1.8. If not explicitly defined by the user, a simple definition that binds the account to the 'postgres-pod' cluster role will be used. The default is empty.

• pod_terminate_grace_period Postgres pods are terminated forcefully after this timeout. The default is 5m.

• custom_pod_annotations This key/value map provides a list of annotations that get attached to each pod of a database created by the operator. If the annotation key is also provided by the database definition, the database definition value is used.

• delete_annotation_date_key key name for annotation that compares manifest value with current date in the YYYY-MM-DD format. Allowed pattern: '([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]'. The default is empty which also disables this delete protection check.

• delete_annotation_name_key key name for annotation that compares manifest value with Postgres cluster name. Allowed pattern: '([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]'. The default is empty which also disables this delete protection check.

• downscaler_annotations An array of annotations that should be passed from Postgres CRD on to the statefulset and, if exists, to the connection pooler deployment as well. Regular expressions like downscaler/* etc. are also accepted. Can be used with kube-downscaler.

• watched_namespace The operator watches for Postgres objects in the given namespace. If not specified, the value is taken from the operator namespace. A special * value makes it watch all namespaces. The default is empty (watch the operator pod namespace).

• pdb_name_format defines the template for PDB (Pod Disruption Budget) names created by the operator. The default is postgres-{cluster}-pdb, where {cluster} is replaced by the cluster name. Only the {cluster} placeholders is allowed in the template.

• enable_pod_disruption_budget PDB is enabled by default to protect the cluster from voluntarily disruptions and hence unwanted DB downtime. However, on some cloud providers it could be necessary to temporarily disabled it, e.g. for node updates. See admin docs for more information. Default is true.

• enable_cross_namespace_secrets To allow secrets in a different namespace other than the Postgres cluster namespace. Once enabled, specify the namespace in the user name under the users section in the form {namespace}.{username}. The operator will then create the user secret in that namespace. The part after the first . is considered to be the user name. The default is false.

• enable_init_containers global option to allow for creating init containers in the cluster manifest to run actions before Spilo is started. Default is true.

• enable_sidecars global option to allow for creating sidecar containers in the cluster manifest to run alongside Spilo on the same pod. Globally defined sidecars are always enabled. Default is true.

• secret_name_template a template for the name of the database user secrets generated by the operator. {namespace} is replaced with name of the namespace if enable_cross_namespace_secret is set, otherwise the secret is in cluster's namespace. {username} is replaced with name of the secret, {cluster} with the name of the cluster, {tprkind} with the kind of CRD (formerly known as TPR) and {tprgroup} with the group of the CRD. No other placeholders are allowed. The default is {namespace}.{username}.{cluster}.credentials.{tprkind}.{tprgroup}.

• cluster_domain defines the default DNS domain for the kubernetes cluster the operator is running in. The default is cluster.local. Used by the operator to connect to the Postgres clusters after creation.

• oauth_token_secret_name namespaced name of the secret containing the OAuth2 token to pass to the teams API. The default is postgresql-operator.

• infrastructure_roles_secret_name deprecated: namespaced name of the secret containing infrastructure roles with user names, passwords and role membership.

• infrastructure_roles_secrets array of infrastructure role definitions which reference existing secrets and specify the key names from which user name, password and role membership are extracted. For the ConfigMap this has to be a string which allows referencing only one infrastructure roles secret. The default is empty.

• inherited_annotations list of annotation keys that can be inherited from the cluster manifest, and added to each child objects (Deployment, StatefulSet, Pod, PDB and Services) created by the operator incl. the ones from the connection pooler deployment. The default is empty.

• pod_role_label name of the label assigned to the Postgres pods (and services/endpoints) by the operator. The default is spilo-role.

• cluster_labels list of name:value pairs for additional labels assigned to the cluster objects. The default is application:spilo.

• inherited_labels list of label keys that can be inherited from the cluster manifest, and added to each child objects (Deployment, StatefulSet, Pod, PVCs, PDB, Service, Endpoints and Secrets) created by the operator. Typical use case is to dynamically pass labels that are specific to a given Postgres cluster, in order to implement NetworkPolicy. The default is empty.

• cluster_name_label name of the label assigned to Kubernetes objects created by the operator that indicates which cluster a given object belongs to. The default is cluster-name.

• node_readiness_label a set of labels that a running and active node should possess to be considered ready. The operator uses values of those labels to detect the start of the Kubernetes cluster upgrade procedure and move master pods off the nodes to be decommissioned. When the set is not empty, the operator also assigns the Affinity clause to the Postgres pods to be scheduled only on ready nodes. The default is empty.

• toleration a dictionary that should contain key, operator, value and effect keys. In that case, the operator defines a pod toleration according to the values of those keys. See kubernetes documentation for details on taints and tolerations. The default is empty.

• pod_environment_configmap namespaced name of the ConfigMap with environment variables to populate on every pod. Right now this ConfigMap is searched in the namespace of the Postgres cluster. All variables from that ConfigMap are injected to the pod's environment, on conflicts they are overridden by the environment variables generated by the operator. The default is empty.

• pod_priority_class_name a name of the priority class that should be assigned to the Postgres pods. The priority class itself must be defined in advance. Default is empty (use the default priority class).

• spilo_runasuser sets the user ID which should be used in the container to run the process. This must be set to run the container without root. By default the container runs with root. This option only works for Spilo versions >= 1.6-p3.

• spilo_runasgroup sets the group ID which should be used in the container to run the process. This must be set to run the container without root. By default the container runs with root. This option only works for Spilo versions >= 1.6-p3.

• spilo_fsgroup the Persistent Volumes for the Spilo pods in the StatefulSet will be owned and writable by the group ID specified. This is required to run Spilo as a non-root process, but requires a custom Spilo image. Note the FSGroup of a Pod cannot be changed without recreating a new Pod.

• spilo_privileged whether the Spilo container should run in privileged mode. Privileged mode is used for AWS volume resizing and not required if you don't need that capability. The default is false.

• spilo_allow_privilege_escalation Controls whether a process can gain more privileges than its parent process. Required by cron which needs setuid. Without this parameter, certification rotation & backups will not be done. The default is true.

• additional_pod_capabilities list of additional capabilities to be added to the postgres container's SecurityContext (e.g. SYS_NICE etc.). Please, make sure first that the PodSecruityPolicy allows the capabilities listed here. Otherwise, the container will not start. The default is empty.

• master_pod_move_timeout The period of time to wait for the success of migration of master pods from an unschedulable node. The migration includes Patroni switchovers to respective replicas on healthy nodes. The situation where master pods still exist on the old node after this timeout expires has to be fixed manually. The default is 20 minutes.

• enable_pod_antiaffinity toggles pod anti affinity on the Postgres pods, to avoid multiple pods of the same Postgres cluster in the same topology , e.g. node. The default is false.

• pod_antiaffinity_topology_key override topology key for pod anti affinity. The default is kubernetes.io/hostname.

• pod_management_policy specify the pod management policy of stateful sets of PG clusters. The default is ordered_ready, the second possible value is parallel.

• storage_resize_mode defines how operator handles the difference between the requested volume size and the actual size. Available options are:

  1. ebs : operator resizes EBS volumes directly and executes resizefs within a pod
  2. pvc : operator only changes PVC definition
  3. off : disables resize of the volumes.
  4. mixed :operator uses AWS API to adjust size, throughput, and IOPS, and calls pvc change for file system resize Default is "pvc".