Upgrading from 2026.10.1 to 2026.11 (Innovation Release) Innovation Release

Upgrade from 2026.10.1 to 2026.11. This upgrade changes more than the HM version: it moves key resources to a new namespace, changes how Chat Agent gets its models, and briefly pauses database management while that move happens.

Role: Infrastructure engineer

Prerequisites

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

What to expect during the upgrade

Starting in 2026.11, HM moves to the edb-system namespace instead of default:

• Beacon server resources — your clusters, backups, backup schedules, locations, AI pipelines, and automations, plus the secrets and certificates that Beacon creates for each cluster. A pre-upgrade job and a post-upgrade job copy these for you automatically.
• Install secrets — HM moves edb-object-storage for you. Create the rest — hm-portal-bootstrap, langflow-secret, the db-* secrets, and so on — in edb-system yourself before you upgrade. See Create secrets.
• OSS Library app catalog — the PackageRepository resource and the packages it lists. The upgrade moves this for you automatically.
• Installed OSS Library apps — the upgrade doesn't move apps that you installed before it. See Choose when to recreate OSS Library apps.

If you have scripts, monitoring, or kubectl commands that read these resources in default, update them to use edb-system.

Chat Agent also stops relying on the inference services you configured in HM, and that configuration doesn't carry over. If you use Chat Agent, see Chat Agent model credentials.

Database management downtime

• The time depends on how many resources you have. Each backup is one resource, so an installation with thousands of backups takes much longer than one with a few hundred. If you have a long backup history, plan the upgrade for a maintenance window.
• The HybridControlPlane stays in deploying until the post-upgrade job finishes. The post-upgrade job removes the old copies from default. The Beacon server is running again by then, so this phase doesn't affect database management.
• Don't delete or restart the upgrade jobs while they run.

Estimating the time and tuning the upgrade job

Before you upgrade, count the Beacon resources in default that the pre-upgrade job copies:

total=0
for r in locations.beacon clusterwrappers.beacon clusterresources.beacon \
         beaconpackagemetadatas.beacon beaconappwrappers.beacon tasks.tasks.beacon \
         remotepgs.beacon backupwrappers.beacon scheduledbackupwrappers.beacon \
         aidbpipelineconfigs.beacon aidbpipelinerecords.beacon beaconpackages.beacon \
         taskapprovals.tasks.beacon maintenancewindows.tasks.beacon \
         automations.automations.beacon remotequeries.beacon; do
  n=$(kubectl get "$r.enterprisedb.com" -n default --no-headers | wc -l)
  printf '%-34s %s\n' "$r" "$n"
  total=$((total + n))
done
echo "total: $total"

The total line is the number of resources that the job copies. Backups are usually most of them, so a long backup history is what makes the job slow.

The following table shows the approximate time that the pre-upgrade job needs to copy that many resources, which is the time database management is unavailable. The figures come from one measurement of an installation with about 2,800 resources, nearly all of them backups, scaled to other sizes, so treat them as estimates:

The post-upgrade job deletes the old copies in less time than the copy takes (about a third at 100m CPU), and it runs while the Beacon server is up, so it doesn't affect database management.

The upgrade job gets 1 CPU and 1Gi of memory by default, which is enough for installations with a few thousand resources. If a job is killed for lack of memory (its pod shows OOMKilled), raise the limit in spec.globalParameters of your HybridControlPlane:

spec:
  globalParameters:
    upgrade_job_memory_limit: "3Gi"

You can also set upgrade_job_cpu_limit, upgrade_job_cpu_request and upgrade_job_memory_request. The values apply to jobs that the operator creates afterwards. To retry a failed job with new values, set them and delete the failed job. The operator creates it again.

Upgrade 2026.10.1 → 2026.11

Complete the steps in the order given:

