Installation and upgrades

Installation on Kubernetes

Directly using the operator manifest

The operator can be installed like any other resource in Kubernetes,through a YAML manifest applied via kubectl .

You can install the latest operator manifest as follows:

kubectl apply -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.15.0.yaml

Once you have run the kubectl command, CloudNativePG will be installed in your Kubernetes cluster.

You can verify that with:

kubectl get deploy -n cnpg-system cnpg-controller-manager

Using the Helm Chart

The operator can be installed using the provided Using the Helm Chart .

Details about the deployment

In Kubernetes, the operator is by default installed in the cnpg-system namespace as a Kubernetes Deployment called cnpg-controller-manager . You can get more information by running:

kubectl describe deploy \
  -n cnpg-system \
  cnpg-controller-manager

As with any Deployment, it sits on top of a ReplicaSet and supports rollingupgrades. The default configuration of the CloudNativePG operatorcomes with a Deployment of a single replica, which is suitable for mostinstallations. In case the node where the pod is running is not reachableanymore, the pod will be rescheduled on another node.

If you require high availability at the operator level, it is possible tospecify multiple replicas in the Deployment configuration - given that theoperator supports leader election. Also, you can take advantage of taints andtolerations to make sure that the operator does not run on the same nodes wherethe actual PostgreSQL clusters are running (this might even include the controlplane for self-managed Kubernetes installations).

Upgrades

Important

Please carefully read the Release notes before performing an upgrade as some versions might require extra steps.

Upgrading CloudNativePG operator is a two-step process:

1. upgrade the controller and the related Kubernetes resources2. upgrade the instance manager running in every PostgreSQL pod

Unless differently stated in the release notes, the first step is normally doneby applying the manifest of the newer version for plain Kubernetesinstallations, or using the native package manager of the used distribution(please follow the instructions in the above sections).

The second step is automatically executed after having updated the controller,by default triggering a rolling update of every deployed PostgreSQL instance touse the new instance manager. The rolling update procedure culminates with aswitchover, which is controlled by the primaryUpdateStrategy option, bydefault set to unsupervised . When set to supervised , users need to completethe rolling update by manually promoting a new instance through the cnpg plugin for kubectl .

Important

In case primaryUpdateStrategy is set to the default value of unsupervised , an upgrade of the operator will trigger a switchover on your PostgreSQL cluster, causing a (normally negligible) downtime.

Since version 1.10.0, the rolling update behavior can be replaced with in-placeupdates of the instance manager. The latter don’t require a restart of thePostgreSQL instance and, as a result, a switchover in the cluster.This behavior, which is disabled by default, is described below.

In-place updates of the instance manager

By default, CloudNativePG issues a rolling update of the clusterevery time the operator is updated. The new instance manager shipped with theoperator is added to each PostgreSQL pod via an init container.

However, this behavior can be changed via configuration to enable in-placeupdates of the instance manager, which is the PID 1 process that keeps thecontainer alive.

Internally, any instance manager from version 1.10 of CloudNativePGsupports injection of a new executable that will replace the existing one,once the integrity verification phase is completed, as well as gracefultermination of all the internal processes. When the new instance managerrestarts using the new binary, it adopts the already running postmaster.

As a result, the PostgreSQL process is unaffected by the update, refrainingfrom the need to perform a switchover. The other side of the coin, is thatthe Pod is changed after the start, breaking the pure concept of immutability.

You can enable this feature by setting the ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES environment variable to 'true' in the Operator configuration .

The in-place upgrade process will not change the init container image inside thePods. Therefore, the Pod definition will not reflect the current version of theoperator.

Important

This feature requires that all pods (operators and operands) run on the same platform/architecture (for example, all linux/amd64 ).

Compatibility among versions

CloudNativePG follows semantic versioning. Every release of theoperator within the same API version is compatible with the previous one.The current API version is v1, corresponding to versions 1.x.y of the operator.

In addition to new features, new versions of the operator contain bug fixes andstability enhancements. Because of this, westronglyencourageuserstoupgradetothelatestversionoftheoperator , as each version is released in order tomaintain the most secure and stable Postgres environment.

CloudNativePG currently releases new versions of the operator atleast monthly. If you are unable to apply updates as each version becomesavailable, we recommend upgrading through each version in sequential order tocome current periodically and not skipping versions.

Important

In 2022, EDB plans an LTS release for CloudNativePG in environments where frequent online updates are not possible.

The Release notes page contains a detailed list of thechanges introduced in every released version of CloudNativePG,and it must be read before upgrading to a newer version of the software.

Most versions are directly upgradable and in that case, applying the newermanifest for plain Kubernetes installations or using the native packagemanager of the chosen distribution is enough.

When versions are not directly upgradable, the old version needs to beremoved before installing the new one. This won’t affect user data butonly the operator itself.