Prerequisites

Prerequisites

The following is required prior to installing Crunchy PostgreSQL Operator using Ansible:

• postgres-operator playbooks source code for the target version
• Ansible 2.5+

Kubernetes Installs

• Kubernetes v1.11+
• Cluster admin privileges in Kubernetes
• kubectl configured to communicate with Kubernetes

OpenShift Installs

• OpenShift v3.09+
• Cluster admin privileges in OpenShift
• oc configured to communicate with OpenShift

Installing from a Windows Host

If the Crunchy PostgreSQL Operator is being installed from a Windows host the following are required:

• Windows Subsystem for Linux (WSL)
• Ubuntu for Windows

Environment

Ensure the appropriate environment variables are set.

Permissions

The installation of the Crunchy PostgreSQL Operator requires elevated privileges.
It is required that the playbooks are run as a cluster-admin to ensure the playbooks can install:

• Custom Resource Definitions
• Cluster RBAC
• Create required namespaces

Obtaining Operator Ansible Role

There are two ways to obtain the Crunchy PostgreSQL Operator Roles:

• Clone the postgres-operator project

• postgres-operator-playbooks RPM provided for Crunchy customers via the Crunchy Access Portal.

GitHub Installation

All necessary files (inventory, main playbook and roles) can be found in the ansible directory in the postgres-operator project.

RPM Installation using Yum

Available to Crunchy customers is an RPM containing all the necessary Ansible roles and files required for installation using Ansible. The RPM can be found in Crunchy’s yum repository. For information on setting up yum to use the Crunchy repoistory, see the Crunchy Access Portal.

To install the Crunchy PostgreSQL Operator Ansible roles using yum, run the following command on a RHEL or CentOS host:

sudo yum install postgres-operator-playbooks

• Ansible roles can be found in: /usr/share/ansible/roles/crunchydata
• Ansible playbooks/inventory files can be found in: /usr/share/ansible/postgres-operator/playbooks

Once installed users should take a copy of the inventory file included in the installation using the following command:

cp /usr/share/ansible/postgres-operator/playbooks/inventory ${HOME?}

Configuring the Inventory File

The inventory file included with the PostgreSQL Operator Playbooks allows installers to configure how the operator will function when deployed into Kubernetes. This file should contain all configurable variables the playbooks offer.

Requirements

The following configuration parameters must be set in order to deploy the Crunchy PostgreSQL Operator.

Additionally, storage variables will need to be defined to provide the Crunchy PostgreSQL Operator with any required storage configuration. Guidance for defining storage variables can be found further in this documentation.

