EDB Klio Operator Helm Chart v0.0.15

The EDB Klio Operator Helm chart allows you to deploy the Klio Operator in your Kubernetes cluster. It is distributed as a private OCI image.

Prerequisites

Before installing the Klio Operator, ensure you have:

• Helm – see the Helm installation guide
• Kubernetes cluster with appropriate permissions
• Credentials to access the registry hosting the Helm chart, the Klio operator image, and the Klio operand image.
• CloudNativePG Operator already installed in your Kubernetes cluster. See the CloudNativePG installation guide.
• cert-manager (optional, but strongly recommended for managing TLS certificates). See the cert-manager installation guide.
• Prometheus Operator (optional, for operator monitoring). See the Prometheus Operator installation guide.

Installation

Step 1: Registry Authentication

Authenticate with the EDB registry where the Helm chart is hosted:

helm registry login helm.oci.cloudsmith.io -u enterprisedb/k8s -p <TOKEN>

Replace <TOKEN> with the required credentials.

Step 2: Create an Image Pull Secret

Create a Kubernetes secret to allow the operator to pull container images from the registry:

kubectl create secret docker-registry klio-registry-secret \
  --docker-server=docker.enterprisedb.com \
  --docker-username=k8s \
  --namespace cnpg-system \
  --docker-password=<TOKEN>

Step 3: Create a values file

Create a values.yaml file with your configuration. At minimum, set the image pull secret created in the previous step. If you have not installed cert-manager or the Prometheus Operator, disable them to avoid errors during installation:

controllerManager:
  manager:
    image:
      pullSecrets:
        - name: klio-registry-secret

# Uncomment if cert-manager is not installed
# certmanager:
#   enable: false

# Uncomment if the Prometheus Operator is not installed
# prometheus:
#   enable: false

See the Configuration section for the full list of available parameters. You will reuse this file for future upgrades.

Step 4: Install the Helm Chart

Deploy the Klio Operator to your cluster:

helm install klio-operator \
  oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \
  --version 0.0.15 \
  --namespace cnpg-system \
  -f values.yaml

Step 5: Verify Installation

After installation, verify that the Klio Operator is running:

kubectl get pods -n cnpg-system -l app.kubernetes.io/name=klio

You should see the operator pod in a Running state. Check the logs to ensure there are no errors:

kubectl logs -n cnpg-system -l app.kubernetes.io/name=klio -f

Verify that the Custom Resource Definitions (CRDs) were created:

kubectl get crds | grep klio.enterprisedb.io

You should see CRDs like servers.klio.enterprisedb.io and pluginconfigurations.klio.enterprisedb.io.

Configuration

Inspecting the Chart

You can download the Helm chart to inspect its contents, review the default values, and understand what resources it will create:

helm pull oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \
  --version 0.0.15 \
  --untar

This downloads the chart and extracts it into the klio-operator-chart folder, where you can review the templates, the default values.yaml, and other chart files.

Configuration Reference

Custom CNPG API Group

Klio targets the CloudNativePG API group (postgresql.cnpg.io, version v1) by default. If you are running a CNPG-based operator that uses a different API group or version (for example, EDB Postgres® AI for CloudNativePG™ Cluster), you must tell the Klio operator which group and version to use.

Set the --custom-cnpg-group and --custom-cnpg-version flags via the controllerManager.manager.args Helm value:

controllerManager:
  manager:
    args:
      # … other flags …
      - "--custom-cnpg-group=postgresql.k8s.enterprisedb.io"
      - "--custom-cnpg-version=v1"

The operator passes these values to every Klio sidecar as the CUSTOM_CNPG_GROUP and CUSTOM_CNPG_VERSION environment variables, so the sidecar and the operator always use the same API group and version.

Upgrades

A complete upgrade consists of three steps that must be performed in order:

1. Upgrade the CRDs — apply updated CRD manifests
2. Upgrade the Operator — run helm upgrade
3. Upgrade the Klio Server and client — upgrade operand images

Upgrade the CRDs

Step 1: Download the new chart

Download the new version of the Helm chart to access the updated CRD manifests:

helm pull oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \
  --version 0.0.15 \
  --untar

Step 2: Review CRD changes

Before applying, review the CRD changes to understand what is being modified:

kubectl diff -f klio-operator-chart/crds/

Step 3: Apply the updated CRDs

Apply the CRD manifests to your cluster:

kubectl apply --server-side --force-conflicts -f klio-operator-chart/crds/

Step 4: Clean up

Remove the extracted chart directory:

rm -rf klio-operator-chart

Upgrade the Operator

To upgrade the Klio Operator to a newer version, run the following Helm upgrade command:

helm upgrade klio-operator \
  oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \
  --version 0.0.15 \
  --namespace cnpg-system \
  -f values.yaml

See the Helm upgrade documentation for more details on this and other upgrade options.

Upgrade the Klio Server and client

After upgrading the operator and the CRDs, Klio images in Server resources and the ones used as sidecars in Cluster resources should be upgraded as well. We recommend using the same version for the operator and the operand.

Upgrade Klio servers

Klio servers are not automatically updated when a new operand image is released. Update the spec.image field with the new image reference:

kubectl patch server <server-name> -n <namespace> \
  --type merge \
  -p '{"spec":{"image":"docker.enterprisedb.com/k8s/klio:v0.0.15"}}'

Verify that the Klio Server pods are running the latest version:

kubectl get pods -l klio.enterprisedb.io/klio-server -A \
  -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,IMAGE:.spec.containers[0].image'

kubectl delete statefulset -l klio.enterprisedb.io/klio-server=<SERVER_NAME> -n <NAMESPACE>

Upgrade Klio client sidecars

The Pods of the CNPG instances need to be recreated to run the new Klio image. You can use the CNPG kubectl plugin to trigger a rolling update:

kubectl cnpg restart <cluster-name>

Refer to the CloudNativePG documentation for guidance on performing rolling updates.

Verify that the sidecar containers are running the latest version:

kubectl get pods -l cnpg.io/cluster -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{range .spec.initContainers[?(@.name=="klio-plugin")]}{.image}{end}{"\n"}{end}'

Uninstalling

To uninstall the Klio Operator:

helm uninstall klio-operator --namespace cnpg-system

To remove the CRDs after uninstalling:

kubectl delete crd servers.klio.enterprisedb.io
kubectl delete crd pluginconfigurations.klio.enterprisedb.io