Upgrading from 2026.9 to 2026.10.1 (Innovation Release) Innovation Release

Upgrade from 2026.9 to 2026.10.1.

Role: Infrastructure engineer

Prerequisites

• Administrative access to the Kubernetes cluster (kubectl, helm).
• Required tools:
  • helm (latest version recommended)
  • kubectl
  • edbctl, the Hybrid Manager CLI — see the edbctl compatibility matrix for the supported version.

Upgrade 2026.9 → 2026.10.1

This release changes the telemetry stack that powers Query Diagnostics: ClickHouse partially replaces Prometheus/Thanos, and the pg_stat_ch extension replaces edb_stat_monitor as the source of query-level monitoring data. This upgrade has two parts:

1. The Hybrid Manager (HM) platform upgrade — a one-time action that upgrades HM itself. This also restarts every Postgres cluster in your estate once, as a side effect of the Barman Cloud Plugin bump.
2. A per-cluster operand-set migration — a separate, per-Postgres-cluster action that moves each cluster onto the new operand-set so it can collect telemetry again.

Complete the steps in the order given:

1. Create new secrets.
2. Upgrade the operator to 2.2 or later, if it isn't already.
3. Update spec.version and trigger the HM platform upgrade.
4. As soon as possible afterward, for each Postgres cluster: whitelist both operand-sets, perform the cluster's major/minor upgrade to move it onto the new operand, then manually create the pg_stat_ch extension.

Complete step 4 for every Postgres cluster as soon as possible after the HM platform upgrade. Once HM is on 2026.10.1, the old telemetry pipeline that read edb_stat_monitor is no longer deployed platform-wide. A cluster that hasn't yet been migrated to the new operand-set and had pg_stat_ch created loses Query Diagnostics data entirely in the meantime — it isn't a fallback to the old data, it's a gap.

Create new secrets

Before upgrading, create the new secrets required for this release:

edbctl hm create-install-secrets --version v2026.10.1

For more CLI options, see edbctl hybrid-manager. To customize your component's secrets, see Customizing secrets.

Upgrade the operator

The commands below use edb-hcp-operator-system — use the namespace where your operator is actually installed. If you migrated from the bootstrap method, the conversion transfers Helm ownership onto edbpgai-bootstrap, so use that namespace instead.

Upgrade the edb-hcp-operator Helm chart using edbctl:

edbctl hm upgrade-operator \
  --release-name edb-hcp-operator \
  --namespace edb-hcp-operator-system \
  --registry-uri docker.enterprisedb.com/pgai-platform \
  --registry-username pgai-platform \
  --registry-password <password>

Or upgrade directly with Helm:

1. Create the values file:

   → WrapCopy

   cat <<EOF > edb-hcp-operator.values.yaml
   controllerManager:
     manager:
       image:
         repository: docker.enterprisedb.com/pgai-platform/edb-hcp-operator/manager
         tag: <OPERATOR_VERSION>
   imagePullSecrets:
     - name: edb-cred
   EOF

2. Run the upgrade:

   → WrapCopy

   helm upgrade --install \
     --version <OPERATOR_VERSION> \
     --values edb-hcp-operator.values.yaml \
     -n edb-hcp-operator-system \
     edb-hcp-operator enterprisedb-edbpgai/edb-hcp-operator

Upgrade Hybrid Manager

1. In your HybridControlPlane manifest (hybridmanager.yaml), update the spec.version field to v2026.10.1:

   → WrapCopy

   apiVersion: edbpgai.edb.com/v1alpha1
   kind: HybridControlPlane
   metadata:
     name: edbpgai
   spec:
     version: v2026.10.1 # was v2026.9.0

2. Apply the updated manifest:

   → WrapCopy

   kubectl apply -f hybridmanager.yaml

3. Trigger the upgrade:

   → WrapCopy

   kubectl annotate hybridcontrolplane edbpgai --overwrite edbpgai.com/ready-for-upgrade=true

4. Monitor progress:

   → WrapCopy

   kubectl get hybridcontrolplane edbpgai -w

This step restarts every Postgres cluster in your estate once, to apply the updated Barman Cloud Plugin (version 0.15.0, bringing significantly faster restore times for compressed backups). This restart is automatic and applies platform-wide — it's separate from the per-cluster operand-set migration described next.

Migrate each Postgres cluster to the new operand-set

Once HM itself is on 2026.10.1, migrate each Postgres cluster to the new operand-set as soon as possible, to restore its Query Diagnostics telemetry. A cluster you haven't migrated yet keeps running and stays healthy, but has no Query Diagnostics data until you complete this migration.

Enable the major/minor upgrade path

Starting in HM 1.3.2, operand images carry an operand-set version, and the beacon agent only treats images matching an allowed pattern as discoverable. Innovation Releases for HM 2026.7–2026.9 shipped operand-set 1.2.x. HM 2026.10.1 requires operand-set 1.3.0 or later and only works with operand images from that operand-set onward.

A cluster still running a 1.2.x operand image becomes undiscoverable to HM once you narrow operandSetVersions to 1.3.x only. While you still have clusters on 1.2.x images, whitelist both patterns so the major/minor upgrade action in the HM console can resolve each cluster's current image.

Whitelist both operand-sets on the HybridControlPlane (HCP) CR — the source of truth for this setting. Don't edit the beacon-agent-k8s-config configmap directly; it's reconciled from the HCP CR and a direct edit will drift or revert.