• archive_mode
• archive_timeout
• backup_storage
• backrest
• backrest_storage
• badger
• ccp_image_prefix
• ccp_image_tag
• create_rbac
• db_name
• db_password_age_days
• db_password_length
• db_port
• db_replicas
• db_user
• disable_auto_failover`
• exporterport
• kubernetes_context (Comment out if deploying to am OpenShift environment)
• metrics
• openshift_host (Comment out if deploying to a Kubernetes environment)
• openshift_password (Comment out if deploying to a Kubernetes environment)
• openshift_skip_tls_verify (Comment out if deploying to a Kubernetes environment)
• openshift_token (Comment out if deploying to a Kubernetes environment)
• openshift_user (Comment out if deploying to a Kubernetes environment)
• pgbadgerport
• pgo_admin_password
• pgo_admin_perms
• pgo_admin_role_name
• pgo_admin_username
• pgo_client_version
• pgo_image_prefix
• pgo_image_tag
• pgo_installation_name
• pgo_operator_namespace
• primary_storage
• replica_storage
• scheduler_timeout

Configuration Parameters

kubectl config current-context

Storage

Kubernetes and OpenShift offer support for a wide variety of different storage types, and by default, the inventory is pre-populated with storage configurations for some of these storage types. However, the storage types defined in the inventory can be modified or removed as needed, while additional storage configurations can also be added to meet the specific storage requirements for your PG clusters.

The following storage variables are utilized to add or modify operator storage configurations in the inventory:

The ID portion of storage prefix for each variable name above should be an integer that is used to group the various storage variables into a single storage configuration. For instance, the following shows a single storage configuration for NFS storage:

storage3_name='nfsstorage'
storage3_access_mode='ReadWriteMany'
storage3_size='1G'
storage3_type='create'
storage3_supplemental_groups=65534

As this example storage configuration shows, integer 3 is used as the ID for each of the storage variables, which together form a single storage configuration called nfsstorage. This approach allows different storage configurations to be created by defining the proper storage variables with a unique ID for each required storage configuration.

Additionally, once all storage configurations have been defined in the inventory, they can then be used to specify the default storage configuration that should be utilized for the various PG pods created by the operator. This is done using the following variables, which are also defined in the inventory:

backrest_storage='nfsstorage'
backup_storage='nfsstorage'
primary_storage='nfsstorage'
replica_storage='nfsstorage'

With the configuration shown above, the nfsstorage storage configuration would be used by default for the various containers created for a PG cluster (i.e. containers for the primary DB, replica DB’s, backups and/or pgBackRest).

Examples

The following are additional examples of storage configurations for various storage types.

Generic Storage Class

The following example defines a storageTo setup storage1 to use the storage class fast

storage5_name='storageos'
storage5_access_mode='ReadWriteOnce'
storage5_size='300M'
storage5_type='dynamic'
storage5_class='fast'
storage5_fs_group=26

To assign this storage definition to all primary pods created by the Operator, we can configure the primary_storage=storageos variable in the inventory file.

GKE

The storage class provided by Google Kubernetes Environment (GKE) can be configured to be used by the Operator by setting the following variables in the inventory file:

storage8_name='gce'
storage8_access_mode='ReadWriteOnce'
storage8_size='300M'
storage8_type='dynamic'
storage8_class='standard'
storage8_fs_group=26

To assign this storage definition to all primary pods created by the Operator, we can configure the primary_storage=gce variable in the inventory file.

Considerations for Multi-Zone Cloud Environments

When using the Operator in a Kubernetes cluster consisting of nodes that span multiple zones, special consideration must betaken to ensure all pods and the volumes they require are scheduled and provisioned within the same zone. Specifically, being that a pod is unable mount a volume that is located in another zone, any volumes that are dynamically provisioned must be provisioned in a topology-aware manner according to the specific scheduling requirements for the pod. For instance, this means ensuring that the volume containing the database files for the primary database in a new PostgreSQL cluster is provisioned in the same zone as the node containing the PostgreSQL primary pod that will be using it.

Resource Configuration

Kubernetes and OpenShift allow specific resource requirements to be specified for the various containers deployed inside of a pod. This includes defining the required resources for each container, i.e. how much memory and CPU each container will need, while also allowing resource limits to be defined, i.e. the maximum amount of memory and CPU a container will be allowed to consume. In support of this capability, the Crunchy PGO allows any required resource configurations to be defined in the inventory, which can the be utilized by the operator to set any desired resource requirements/limits for the various containers that will be deployed by the Crunchy PGO when creating and managing PG clusters.

The following resource variables are utilized to add or modify operator resource configurations in the inventory:

The ID portion of resource prefix for each variable name above should be an integer that is used to group the various resource variables into a single resource configuration. For instance, the following shows a single resource configuration called small:

resource1_name='small'
resource1_requests_memory='512Mi'
resource1_requests_cpu=0.1
resource1_limits_memory='512Mi'
resource1_limits_cpu=0.1

As this example resource configuration shows, integer 1 is used as the ID for each of the resource variables, which together form a single resource configuration called small. This approach allows different resource configurations to be created by defining the proper resource variables with a unique ID for each required resource configuration.

Additionally, once all resource configurations have been defined in the inventory, they can then be used to specify the default resource configurations that should be utilized for the various PG containers created by the operator. This is done using the following variables, which are also defined in the inventory:

default_container_resources='large'
default_load_resources='small'
default_rmdata_resources='small'
default_backup_resources='small'
default_pgbouncer_resources='small'

With the configuration shown above, the large resource configuration would be used by default for all database containers, while the small resource configuration would then be utilized by default for the various other containers created for a PG cluster.

Understanding pgo_operator_namespace & namespace

The Crunchy PostgreSQL Operator can be configured to be deployed and manage a single namespace or manage several namespaces. The following are examples of different types of deployment models configurable in the inventory file.

Single Namespace

To deploy the Crunchy PostgreSQL Operator to work with a single namespace (in this example our namespace is named pgo), configure the following inventory settings:

pgo_operator_namespace='pgo'
namespace='pgo'

Multiple Namespaces

To deploy the Crunchy PostgreSQL Operator to work with multiple namespaces (in this example our namespaces are named pgo, pgouser1 and pgouser2), configure the following inventory settings:

pgo_operator_namespace='pgo'
namespace='pgouser1,pgouser2'

Deploying Multiple Operators

The 4.0 release of the Crunchy PostgreSQL Operator allows for multiple operator deployments in the same cluster.
To install the Crunchy PostgreSQL Operator to multiple namespaces, it’s recommended to have an inventory file for each deployment of the operator.

For each operator deployment the following inventory variables should be configured uniquely for each install.

For example, operator could be deployed twice by changing the pgo_operator_namespace and namespace for those deployments:

Inventory A would deploy operator to the pgo namespace and it would manage the pgo target namespace.

# Inventory A
pgo_operator_namespace='pgo'
namespace='pgo'
...

Inventory B would deploy operator to the pgo2 namespace and it would manage the pgo2 and pgo3 target namespaces.

# Inventory B
pgo_operator_namespace='pgo2'
namespace='pgo2,pgo3'
...

Each install of the operator will create a corresponding directory in $HOME/.pgo/<PGO NAMESPACE> which will contain the TLS and pgouser client credentials.

Deploying Grafana and Prometheus

PostgreSQL clusters created by the operator can be configured to create additional containers for collecting metrics.
These metrics are very useful for understanding the overall health and performance of PostgreSQL database deployments over time. The collectors included by the operator are:

• PostgreSQL Exporter - PostgreSQL metrics

The operator, however, does not install the necessary timeseries database (Prometheus) for storing the collected metrics or the front end visualization (Grafana) of those metrics.

Included in these playbooks are roles for deploying Granfana and/or Prometheus. See the inventory file for options to install the metrics stack.