postgres-operator

README

= PostgreSQL Operator
v1.3.1, {docdate}

== Overview

The PostgreSQL Operator provides a Kubernetes operator capability for managing PostgreSQL Clusters deployed within a Kubernetes.

The PostgreSQL Operator leverages Kubernetes Third Party Resources to define custom resource type *pgcluster*, *pgbackups*, and *pgupgrades*.

Once those custom objects are defined, Kubernetes provides the ability to create and manage those objects similar to any other native Kubernetes object. 

The PostgreSQL Operator runs within Kubernetes detecting these new custom object types being created or removed. 

Once the objects are detected, the PostgreSQL Operator enables users to perform operations across the Kubernetes environment, including:

* Create Cluster
* Destroy Cluster
* Backup Cluster
* Scale a Cluster
* Restore Cluster
* Upgrade Cluster
* View PVC
* Test Connections
* Clone a Cluster

What actually gets created on the Kube cluster for a 
*pgcluster* resource is defined as a *deployment strategy*.  Strategies
are documented in detail here link:docs/strategies.asciidoc[Deployment Strategies] 

== Requirements

* Kubernetes 1.5.3+
* Openshift Origin 1.5.1+ or Openshift Container Platform 3.5
* link:https://hub.docker.com/r/crunchydata/crunchy-postgres/[PostgreSQL 9.5+ Container]
* link:https://hub.docker.com/r/crunchydata/crunchy-backup/[PostgreSQL Backup Container]
* link:https://hub.docker.com/r/crunchydata/crunchy-upgrade/[PostgreSQL Upgrade Container]

== Example Commands Usage

Some examples of using the command line interface:

.Display Cluster Information
[source,bash]
----
pgo show cluster all
pgo show cluster db1 db2 db3
pgo show cluster mycluster
pgo show cluster mycluster --show-secrets=true
----

.Create Cluster
[source,bash]
----
pgo create cluster mycluster
----

.Scale Cluster
[source,bash]
----
pgo scale mycluster --replica-count=2
----

.Delete a Cluster
[source,bash]
----
pgo delete cluster mycluster
----

.Backup Cluster
[source,bash]
----
pgo create backup mycluster
----

.Restore Cluster
[source,bash]
----
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)
[source,bash]
----
pgo create upgrade mycluster 
----

.Upgrade Cluster (major Postgres version upgrade from 9.5 to 9.6)
[source,bash]
----
pgo create upgrade mycluster --upgrade-type=major
----

.View PVC
[source,bash]
----
pgo show pvc mypvc
----

.Test Connections
[source,bash]
----
pgo test mycluster
----

.Clone Cluster
[source,bash]
----
pgo clone mycluster --name=myclone
----

Details on the *pgo* commands are found in the 
link:docs/user-guide.asciidoc[User Guide] 


== postgres-operator Container

In the following diagram, the postgres operator client, *pgo*, is
shown interacting with the postgres operator that runs within
a Kubernetes cluster.  The operator is responsible for creating
or modifying PostgreSQL databases deployed within the Kube cluster.

image::docs/operator-diagram.png?raw=true[]

The operator funtionality runs in a Pod deployed to your
Kubernetes cluster.  The *postgres-operator* Docker container
is available on link:https://hub.docker.com/r/crunchydata/postgres-operator/[Dockerhub].  

You can also build the Docker image for *postgres-operator* using
the build instructions link:docs/build.asciidoc[Build and Setup].

== Command Line Interface

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

You can download a pre-built *pgo* CLI binary from 
the Releases page on the github repository or build
it yourself using the build instructions.


== Build and Setup Instructions

Build instructions are documented here.
link:docs/build.asciidoc[Build and Setup] 

== Configuration

You can configure both the client and the operator.  The
configuration options are documented here.
link:docs/config.asciidoc[Configuration]