spec:
  beaconAgent:
    provisioning:
      operandSetVersions:
        - 1\.2\.[0-9]+    # previous operand-set (current cluster images) — keeps them discoverable
        - 1\.3\.[0-9]+    # new operand-set shipped with IR 2026.10.1

Apply it via values.yaml when you upgrade HM, or afterward with kubectl:

# Inspect the current value
kubectl get hcp <name> -o jsonpath='{.spec.beaconAgent.provisioning.operandSetVersions}{"\n"}'

# Patch to whitelist both operand-sets
kubectl patch hcp <name> --type=merge -p '{
  "spec": {"beaconAgent": {"provisioning": {"operandSetVersions": ["1\\.2\\.[0-9]+", "1\\.3\\.[0-9]+"]}}}
}'

With both whitelisted, HM can discover each cluster's current 1.2.x image, the major/minor upgrade action in the HM console resolves it, and the upgrade path — including extensions — becomes available so you can move the cluster onto a 1.3.x operand.

Follow this phased approach as you migrate:

Perform the major upgrade for each Postgres cluster

Once both operand-sets are whitelisted (phase 1 above), move each Postgres cluster onto a 1.3.x operand as soon as possible, since the cluster has no Query Diagnostics data until this step and the next are both complete. For an HM-managed cluster:

1. From the cluster's main page in the HM console, select Quick Actions > Upgrade Cluster, then select Major Upgrade.
2. Select a 1.3.x operand image as the new major version image.
3. Review the upgrade path. Select Continue.
4. Review the specific package changes expected with the upgrade. If everything looks correct, select Upgrade Cluster.
5. Use the Monitoring and Logs tabs to monitor the process and troubleshoot any unexpected behavior.

This is the same procedure used for any Postgres major version upgrade in HM. For the full procedure and rollback considerations, see Postgres major version upgrades.

Enable pg_stat_ch on each migrated cluster

After a cluster's image is on a 1.3.x operand, HM-managed clusters already have pg_stat_ch in shared_preload_libraries and configured for OpenTelemetry — moving the image forward doesn't, by itself, create the extension in the database. You must do that manually, once per cluster:

CREATE EXTENSION IF NOT EXISTS pg_stat_ch WITH SCHEMA edb_internals;

HM retains edb_stat_monitor — it's still used internally — and only removes it in IR 2026.11, so there's no need to drop it yourself. Enabling the pg_stat_ch extension itself doesn't require a cluster restart — this is separate from the platform-wide restart that already happened when you upgraded HM.

Self-managed clusters (external CNPG and bare-metal)

Self-managed clusters — external CNPG (pg4k) clusters and bare-metal installations — need a separate, more involved process than HM-managed clusters, because pg_stat_ch isn't bundled with their images automatically.

For external CNPG clusters running the enterprise build (pg4k), find a suitable operand image in the Asset Library: select the Asset Library tab in the HM console, open Container Images, then search for the postgresql image repository. Open an image tag's Image Tag Details page and check its extensions table for pg_stat_ch to confirm the tag includes it. See Container images for details on searching and filtering. Once you've identified a suitable image, perform the cluster's major version upgrade as described in Perform the major upgrade for each Postgres cluster, then create the extension as described in Enable pg_stat_ch on each migrated cluster. OSS CNPG doesn't support mounting the extension from the official CloudNativePG extension catalogue, so you need a custom image that installs the EDB build of pg_stat_ch.

For bare-metal installations, install pg_stat_ch and configure it to point at your ClickHouse server before creating the extension. For the full procedure — package installation, shared_preload_libraries, and the OpenTelemetry settings — see Monitoring Postgres with pg_stat_ch in the EDB Postgres AI for ClickHouse documentation.

Scenario behavior change: core now includes observability

From this release onward, selecting the core installation scenario automatically includes observability, because core now requires ClickHouse. This applies on fresh installs, upgrades, and existing installations alike — if your HybridControlPlane manifest lists only core, upgrading to 2026.10.1 deploys the observability components alongside it. You don't need to add observability to spec.scenarios yourself. However, having the observability components deployed doesn't by itself restore Query Diagnostics data for your Postgres clusters — you still need to migrate each cluster to the new operand-set and enable pg_stat_ch, as described earlier in this guide, to actually make use of it.

Upgrading multi-DC deployments

In a multi-DC deployment, all locations must run the same HM version. Upgrade the primary location first, then upgrade each data-only secondary location to the same version immediately after. For the full procedure, see Upgrading a multi-DC deployment.

Troubleshooting upgrade job failures

The upgrade operator creates and manages upgrade jobs automatically. If an upgrade job fails and doesn't reach a Complete or Succeeded state, the operator pauses and retries. It doesn't proceed to apply updated manifests until the job succeeds.

To investigate a failed upgrade job:

1. Check the status of upgrade jobs:

   → WrapCopy

   kubectl get jobs -n edbpgai-bootstrap -l edbpgai.edb.com/hm-upgrader=true

2. Check the logs for the failed job:

   → WrapCopy

   kubectl logs job/<job-name> -n edbpgai-bootstrap

   Replace <job-name> with the name of the failed job from the previous command.

3. Check the HybridControlPlane status for upgrade-related events:

   → WrapCopy

   kubectl describe hybridcontrolplane edbpgai

If the issue persists after the operator retries, contact EDB support with the job logs.