Quickstart | CloudNativePG

This section guides you through testing a PostgreSQL cluster on your local machine by deploying CloudNativePG on a local Kubernetes cluster using either Kind or Minikube.
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 using regular manifests written in YAML.
By following the instructions on this page you should be able to start a PostgreSQL cluster on your local Kubernetes installation and experiment with it.
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.
The first part is about installing Minikube or Kind. Please spend some time reading about the systems and decide which one to proceed with. After setting up one of them, please proceed with part 2.
We also provide instructions for setting up monitoring with Prometheus and Grafana for local testing/evaluation, in part 4
Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs a single-node Kubernetes cluster inside a Virtual Machine (VM) on your laptop for users looking to try out Kubernetes or develop with it day-to-day. Normally, it is used in conjunction with VirtualBox.
You can find more information in the official Kubernetes documentation on how to install Minikube in your local personal environment. When you installed it, run the following command to create a minikube cluster:
This will create the Kubernetes cluster, and you will be ready to use it. Verify that it works with the following command:
You will see one node called minikube.
If you do not want to use a virtual machine hypervisor, then Kind is a tool for running local 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:
Now that you have a Kubernetes installation up and running on your laptop, you can proceed with CloudNativePG installation.
Please refer to the "Installation" section and then proceed with the deployment of a PostgreSQL cluster.
As with any other deployment in Kubernetes, to deploy a PostgreSQL cluster you need to apply a configuration file that defines your desired Cluster.
The cluster-example.yaml sample file defines a simple Cluster using the default storage class to allocate disk space:
For more detailed information about the available options, please refer to the "API Reference" section.
In order to create the 3-node PostgreSQL cluster, you need to run the following command:
You can check that the pods are being created with the get pods command:
That will look for pods in the default namespace. To separate your cluster from other workloads on your Kubernetes installation, you could always create a new namespace to deploy clusters on. Alternatively, you can use labels. The operator will apply the cnpg.io/cluster label on all objects relevant to a particular cluster. For example:
Note that we are using cnpg.io/cluster as the label. In the past you may have seen or used postgresql. This label is being deprecated, and will be dropped in the future. Please use cnpg.io/cluster.
By default, the operator will install the latest available minor version of the latest major version of PostgreSQL when the operator was released. You can override this by setting the imageName key in the spec section of the Cluster definition. For example, to install PostgreSQL 13.6:
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.
There are some examples cluster configurations bundled with the operator. Please refer to the "Examples" section.
Installing Prometheus and Grafana is beyond the scope of this project. The instructions in this section are provided for experimentation and illustration only.
In this section we show how to deploy Prometheus and Grafana for observability, and how to create a Grafana Dashboard to monitor CloudNativePG clusters, and a set of Prometheus Rules defining alert conditions.
We leverage the Kube-Prometheus stack Helm chart, which is maintained by the Prometheus Community. Please refer to the project website for additional documentation and background.
The Kube-Prometheus-stack Helm chart installs the Prometheus Operator, including the Alert Manager, and a Grafana deployment.
We include a configuration file for the deployment of this Helm chart that will provide useful initial settings for observability of CloudNativePG clusters.
If you don't have Helm installed yet, please follow the instructions to install it in your system.
We need to add the prometheus-community helm chart repository, and then install the Kube Prometheus stack with our sample configuration kube-stack-config.yaml.
We can accomplish this with the following commands:
After completion, you will have Prometheus, Grafana, and Alert Manager, configured with the kube-stack-config.yaml file:
For further information about the above helm commands, refer to the helm install documentation.
You can see several Custom Resources have been created:
as well as a series of Services:
At this point, a CloudNativePG cluster deployed with monitoring activated would be observable via Prometheus.
For example, you could deploy a simple cluster with PodMonitor enabled:
To access Prometheus, port-forward the Prometheus service: