merge master

docs/administrator.md

@@ -321,11 +321,12 @@ spec:
 ## Custom Pod Environment Variables
 
 It is possible to configure a ConfigMap which is used by the Postgres pods as
-an additional provider for environment variables.
-
-One use case is to customize the Spilo image and configure it with environment
-variables. The ConfigMap with the additional settings is configured in the
-operator's main ConfigMap:
+an additional provider for environment variables. One use case is to customize
+the Spilo image and configure it with environment variables. The ConfigMap with
+the additional settings is referenced in the operator's main configuration.
+A namespace can be specified along with the name. If left out, the configured
+default namespace of your K8s client will be used and if the ConfigMap is not
+found there, the Postgres cluster's namespace is taken when different:
 
 **postgres-operator ConfigMap**
 
@@ -336,7 +337,7 @@ metadata:
   name: postgres-operator
 data:
   # referencing config map with custom settings
-  pod_environment_configmap: postgres-pod-config
+  pod_environment_configmap: default/postgres-pod-config
 ```
 
 **OperatorConfiguration**
@@ -349,7 +350,7 @@ metadata:
 configuration:
   kubernetes:
     # referencing config map with custom settings
-    pod_environment_configmap: postgres-pod-config
+    pod_environment_configmap: default/postgres-pod-config
 ```
 
 **referenced ConfigMap `postgres-pod-config`**

docs/reference/cluster_manifest.md

@@ -140,6 +140,11 @@ These parameters are grouped directly under  the `spec` key in the manifest.
   is `false`, then no volume will be mounted no matter how operator was
   configured (so you can override the operator configuration). Optional.
 
+* **enableConnectionPool**
+  Tells the operator to create a connection pool with a database. If this
+  field is true, a connection pool deployment will be created even if
+  `connectionPool` section is empty. Optional, not set by default.
+
 * **enableLogicalBackup**
   Determines if the logical backup of this cluster should be taken and uploaded
   to S3. Default: false. Optional.
@@ -360,6 +365,35 @@ CPU and memory limits for the sidecar container.
   memory limits for the sidecar container. Optional, overrides the
   `default_memory_limits` operator configuration parameter. Optional.
 
+## Connection pool
+
+Parameters are grouped under the `connectionPool` top-level key and specify
+configuration for connection pool. If this section is not empty, a connection
+pool will be created for a database even if `enableConnectionPool` is not
+present.
+
+* **numberOfInstances**
+  How many instances of connection pool to create.
+
+* **schema**
+  Schema to create for credentials lookup function.
+
+* **user**
+  User to create for connection pool to be able to connect to a database.
+
+* **dockerImage**
+  Which docker image to use for connection pool deployment.
+
+* **maxDBConnections**
+  How many connections the pooler can max hold. This value is divided among the
+  pooler pods.
+
+* **mode**
+  In which mode to run connection pool, transaction or session.
+
+* **resources**
+  Resource configuration for connection pool deployment.
+
 ## Custom TLS certificates
 
 Those parameters are grouped under the `tls` top-level key.

docs/reference/operator_parameters.md

@@ -225,11 +225,12 @@ configuration they are grouped under the `kubernetes` key.
   to the Postgres clusters after creation.
 
 * **oauth_token_secret_name**
-  a name of the secret containing the `OAuth2` token to pass to the teams API.
-  The default is `postgresql-operator`.
+  namespaced name of the secret containing the `OAuth2` token to pass to the
+  teams API. The default is `postgresql-operator`.
 
 * **infrastructure_roles_secret_name**
-  name of the secret containing infrastructure roles names and passwords.
+  namespaced name of the secret containing infrastructure roles names and
+  passwords.
 
 * **pod_role_label**
   name of the label assigned to the Postgres pods (and services/endpoints) by
@@ -266,11 +267,11 @@ configuration they are grouped under the `kubernetes` key.
   for details on taints and tolerations. The default is empty.
 
 * **pod_environment_configmap**
-  a 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.
+  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](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass)
@@ -599,3 +600,40 @@ scalyr sidecar. In the CRD-based configuration they are grouped under the
 
 * **scalyr_memory_limit**
   Memory limit value for the Scalyr sidecar. The default is `500Mi`.
+
+## Connection pool configuration
+
+Parameters are grouped under the `connection_pool` top-level key and specify
+default configuration for connection pool, if a postgres manifest requests it
+but do not specify some of the parameters. All of them are optional with the
+operator being able to provide some reasonable defaults.
+
+* **connection_pool_number_of_instances**
+  How many instances of connection pool to create. Default is 2 which is also
+  the required minimum.
+
+* **connection_pool_schema**
+  Schema to create for credentials lookup function. Default is `pooler`.
+
+* **connection_pool_user**
+  User to create for connection pool to be able to connect to a database.
+  Default is `pooler`.
+
+* **connection_pool_image**
+  Docker image to use for connection pool deployment.
+  Default: "registry.opensource.zalan.do/acid/pgbouncer"
+
+* **connection_pool_max_db_connections**
+  How many connections the pooler can max hold. This value is divided among the
+  pooler pods. Default is 60 which will make up 30 connections per pod for the
+  default setup with two instances.
+
+* **connection_pool_mode**
+  Default pool mode, `session` or `transaction`. Default is `transaction`.
+
+* **connection_pool_default_cpu_request**
+  **connection_pool_default_memory_reques**
+  **connection_pool_default_cpu_limit**
+  **connection_pool_default_memory_limit**
+  Default resource configuration for connection pool deployment. The internal
+  default for memory request and limit is `100Mi`, for CPU it is `500m` and `1`.

docs/user.md

@@ -512,6 +512,59 @@ monitoring is outside the scope of operator responsibilities. See
 [administrator documentation](administrator.md) for details on how backups are
 executed.
 
+## Connection pool
+
+The operator can create a database side connection pool for those applications,
+where an application side pool is not feasible, but a number of connections is
+high. To create a connection pool together with a database, modify the
+manifest:
+
+```yaml
+spec:
+  enableConnectionPool: true
+```
+
+This will tell the operator to create a connection pool with default
+configuration, through which one can access the master via a separate service
+`{cluster-name}-pooler`. In most of the cases provided default configuration
+should be good enough.
+
+To configure a new connection pool, specify:
+
+```
+spec:
+  connectionPool:
+    # how many instances of connection pool to create
+    number_of_instances: 2
+
+    # in which mode to run, session or transaction
+    mode: "transaction"
+
+    # schema, which operator will create to install credentials lookup
+    # function
+    schema: "pooler"
+
+    # user, which operator will create for connection pool
+    user: "pooler"
+
+    # resources for each instance
+    resources:
+      requests:
+        cpu: 500m
+        memory: 100Mi
+      limits:
+        cpu: "1"
+        memory: 100Mi
+```
+
+By default `pgbouncer` is used to create a connection pool. To find out about
+pool modes see [docs](https://www.pgbouncer.org/config.html#pool_mode) (but it
+should be general approach between different implementation).
+
+Note, that using `pgbouncer` means meaningful resource CPU limit should be less
+than 1 core (there is a way to utilize more than one, but in K8S it's easier
+just to spin up more instances).
+
 ## Custom TLS certificates
 
 By default, the spilo image generates its own TLS certificate during startup.