PostgreSQL Operator logo PostgreSQL Operator

PostgreSQL Operator
for Kubernetes

by Zalando

The PostgreSQL operator provisions and configures a PostgreSQL database cluster on top of Kubernetes. PostgreSQL is a powerful, open source object-relational database system.

Documentation

description README

Install, update and remove

description DEPLOY

Deploy a PostgreSQL Cluster

Install the PostgreSQL Operator

info_outline

Below instructions explain how to install the PostgreSQL operator in a repository bootstrapped using the Kubestack quickstart. But you can adapt the workflow to any kustomize directory layout easily.

  1. Vendor the base

    # Run these commands from the root of your Kubestack infra repository
    wget https://storage.googleapis.com/catalog.kubestack.com/postgresql-v1.2.0-kbst.0.zip
    unzip -d manifests/bases/ postgresql-v1.2.0-kbst.0.zip
    rm postgresql-v1.2.0-kbst.0.zip
    
  2. Include in bases

    cd manifests/overlays/common
    kustomize edit add base ../../bases/postgresql/clusterwide
    
  3. Commit and push

    cd -
    git checkout -b add-postgresql
    git add manifests/bases/postgresql manifests/overlays/common/kustomization.yaml
    git commit -m "Add postgresql v1.2.0-kbst.0 base"
    git push origin add-postgresql
    
  4. Review PR and merge

    Finally, review and merge the PR into master. Once it's been successfully applied against the Ops-Cluster set a prod-deploy tag to also apply the change against the Apps-Cluster.


Update the PostgreSQL Operator

info_outline

The UPDATE instructions assume the operator has been installed by following the INSTALL instructions. If not, adjust accordingly.

To update the operator delete the previously vendored base and then vendor the new version.

  1. Delete the previous vendored version

    # Run these commands from the root of your Kubestack infra repository
    rm -r manifests/bases/postgresql
    
  2. Vendor the new version

    # Run these commands from the root of your Kubestack infra repository
    wget https://storage.googleapis.com/catalog.kubestack.com/postgresql-v1.2.0-kbst.0.zip
    unzip -d manifests/bases/ postgresql-v1.2.0-kbst.0.zip
    rm postgresql-v1.2.0-kbst.0.zip
    
  3. Commit and push

    git checkout -b update-postgresql
    git add manifests/bases/postgresql
    git commit -m "Update postgresql base to v1.2.0-kbst.0"
    git push origin update-postgresql
    

Remove the Database Clusters and the Operator

info_outline

Please be advised, the removal instructions for the PostgreSQL operator require manual steps to cleanly remove both eventually provisioned database clusters and the operator itself from your Kubernetes cluster.

  1. List and deprovision PostgreSQL clusters

    # Make sure your context is pointing to the correct cluster
    kubectl get postgresql
    
  2. Delete the vendored base from your repository

    # Run these commands from the root of your Kubestack infra repository
    rm -r manifests/bases/postgresql
    
  3. Commit and push

    git checkout -b remove-postgresql
    git add manifests/bases/postgresql
    git commit -m "Remove postgresql base"
    git push origin remove-postgresql
    
  4. Delete operator

    When manifests are applied using kubectl apply, resources that have been removed from the manifests, are not removed from the clusters. So, as a last step, we need to delete the operator from our clusters, which we can do by simply deleting the namespace.

    kubectl delete namespace operator-postgresql
    

Deploy a PostgreSQL Cluster

Once the operator has been deployed to the Kubernetes cluster, you can use it to provision and operate one or more database clusters by creating a custom object of the operator's custom resource.

PostgreSQL Custom Object

Below is an example of a minimal PostgreSQL custom object to instruct the operator to provision a database cluster.

To get started, put the example below into a file called postgresql.yaml and add it to your application's manifests. Then apply the manifests including the postgresql.yaml as usual.

apiVersion: "acid.zalan.do/v1"
kind: postgresql
metadata:
  name: acid-minimal-cluster
  namespace: default
spec:
  postgresql:
    version: "10"
  teamId: "ACID"
  volume:
    size: 1Gi
  numberOfInstances: 2
  users:
    # admin user
    admin:
    - superuser
    # application user
    app_user: []

  databases:
    # db_name: user_name
    app_db: app_user

Configuring your cluster

Make sure to configure name and namespace and the users and databases according to your application's requirements.

You can find additional information on these parameters and additional options in the upstream project's documentation.