Quickstart

This section describes how to test a PostgreSQL cluster on your laptop/computerusing CloudNativePG on a local Kubernetes cluster in

Warning

The instructions contained in this section are for demonstration, testing, and practice purposes only and must not be used in production.

Like any other Kubernetes application, CloudNativePG is deployed usingregular manifests written in YAML.

By following the instructions on this page you should be able to start a PostgreSQLcluster on your local Kubernetes installation and experiment with it.

Important

Make sure that you have kubectl installed on your machine in order to connect to the Kubernetes cluster. Please follow the Kubernetes documentation on how to install `kubectl <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`__ .

Part 1 - Setup the local Kubernetes playground

The first part is about installing Minikube or Kind. Please spend some timereading about the systems and decide which one to proceed with.After setting up one of them, please proceed with part 2.

Minikube

Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs asingle-node Kubernetes cluster inside a Virtual Machine (VM) on your laptop forusers looking to try out Kubernetes or develop with it day-to-day. Normally, itis used in conjunction with VirtualBox.

You can find more information in the official Kubernetes documentation on how toinstall Minikube in your local personal environment.When you installed it, run the following command to create a minikube cluster:

minikube start

This will create the Kubernetes cluster, and you will be ready to use it.Verify that it works with the following command:

kubectl get nodes

You will see one node called minikube .

Kind

If you do not want to use a virtual machine hypervisor, then Kind is a tool for runninglocal Kubernetes clusters using Docker container “nodes” (Kind stands for “Kubernetes IN Docker” indeed).

Install kind on your environment following the instructions in the

Quickstart ,then create a Kubernetes cluster with:

kind create cluster --name pg

Part 2 - Install CloudNativePG

Now that you have a Kubernetes installation up and runningon your laptop, you can proceed with CloudNativePG installation.

Please refer to the Installation and upgrades section and then proceedwith the deployment of a PostgreSQL cluster.

Part 3 - Deploy a PostgreSQL cluster

As with any other deployment in Kubernetes, to deploy a PostgreSQL clusteryou need to apply a configuration file that defines your desired Cluster .

The cluster-example.yaml sample filedefines a simple Cluster using the default storage class to allocatedisk space:

#  Example of PostgreSQL cluster
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3

  # Example of rolling update strategy:
  # - unsupervised: automated update of the primary once all
  #                 replicas have been upgraded (default)
  # - supervised: requires manual supervision to perform
  #               the switchover of the primary
  primaryUpdateStrategy: unsupervised

  # Require 1Gi of space
  storage:
    size: 1Gi

In order to create the 3-node PostgreSQL cluster, you need to run the following command:

kubectl apply -f cluster-example.yaml

You can check that the pods are being created with the get pods command:

kubectl get pods

By default, the operator will install the latest available minor versionof the latest major version of PostgreSQL when the operator was released.You can override this by setting the imageName key in the spec section ofthe Cluster definition. For example, to install PostgreSQL 13.6:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
   # [...]
spec:
   # [...]
   imageName: ghcr.io/cloudnative-pg/postgresql:13.6
   #[...]

Important

The immutable infrastructure paradigm requires that you always point to a specific version of the container image. Never use tags like latest or 13 in a production environment as it might lead to unpredictable scenarios in terms of update policies and version consistency in the cluster. For strict deterministic and repeatable deployments, you can add the digests to the image name, through the <image>:<tag>@sha256:<digestValue> format.