Installing Crunchy Postgres for Kubernetes Using Helm

This section provides instructions for installing and configuring Crunchy Postgres for Kubernetes using Helm.

There are two sources for the Crunchy Postgres for Kubernetes Helm chart:

• the Postgres Operator examples repo;
• the Helm chart hosted on the Crunchy container registry, which supports direct Helm installs.

The Postgres Operator Examples repo

Prerequisites

First, go to GitHub and fork the Postgres Operator examples repository, which contains the Crunchy Postgres for Kubernetes Helm installer.

https://github.com/CrunchyData/postgres-operator-examples/fork

Once you have forked this repo, you can download it to your working environment with a command similar to this:

YOUR_GITHUB_UN="$YOUR_GITHUB_USERNAME"
git clone --depth 1 "git@github.com:${YOUR_GITHUB_UN}/postgres-operator-examples.git"
cd postgres-operator-examples
Copy

For Powershell environments:

$env:YOUR_GITHUB_UN="YOUR_GITHUB_USERNAME"
git clone --depth 1 "git@github.com:$env:YOUR_GITHUB_UN/postgres-operator-examples.git"
cd postgres-operator-examples
Copy

The Crunchy Postgres for Kubernetes Helm chart is located in the helm/install directory of this repository.

Configuration

The values.yaml file for the Helm chart contains all of the available configuration settings for Crunchy Postgres for Kubernetes. The default values.yaml settings should work in most Kubernetes environments, but it may require some customization depending on your specific environment and needs.

For instance, it might be necessary to customize the image tags that are utilized using the controllerImages setting:

controllerImages:
  cluster: registry.developers.crunchydata.com/crunchydata/postgres-operator:ubi8-5.7.0-0
Copy

Please note that the values.yaml file is located in helm/install.

Logging

By default, Crunchy Postgres for Kubernetes deploys with debug logging turned on. If you wish to disable this, you need to set the debug attribute in the values.yaml to false, e.g.:

debug: false
Copy

Installation Mode

When Crunchy Postgres for Kubernetes is installed, it can be configured to manage PostgreSQL clusters in all namespaces within the Kubernetes cluster, just those within a single namespace, or, starting in CPK 5.7, those in a select set of namespaces. When managing PostgreSQL clusters in multiple namespaces, a ClusterRole and ClusterRoleBinding is created to ensure Crunchy Postgres for Kubernetes has the permissions it requires to properly manage PostgreSQL clusters across all namespaces. However, when Crunchy Postgres for Kubernetes is configured to manage PostgreSQL clusters within a single namespace only, a Role and RoleBinding is created instead.

In order to select between the multi-namespace and single-namespace modes when installing Crunchy Postgres for Kubernetes using Helm, the singleNamespace setting in the values.yaml file can be utilized:

singleNamespace: false
Copy

Specifically, if this setting is set to false (which is the default), then a ClusterRole and ClusterRoleBinding will be created, and Crunchy Postgres for Kubernetes will be able to manage PostgreSQL clusters in multiple namespaces. By default, the operator will manage PostgreSQL clusters in all namespaces. However, if you wish for the operator to only manage PostgreSQL clusters in a select set of namespaces, you will need to make a change to the helm/install/templates/manager.yaml file. Open the file and to the list of operator container environment variables, add a variable with the name PGO_TARGET_NAMESPACES, and for the value enter the desired namespaces in a double-quoted, comma-separated list. For example:

spec:
      {{- include "install.imagePullSecrets" . | indent 6 }}
      serviceAccountName: {{ include "install.serviceAccountName" . }}
      containers:
      - name: operator
        image: {{ required ".Values.controllerImages.cluster is required" .Values.controllerImages.cluster | quote }}
        env:
        - name: PGO_TARGET_NAMESPACES
          value: "namespace-one,namespace-two,namespace-three"
Copy

However, if the singleNamespace setting is set to true, then a Role and RoleBinding will be created instead, allowing Crunchy Postgres for Kubernetes to only manage PostgreSQL clusters in the same namespace utilized when installing the Crunchy Postgres for Kubernetes Helm chart.

High Availability

