postgres-operator

README

= PostgreSQL Operator
v1.1.0, {docdate}

== Overview

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

The PostgreSQL Operator leverages Kubernetes Third Party Resources to define custom resource types *pgdatabase* and *pgcluster*.

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 Database or Cluster
* Destroy Database or Cluster
* Backup Database or Cluster
* Restore Database or Cluster
* Upgrade Database or Cluster
* View PVC

What actually gets created on the Kube cluster for a *pgdatabase* or
*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+
* 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 Database or Cluster Information
[source,bash]
----
pgo show database all
pgo show database db1 db2 db3
pgo show cluster mycluster
----

.Create Database or Cluster
[source,bash]
----
pgo create database mydatabase
pgo create cluster mycluster
----

.Delete a Database or Cluster
[source,bash]
----
pgo delete database mydatabase
pgo delete cluster mycluster
----

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

.Restore Database
[source,bash]
----
pgo create database myrestore --backup-pvc=mypvc --backup-path=foo-backups/2017-03-21-15-57-21
----

.Upgrade Database (minor Postgres version upgrade)
[source,bash]
----
pgo create upgrade mydatabase 
----

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

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

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]