1. If you have OSS Library apps, decide when to recreate them. EDB recommends that you delete them before the upgrade. See Choose when to recreate OSS Library apps.
2. Upgrade the operator to 2.3 or later, if it isn't already.
3. Create secrets, including Chat Agent model credentials if you use Chat Agent.
4. If you have the ai or migration scenarios enabled, download any Migration Portal reports that you want to keep. Leave spec.scenarios as it is. The upgrade removes both scenarios for you. See Prepare for the removal of the ai and migration scenarios.
5. Update spec.version (and spec.scenarios, if you're enabling Chat Agent) and trigger the HM platform upgrade.

Choose when to recreate OSS Library apps

This section only applies if you have OSS Library apps installed.

Starting with HM 2026.11, HM tracks OSS Library apps in the edb-system namespace instead of the default namespace. The upgrade doesn't move the apps that you installed on 2026.10.1 or earlier versions. If you don't delete the existing apps before or after the upgrade, those apps keep running and serving, but HM still tracks them in default.

You can delete an app before the upgrade (option A, recommended) or after it (option B). Option A removes the app completely through the console, but it's unavailable until you reinstall it after the upgrade. Option B keeps the app running through the upgrade, but you must manually remove the old copy with kubectl afterward.

Option A (recommended): delete the app before the upgrade

With this option, HM 2026.10.1 removes the app completely, including its storage and route. You don't need to run any kubectl commands. The app isn't available from the time that you delete it until you install it again after the upgrade.

1. Export any data that you need from the app.
2. In the HM console, on 2026.10.1, delete the app.

Then continue with the upgrade. See Finish recreating OSS Library apps once HM is on 2026.11.

Upgrade the operator

The operator's namespace depends on how it was installed. Fresh operator installs use edb-hcp-operator-system. Installations converted from the bootstrap method usually remain in edbpgai-bootstrap. Set OPERATOR_NS to the namespace of your operator release:

OPERATOR_NS=$(helm list -A --filter '^edb-hcp-operator$' --no-headers | awk '{print $2}')
echo "$OPERATOR_NS"

If echo prints nothing, your release isn't named edb-hcp-operator and the environment variable OPERATOR_NS is empty. Run helm list -A to find its actual name and namespace, then set OPERATOR_NS to that namespace yourself.

Choose one of the following methods to upgrade the edb-hcp-operator Helm chart.

Using edbctl (recommended)

Run the upgrade:

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

Using 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 "$OPERATOR_NS" \
     edb-hcp-operator enterprisedb-edbpgai/edb-hcp-operator

Create secrets

Install secrets in edb-system

Before upgrading, use edbctl 1.11 or later to create the install secrets in the edb-system namespace:

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

Use the same --scenario options that you listed in spec.scenarios. For more information, see Create component secrets.

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

Chat Agent model credentials

In 2026.11, Chat Agent no longer uses the inference services that you configured in HM, and that configuration doesn't carry over automatically. If you want to keep using Chat Agent, you'll need to configure it again.

Create the chatbot-model-creds secret yourself with edbctl, using the chatbot scenario:

edbctl hybrid-manager create-install-secrets --version v2026.11.0 --scenario chatbot

Then make sure chatbot is included in spec.scenarios when you update the manifest in Upgrade Hybrid Manager.

The secret holds the endpoint, model name, and API key for each model that Chat Agent uses. For the settings and options, see Customizing Chat Agent model secrets. For how Chat Agent uses the models, see Configuring the Chat Agent.

Prepare for the removal of the ai and migration scenarios

Prepare for the removal of the ai or migration scenarios, only if you had them enabled in spec.scenarios on 2026.10.1.

HM 2026.11 removes the ai and migration installation scenarios. The components of the ai scenario were already removed in 2026.10.1, so for ai the upgrade removes only the scenario itself. For migration, it removes the scenario and its components.

Leave spec.scenarios as it is when you update the manifest. The upgrade removes both scenarios for you, and you don't need to take any further action.

Upgrade Hybrid Manager

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

   → WrapCopy

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

   If you want to use Chat Agent and already created its required secret, also add chatbot to the scenarios that you already list in spec.scenarios. Keep the others as they are. For example, if you only had core:

   → WrapCopy

   spec:
     scenarios:
       - core
       - chatbot
     version: v2026.11.0 # was v2026.10.1

2. Apply the updated manifest:

   → WrapCopy

   kubectl apply -f hybridmanager.yaml

3. Monitor progress:

   → WrapCopy

   kubectl get hybridcontrolplane edbpgai -w

   To follow the pre-upgrade and post-upgrade jobs that move your resources to edb-system (see What to expect during the upgrade), also run:

   → WrapCopy

   kubectl get jobs -n "$OPERATOR_NS" -l edbpgai.edb.com/hm-upgrader=true
   kubectl logs -f job/hm-pre-upgrader-2026-10-to-2026-11 -n "$OPERATOR_NS"
   kubectl logs -f job/hm-post-upgrader-2026-10-to-2026-11 -n "$OPERATOR_NS"

   The logs list every object that the job copies or deletes, and end with a summary that shows how many objects were copied or deleted and how many failed.

Finish recreating OSS Library apps

This section only applies if you have OSS Library apps installed.

If you took option A, reinstall the app now: in the HM console, install the app again from the OSS Library, then load the data you exported earlier into it and point any scripts or integrations at its new URL.

If you took option B, use the following steps to delete the app and remove the old copy.

Option B: delete the app after the upgrade

Use this option if the app can't be unavailable while you upgrade. It keeps running and stays editable until you replace it; removing the old copy by hand is the only step that needs kubectl.

To recreate the app:

1. Export any data that you need from the app.

2. In the HM console, delete the app. This removes only the app's entry — the app itself keeps running, with its storage and route, until you remove it manually with kubectl.

3. In the HM console, install the app again from the OSS Library. The new app is available as soon as you install it, but it's a new installation with a new app ID and an empty volume — load the data you exported earlier into it, and point any scripts or integrations at its new URL.

4. Once you've switched over, remove the old copy of the deleted app. List the apps in the default namespace and find the one with the name of the app that you deleted:

   → WrapCopy

   kubectl get beaconapp -n default

   Then delete it:

   → WrapCopy

   kubectl delete beaconapp <app-id> -n default

   Replace <app-id> with the value in the NAME column. This uninstalls the old app, including its storage.

Apps that you install after the upgrade are tracked in edb-system and need no extra steps.

Disabling edb_stat_monitor data collection

Query data is collected by pg_stat_ch, so you can stop edb_stat_monitor from collecting data on existing clusters.

1. Set this Postgres parameter on the cluster:

   → WrapCopy

   edb_stat_monitor.edbsm_track = none

2. Reload the configuration. No restart is needed:

   → WrapCopy

   > SELECT pg_reload_conf();

3. Check that the change is active:

   → WrapCopy

   > SHOW edb_stat_monitor.edbsm_track;   -- returns: none

The change applies to the primary and all replicas.

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 -A -l edbpgai.edb.com/hm-upgrader=true

2. Check the logs for the failed job:

   → WrapCopy

   kubectl logs job/<job-name> -n <namespace>

   Replace <job-name> and <namespace> with 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.