Upgrading Hybrid Manager Innovation Release

Suggest edits

Role: Infrastructure Engineer

Prerequisites:

  • Administrative access to the Kubernetes cluster (kubectl, helm).
  • Access to the values.yaml file used for the current installation.
  • Required Tools:
    • helm (Latest version recommended)
    • cmctl (Cert-Manager CLI) - Required for 2025.11+

Upgrade strategy

Hybrid Manager upgrades are sequential. You must upgrade through the major versions in order to ensure database schemas and internal secrets are migrated correctly.

Identify your current version and select the appropriate path:

  1. Current: 1.3.x → Upgrade to 2025.11
  2. Current: 2025.11 → Upgrade to 2025.12
Warning

You cannot successfully skip versions (for example, you cannot jump from 1.2 directly to 2025.12). You must perform the intermediate upgrade steps to ensure data integrity.

Upgrade 1.3.x → 2025.11

This release increases the Certificate Authority (CA) TTL to 10 years and refactors the Istio implementation on OpenShift.

Certificate renewal (required)

The internal self-signed CA has been updated. You must regenerate certificates to apply the new 10-year TTL.

  1. Install `cmctl (for example, brew install cmctl).

  2. Regenerate certificates:

    # Global CA
cmctl renew -n cert-manager global-ca-cert
 
# Leaf Certificates
cmctl renew -n upm-beacon beacon-int-ca
cmctl renew -n istio-system beaco-istio-gw-cert

OpenShift specifics: Istio Migration

Note

You can skip this step if you are not running on Red Hat OpenShift (RHOS).

HM is no longer using the OLM-managed Maistra Service Mesh with RHOS. You must manually clean up the old resources before the upgrade.

  1. Scale down the operator.

    kubectl scale deployment --replicas 0 edb-hcp-operator-controller-manager -n edbpgai-bootstrap

  2. Remove old Maistra resources.

    kubectl delete servicemeshmemberrolls.maistra.io -n istio-system default
kubectl delete servicemeshcontrolplanes.maistra.io -n istio-system upm

  3. Bulk delete members.

    kubectl get servicemeshmember -A -ojsonpath='{range .items[*]}{"kubectl delete servicemeshmember "}{@.metadata.name}{" -n "}{@.metadata.namespace}{"\n"} {end}' | while read -r line; do eval $line; done
Important

Do not resume the operator at this point. Proceed with the upgrade. The Helm upgrade automatically scales the operator back up.

Perform the upgrade

  1. Update the repo.

    helm repo update

  2. Perform the upgrade.

    helm upgrade --install edbpgai-bootstrap enterprisedb-edbpgai/edbpgai-bootstrap \
  --version 2025.11.0 \
  --values values.yaml \
  --namespace edbpgai-bootstrap \
  --wait

Upgrade 2025.11 → 2025.12

This release introduces new authentication secrets, updates the Transporter configuration, and deprecates several Beacon parameters.

Create Fernet secret

Before installing the 2025.12 chart, you must manually create the dex-fernet-key.

FERNET_KEY=$(head -c 32 /dev/urandom | base64)

kubectl create secret generic dex-fernet-key \
  --from-literal=fernet-key="$FERNET_KEY" \
  -n upm-dex

Update values.yaml

  1. Add Transporter domain to values.yaml.

    Add a new global parameter dms_domain_name. It must match your existing transporter-rw-service.domain_name.

    parameters:
global:
    dms_domain_name: <your-transporter-domain>

  2. Remove deprecated fields.

    Remove the following fields from your values.yaml:

    • beaconAgent.plaintext
    • beaconAgent.beaconServerAddress
    • beaconAgent.tlsInsecure
    • beaconAgent.inCluster

Critical infrastructure workaround

To ensure Postgres workloads schedule correctly, you must add a taint to a specific node pool.

  • Taint key: edbaiplatform.io/postgres
  • Value: 'true'
  • Effect: NoSchedule

Perform the upgrade

  1. Update your Helm repo.

    helm repo update

  2. Perform the upgrade.

    helm upgrade --install edbpgai-bootstrap enterprisedb-edbpgai/edbpgai-bootstrap \
  --version 2025.12.0 \
  --values values.yaml \
  --namespace edbpgai-bootstrap \
  --wait

Post-upgrade fixes

  1. Re-initialize SPIRE (if trust domain changed).

    In 2025.12, the trust_domain parameter is removed and defaults to portal_domain_name. If the trust_domain you set in version 1.3.0 differs from your Portal Domain, SPIRE breaks.

    • Fix:

      kubectl scale statefulset spire-server -n spire-server --replicas=0
kubectl delete pvc -l app=spire-server -n spire-server
kubectl scale statefulset spire-server -n spire-server --replicas=1

  2. Reconfigure models

    Knowledge Bases (KBs) may disappear from the UI after upgrade. To workaround, log in to the Portal, navigate to the Model Configuration page, and re-save your model settings.

← Prev

Hybrid Manager Multi-DC deployment guide

↑ Up

Using Hybrid Manager

Next →

PGAIHM High Availability & Disaster Recovery (HA/DR)