2. Operator & `cnpg` plugin¶

Goal: install the CloudNativePG operator (the brain that will manage your database) and the kubectl-cnpg plugin (your inspection tool). This is the first step of Layer 2, done by hand with kubectl.

Step 2.1 — Install the operator¶

The operator is installed by applying a single YAML manifest. We pin to the exact patch release that contains the critical-CVE fix.

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.29/releases/cnpg-1.29.1.yaml

Why --server-side?

Server-side apply lets the API server merge changes field-by-field and is the recommended way to install large CRD-bearing manifests. It avoids the "annotation too long" errors that client-side apply hits on big CRDs.

This creates the cnpg-system namespace, the CRDs (Cluster, Pooler, ScheduledBackup, ImageCatalog, …), RBAC, and the operator Deployment.

flowchart LR
    apply["kubectl apply (manifest)"] --> ns["namespace: cnpg-system"]
    apply --> crds["CRDs registered"]
    apply --> dep["Deployment:<br/>cnpg-controller-manager"]
    dep -->|now watches| cr["Cluster / Pooler / ... resources<br/>in every namespace"]

Step 2.2 — Wait for it to be ready¶

kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

You should see deployment "cnpg-controller-manager" successfully rolled out.

Confirm the version (and that you really got 1.29.1):

kubectl get deployment -n cnpg-system cnpg-controller-manager \
  -o jsonpath='{.spec.template.spec.containers[*].image}'
# → ghcr.io/cloudnative-pg/cloudnative-pg:1.29.1

Step 2.3 — Install the `kubectl-cnpg` plugin¶

The plugin adds kubectl cnpg ... subcommands for status, backups, promotion, and more. On macOS/Linux with Homebrew:

brew install kubectl-cnpg   # (1)!
kubectl cnpg version

The correct formula is kubectl-cnpg. (Older tutorials say brew install cloudnative-pg, which is wrong.)

On Linux without Homebrew, use the upstream install script:

curl -sSfL \
  https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh \
  | sudo sh -s -- -b /usr/local/bin

Step 2.4 — Sanity check¶

The plugin can report on the operator and (later) clusters:

kubectl cnpg status --help          # confirm the plugin loads
kubectl get pods -n cnpg-system     # operator pod Running

A note on upgrades (relevant to your daily teardown)¶

Because you rebuild from zero each day, you will simply re-apply the pinned 1.29.1 manifest every time — there is no in-place upgrade to worry about during the learning phase. When you reach a long-lived cluster, upgrading the operator is "apply the newer manifest"; by default that triggers a rolling update of your PostgreSQL clusters and a switchover. Read the release notes before any real upgrade.

What could go wrong¶

Wrong/old version applied → you might be exposed to the metrics-exporter CVE. Always verify the image tag is 1.29.1 (or newer).
CRDs not registered (kubectl get crd | grep cnpg.io empty) → the apply failed; re-run with --server-side and check kubectl get events -n cnpg-system.
kubectl cnpg not found → the plugin binary is not on your PATH; check where Homebrew/installer placed it.

Where to go deeper¶

Next: Barman Cloud Plugin — the backup engine.

2. Operator & cnpg plugin¶