Installing Crunchy Postgres for Kubernetes Using Kustomize

If you are deploying using the installer from the Crunchy Data Customer Portal, please refer to the guide there for alternative setup information.

Prerequisites

First, go to GitHub and fork the Postgres Operator examples repository, which contains the Crunchy Postgres for Kubernetes Kustomize 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 installation project is located in the kustomize/install directory.

Configuration

While the default Kustomize install should work in most Kubernetes environments, it may be necessary to further customize the Kustomize project(s) according to your specific needs.

For instance, to customize the image tags utilized for the Crunchy Postgres for Kubernetes Deployment, the images setting in the kustomize/install/default/kustomization.yaml file can be modified:

images:
- name: postgres-operator
  newName: registry.developers.crunchydata.com/crunchydata/postgres-operator
  newTag: ubi8-5.7.0-0
Copy

If you are deploying using the images from the Crunchy Data Customer Portal, please refer to the private registries guide for additional setup information.

Please note that the Kustomize install project will also create a namespace for Crunchy Postgres for Kubernetes by default (though it is possible to install without creating the namespace, as shown below). To modify the name of namespace created by the installer, the kustomize/install/namespace/namespace.yaml should be modified:

apiVersion: v1
kind: Namespace
metadata:
  name: custom-namespace
Copy

The namespace setting in kustomize/install/default/kustomization.yaml should be modified accordingly.

namespace: custom-namespace
Copy

By default, Crunchy Postgres for Kubernetes deploys with debug logging turned on. If you wish to disable this, you need to set the CRUNCHY_DEBUG environmental variable to "false" that is found in the kustomize/install/manager/manager.yaml file. Alternatively, you can add the following to your kustomize/install/manager/kustomization.yaml to disable debug logging:

patchesStrategicMerge:
- |-
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: pgo
  spec:
    template:
      spec:
        containers:
        - name: operator
          env:
          - name: CRUNCHY_DEBUG
            value: "false"
Copy

You can also create additional Kustomize overlays to further patch and customize the installation according to your specific needs.

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.

The installation of the necessary resources for a cluster-wide or a single-namespace-limited operator is done automatically by Kustomize, as described below in the Install section. 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 kustomize/install/manager/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:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pgo
spec:
  template:
    spec:
      containers:
      - name: operator
        env:
        - name: PGO_TARGET_NAMESPACES
          value: "namespace-one,namespace-two,namespace-three"
Copy

The only other potential change you may need to make is to the Namespace resource and the namespace field if using a namespace other than the default postgres-operator.

High Availability

Starting in CPK 5.7, the operator can run in a typical hot/cold high availability configuration. When enabled, one pod will be the leader, while others wait to become the leader should the current leader fail. This capability is controlled by the PGO_CONTROLLER_LEASE_NAME environment variable on the PGO deployment. That value names the Lease object used to elect a leader of the deployment. The default is cpk-leader-election-lease, so you can achieve high availability by setting the Deployment replicas greater than one.

If you wish to disable this capability, empty or remove the PGO_CONTROLLER_LEASE_NAME environment variable and set replicas to 1.

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 the Kustomize project has been modified according to your specific needs, Crunchy Postgres for Kubernetes can then be installed using kubectl and Kustomize. To create the target namespace, run the following:

kubectl apply -k kustomize/install/namespace
Copy

This will create the default postgres-operator namespace, unless you have edited the kustomize/install/namespace/namespace.yaml resource. That Namespace resource should have the same value as the namespace field in the kustomization.yaml file (located either at kustomize/install/default or kustomize/install/singlenamespace, depending on whether you are deploying the operator with cluster-wide or single-namespace-limited permissions).

To install Crunchy Postgres for Kubernetes itself in cluster-wide mode (or multi-namespace mode if you have added the PGO_TARGET_NAMESPACES environment variable), apply the kustomization file in the default folder:

kubectl apply --server-side -k kustomize/install/default
Copy

To install Crunchy Postgres for Kubernetes itself in single-namespace-limited mode, apply the kustomization file in the singlenamespace folder:

kubectl apply --server-side -k kustomize/install/singlenamespace
Copy

The kustomization.yaml files in those folders take care of applying the appropriate permissions.

Install the Custom Resource Definition using Older Kubectl

This installer is optimized for Kustomize v4.0.5 or later, which is included in kubectl v1.21. If you are using an earlier version of kubectl to manage your Kubernetes objects, you should be able to create the namespace as described above, but when you run the kubectl apply --server-side -k kustomize/install/default command, you will get an error like:

Error: json: unknown field "labels"
Copy

To fix this error, download the most recent version of Kustomize. Once you have installed Kustomize v4.0.5 or later, you can use it to produce valid Kubernetes yaml:

kustomize build kustomize/install/default
Copy

The output from the kustomize build command can be captured to a file or piped directly to kubectl:

kustomize build kustomize/install/default | kubectl apply --server-side -f -
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 CHECK_FOR_UPGRADES environmental variable on the pgo Deployment to "false".

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

Uninstall

Once Crunchy Postgres for Kubernetes has been installed, it can also be uninstalled using kubectl and Kustomize. To uninstall Crunchy Postgres for Kubernetes (assuming it was installed in cluster-wide mode), the following command can be utilized:

kubectl delete -k kustomize/install/default
Copy

To uninstall Crunchy Postgres for Kubernetes installed with only namespace permissions, use:

kubectl delete -k kustomize/install/singlenamespace
Copy

The namespace created with this installation can likewise be cleaned up with:

kubectl delete -k kustomize/install/namespace
Copy

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 Kustomize for details.