mozinator / postgres-operator

PostgreSQL Operator Creates/Configures/Manages PostgreSQL Clusters on Kubernetes

PostgreSQL Operator

Table of Contents

• Overview

• Requirements

• Build and Install Instructions

• Configuration

• Examples

• PostgreSQL Operator Container

Overview

The PostgreSQL Operator provides a Kubernetes operator capability for managing PostgreSQL Clusters deployed within a Kubernetes environment. The project also incorporates a REST API and REST client for interfacing with the Operator.

The PostgreSQL Operator leverages Kubernetes Custom Resource Definitions to define custom resource types such as:

• pgcluster

• pgbackups

• pgpolicies

Kubernetes provides the ability to create and manage Custom Resource Definitions similar to any other native Kubernetes object.

The PostgreSQL Operator runs within Kubernetes detecting these custom object types as they are created, updated, or removed.

The PostgreSQL Operator enables users to perform operations, including:

• Create, Delete, Scale, Restore, and Backup a PostgreSQL Cluster

• Upgrade a PostgreSQL Cluster

• View PVCs used by PostgreSQL clusters

• Test Connections to a PostgreSQL Cluster

• Create and apply a SQL-based Policy to a PostgreSQL Cluster

• Perform User and Password Management

• Apply User Defined Labels to PostgreSQL Clusters

Requirements

CRD (custom resource definitions) are supported starting with Kube 1.7.X and with the PostgreSQL Operator version 2.0.

If you require an older version of Kube (< 1.7), you can work with the PostgreSQL Operator version 1.5.2 which resides in the github 1.5.X branch. Note however, that the older operator will be deprecated and no longer maintained in the future.

The CRD version of the operator is tested on the following platforms:

• Kubernetes 1.7.X+

• Kubernetes 1.8.0+

• Openshift Origin 1.7.0+

This Operator has also been tested on the following operating systems:

• CentOS 7.3+

• RHEL 7.3+

Build and Install Instructions

To build and deploy the Operator on your Kubernetes system, follow the instructions documented on the Build and Install page.

With the operator deployed, the pgo command line interface can execute commands that the postgres-operator understands and reacts to.

Configuration

The operator is template-driven; this makes it simple to configure both the client and the operator. The configuration options are documented on the Configuration page.

Examples

Some examples of using the pgo command line interface are as follows.

Display Cluster Information

pgo show cluster all
pgo show cluster db1 db2 db3
pgo show cluster mycluster
pgo show cluster mycluster --show-secrets=true

Create Cluster

pgo create cluster mycluster

Scale Cluster

pgo scale mycluster --replica-count=2

Delete a Cluster

pgo delete cluster mycluster

Backup Cluster

pgo create backup mycluster

Restore Cluster

pgo create cluster myrestore --secret-from=foo --backup-pvc=mypvc --backup-path=foo-backups/2017-03-21-15-57-21

Upgrade Cluster (minor Postgres version upgrade)

pgo create upgrade mycluster

Upgrade Cluster (major Postgres version upgrade from 9.5 to 9.6)

pgo create upgrade mycluster --upgrade-type=major

View PVC

pgo show pvc mypvc

Test Connections

pgo test mycluster

Create a Policy

pgo create policy policy1 --in-file=./policy1.sql
pgo create policy policy1 --url=https://someurl/policy1.sql

Warning

Apply a Policy policies are POWERFUL because they are executed as the superuser in PostgreSQL which allows for any sort of SQL to be executed.

pgo apply policy1 --selector=name=mycluster

Details on the pgo commands and complex examples are found in the User Guide

PostgreSQL Operator Container

The following diagram depicts the components of the PostgreSQL Operator, here the PostgreSQL operator client, pgo, is shown interacting with the PostgreSQL operator that runs within a Kubernetes cluster. The operator is responsible for creating or modifying PostgreSQL databases deployed within the Kubernetes cluster.

The pgo client, as of release 2.1, is now a REST client which interacts with the apiserver. The apiserver is a REST API that interacts with the Kube API including creating Custom Resource Definition resources implemented by the PostgreSQL Operator.

The operator functionality runs in a Kubernetes Deployment on your Kubernetes cluster.

The postgres-operator Docker container image is available on Dockerhub. The postgres-operator-apiserver Docker container image is available on Dockerhub. The pgo client is available on in the Releases section of this github repo site.

What actually gets created on the Kubernetes cluster for a pgcluster resource is defined as a deployment strategy. Strategies are documented in detail in Deployment Strategies.

You can also build the project Docker images using the build instructions located on the Build and Setup page.