Starting in CPK 5.7, the operator has the ability to run multiple instances in a typical hot/cold high availability configuration. Essentially, one instance will be the leader while the other instances simply wait around to become the leader should the current primary instance fail. This capability is enabled by giving pgoControllerLeaseName a value in the values.yaml file, which sets the PGO_CONTROLLER_LEASE_NAME environment variable on the PGO Deployment. The value given to this environment variable is used to name the Lease object that will hold the Leader Election Lock. By default, this feature is enabled with a Lease name of cpk-leader-election-lease. If you wish to disable this capability, you can simply set pgoControllerLeaseName to an empty value.

With the feature enabled by setting a valid Lease name in PGO_CONTROLLER_LEASE_NAME, high availability can then be achieved by simply incrementing the replicas count in the values.yaml file.

Health Probes

Starting in CPK 5.7, the operator has the ability to perform liveness and readiness health probes. These probes are set on the operator Deployment and are enabled by default with the following settings:

livenessProbe:
  httpGet:
    path: /readyz
    port: 8081
  initialDelaySeconds: 15
  periodSeconds: 20
readinessProbe:
  httpGet:
    path: /healthz
    port: 8081
  initialDelaySeconds: 5
  periodSeconds: 10
Copy

To disable these probes, simply remove them from the operator Deployment.

Install

Once you have configured the Helm chart according to your specific needs, it can then be installed using helm:

helm install $NAME -n $NAMESPACE helm/install
Copy

Automated Upgrade Checks

By default, Crunchy Postgres for Kubernetes will automatically check for updates to itself and software components by making a request to a URL. If Crunchy Postgres for Kubernetes detects there are updates available, it will print them in the logs. As part of the check, Crunchy Postgres for Kubernetes will send aggregated, anonymized information about the current deployment to the endpoint. An upcoming release will allow for Crunchy Postgres for Kubernetes to opt-in to receive and apply updates to software components automatically.

Crunchy Postgres for Kubernetes will check for updates upon startup and once every 24 hours. Any errors in checking will have no impact on the operation of Crunchy Postgres for Kubernetes. To disable the upgrade check, you can set the disable_check_for_upgrades value in the Helm chart to true.

For more information about collected data, see the Crunchy Data collection notice.

Uninstall

To uninstall Crunchy Postgres for Kubernetes, remove all your PostgresCluster objects, then use the helm uninstall command:

helm uninstall $NAME -n $NAMESPACE
Copy

Helm [leaves the CRDs][helm-crd-limits] in place. You can remove them with kubectl delete:

kubectl delete -f helm/install/crds
Copy

The Crunchy Container Registry

Installing directly from the registry

Crunchy Data hosts an OCI registry that helm can use directly. (Not all helm commands support OCI registries. For more information on which commands can be used, see the Helm documentation.)

You can install Crunchy Postgres for Kubernetes directly from the registry using the helm install command:

helm install pgo oci://registry.developers.crunchydata.com/crunchydata/pgo
Copy

Or to see what values are set in the default values.yaml before installing, you could run a helm show command just as you would with any other registry:

helm show values oci://registry.developers.crunchydata.com/crunchydata/pgo
Copy

Downloading from the registry

Rather than deploying directly from the Crunchy registry, you can instead use the registry as the source for the Helm chart.

To do so, download the Helm chart from the Crunchy Container Registry:

# To pull down the most recent Helm chart
helm pull oci://registry.developers.crunchydata.com/crunchydata/pgo

# To pull down a specific Helm chart
helm pull oci://registry.developers.crunchydata.com/crunchydata/pgo --version 5.7.0
Copy

Once the Helm chart has been downloaded, uncompress the bundle

tar -xvf pgo-5.7.0.tgz
Copy

And from there, you can follow the instructions above on setting the Configuration and installing a local Helm chart.

Next Step: Create a Postgres Cluster

Now that you've installed Crunchy Postgres for Kubernetes, you're ready to Create a Postgres Cluster.

Next Step: Install Monitoring

No installation of Crunchy Postgres for Kubernetes is complete without monitoring! See our Tutorial on installing monitoring with Helm for details.