Local Learning Environment for CloudNativePG

Welcome to cnpg-playground, a local learning environment designed for learning and experimenting with CloudNativePG using Docker and Kind.

Prerequisites

Ensure you have the latest available versions of the following tools installed on a Unix-based system:

• Docker
• Git
• Kubectl
• The cnpg plugin for kubectl
• Kind

You don’t need superuser privileges to run the scripts, but elevated permissions may be required to install the prerequisites.

Additional Tools

For an improved experience with the CNPG Playground, it’s recommended to install the following tools:

• curl: Command-line tool for data transfer.
• jq: JSON processor for handling API outputs.
• stern: Multi-pod log tailing tool.
• kubectx: Kubernetes context switcher.

Recommended kubectl plugins:

• view-secret: Decodes Kubernetes secrets.
• view-cert: Inspects TLS certificates.

These tools streamline working with the CNPG Playground.

Local Environment Overview

This environment emulates a two-region infrastructure (EU and US), with each region containing:

• An object storage service powered by MinIO containers

• A Kubernetes cluster, deployed using Kind, consisting of:

  • One control plane node
  • One node for infrastructure components
  • One node for applications
  • Three nodes dedicated to PostgreSQL

The architecture is illustrated in the diagram below:

Setting Up the Learning Environment

To set up the environment, simply run the following script:

./scripts/setup.sh

Connecting to the Kubernetes Clusters

To configure and interact with both Kubernetes clusters during the learning process, you will need to connect to them.

The setup script provides detailed instructions for accessing the clusters. If you need to view the connection details again after the setup, you can retrieve them by running:

./scripts/info.sh

Inspecting Nodes in a Kubernetes Cluster

To inspect the nodes in a Kubernetes cluster, you can use the following command:

kubectl get nodes

For example, when connected to the k8s-eu cluster, this command will display output similar to:

NAME                   STATUS   ROLES           AGE     VERSION
k8s-eu-control-plane   Ready    control-plane   10m     v1.31.0
k8s-eu-worker          Ready    infra           9m58s   v1.31.0
k8s-eu-worker2         Ready    app             9m58s   v1.31.0
k8s-eu-worker3         Ready    postgres        9m58s   v1.31.0
k8s-eu-worker4         Ready    postgres        9m58s   v1.31.0
k8s-eu-worker5         Ready    postgres        9m58s   v1.31.0

In this example:

• The control plane node (k8s-eu-control-plane) manages the cluster.
• Worker nodes have different roles, such as infra for infrastructure, app for application workloads, and postgres for PostgreSQL databases. Each node runs Kubernetes version v1.31.0.

Installing CloudNativePG on the Control Plane

To install the latest stable version of the CloudNativePG operator on the control plane node in both Kubernetes clusters, run the following commands:

kubectl cnpg install generate --control-plane | \
  kubectl --context kind-k8s-eu apply -f - --server-side

kubectl cnpg install generate --control-plane | \
  kubectl --context kind-k8s-us apply -f - --server-side

These commands will deploy the CloudNativePG operator with server-side apply on both the kind-k8s-eu and kind-k8s-us clusters.

Ensure that you have the latest version of the cnpg plugin installed on your local machine.

Cleaning up the Learning Environment

When you're ready to clean up and remove all resources from the learning environment, run the following script to tear down the containers and associated resources:

./scripts/teardown.sh

This will safely destroy all running containers and return your environment to its initial state.

Nix Flakes

Do you use Nix flakes? If you do, this package have a configured dev shell that can be used with:

nix develop .

Using Linux or WSL2

You may need:

sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=512

More information in the relative ticket comment.