# 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]