Install Hybrid Manager Innovation Release

Suggest edits

This documentation covers the current Innovation Release of EDB Postgres AI. See also:

Hybrid Manager dual release strategy
Documentation for the current Long-term support release

Overview

Role focus: Site reliability engineer (SRE) / Infrastructure Engineer

Prerequisites

Phase 1: Planning your architecture (Completed)
Phase 2: Gathering your system requirements (Completed)
Phase 3: Deploying your Kubernetes Cluster (Running and validated)
Phase 4: Preparing your environment (Completed and validated)

Outcomes

A fully deployed Hybrid Manager (HM) platform, accessible via the web portal.

Note

Deployment responsibility: Installation of Hybrid Manager (HM) is optimally executed by the customer's SRE team, and the customer owns its life cycle operation. If you have a Sovereign System, the EDB CX team executes the HM install. Professional Services and Sales Engineering can also be engaged for assistance, and Support has knowledge base articles available.

Next phase: Phase 6: Exploring post-installation options

Choose your installation method

With your environment prepared and your configuration validated, you are ready to deploy HM.

This phase involves applying your configuration artifact to your Kubernetes cluster and monitoring the deployment.

There are two methods for installing Hybrid Manager. Both result in the same deployed platform:

Method	Configuration	Status
Operator (Recommended)	Uses `HybridControlPlane` Custom Resource with `edb-hcp-operator` helm chart	Active - Recommended
Bootstrap (Deprecated)	Uses `values.yaml` with `edbpgai-bootstrap` helm chart	Deprecated - Will be removed in future release

Warning

The Bootstrap installation method is to be deprecated in an upcoming release. New installations should use the Operator installation method to ensure long-term support and access to the latest features.

Existing Bootstrap users: If you want to migrate to the Operator method, see the Migration guide for step-by-step instructions.

Select your installation method using the tabs below:

Operator (Recommended)
Bootstrap (Deprecated)

Important

The operator method is the recommended installation method for Hybrid Manager. It provides better version flexibility, Kubernetes-native resource management, and GitOps support.

This installation method uses the EDB Postgres AI Operator helm chart and a HybridControlPlane Custom Resource instead of the bootstrap helm chart with values.yaml.

Warning

If you have an existing Bootstrap installation and want to migrate to the Operator method, you cannot install the operator directly on top of it. You must first uninstall the bootstrap deployment to avoid Helm ownership conflicts. See the Migration guide for detailed instructions.

Understanding the HybridControlPlane Custom Resource

The HybridControlPlane is a Kubernetes Custom Resource that defines the desired state of your Hybrid Manager installation.

Key benefits of the operator approach

Kubernetes-native: Follows standard Kubernetes patterns with Custom Resources
Version flexibility: Can install different HM versions independently from the operator version
GitOps friendly: CR manifests work seamlessly with GitOps tools (ArgoCD, Flux)
Declarative: The operator reconciles the actual state to match your desired state

Verify final configuration

Before installing, prepare your HybridControlPlane manifest using the example below as a template.

Coming from Bootstrap?

If you have an existing values.yaml and want to convert it to a HybridControlPlane CR, see the configuration mapping reference and conversion script in the migration guide.

Example HybridControlPlane manifest

Here's a complete example showing the structure:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
  annotations:
    edbpgai.com/ready-for-upgrade: "true"
    biganimal.enterprisedb.io/deletion-protect: enabled
spec:
  # Basic configuration
  flavour: eks  # or aks, gke, rhos, rke
  imageRegistry: docker.enterprisedb.com/pgai-platform
  version: "v2026.3.0"

  # Source configuration
  source:
    remote: true  # Use remote bootstrap image
    # OR
    # useLocalKustomizations: true  # Use operator embedded manifests

  # Image pull secrets
  imagePullSecrets:
    - name: edb-cred
      namespace: edbpgai-bootstrap

  # Global parameters (maps from values.yaml parameters.global)
  globalParameters:
    CONTAINER_REGISTRY_URL: docker.enterprisedb.com/pgai-platform
    internal_backup_folder: "abc123xyz789"
    portal_domain_name: "portal.my-company.com"
    storage_class: "gp3"
    portal_certificate_issuer_kind: "ClusterIssuer"
    portal_certificate_issuer_name: "letsencrypt-prod"
    trust_domain: "portal.my-company.com"

  # Component-specific parameters
  componentsParameters:
    upm-beacon:
      beacon_location_id: "us-east-1"
      server_host: "beacon.my-company.com"
    transporter-rw-service:
      domain_name: "migration.my-company.com"
    transporter-dp-agent:
      rw_service_url: "https://migration.my-company.com/transporter"
    upm-istio-gateway:
      cookie_aeskey: "your-16-or-32-byte-key"
    transporter-data-operator:
      fips_enabled: "false"

  # Beacon server configuration
  beaconServer:
    logLevel: info
    hybridManagerInstallation: "my-company-prod"
    additionalTrustDomains:
      - "secondary-location.my-company.com"

  # Beacon agent configuration
  beaconAgent:
    accessKey: "your-access-key"
    logLevel: info
    providers:
      - kubernetes
    provisioning:
      imageDiscovery: true
      imagesetDiscoveryAuthenticationType: "basic"
      imagesetDiscoveryContainerRegistryURL: "docker.enterprisedb.com/pgai-platform"
      openshift: false
      operandSetVersions:
        - "1\\.1\\.[0-9]+"
      nodeSelector:
        kubernetes.io/os: linux
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: "topology.kubernetes.io/zone"
          whenUnsatisfiable: "DoNotSchedule"
          podSelector: "MatchDatabasePods"
    transparentDataEncryptionMethods:
      - passphrase
      - hashicorp_vault

  # Cluster groups (for multi-DC deployments)
  clusterGroups:
    role: standalone  # or primary/secondary
    # For multi-DC primary:
    # primary:
    #   domainName: "primary.my-company.com"
    # secondaries:
    #   - domainName: "secondary.my-company.com"

  # Installation scenarios
  scenarios:
    - core
    - migration
    - ai
    - analytics

  # Optional: Disable specific components
  # disabledComponents:
  #   - component-name

  # Optional: Resource annotations
  resourceAnnotations:
    - name: istio-ingressgateway
      kind: Service
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-scheme: internal
        service.beta.kubernetes.io/load-balancer-source-ranges: "10.0.0.0/8"

Install the EDB Postgres AI Operator

Add the EDB Helm repository

Register the EDB Helm chart repository and update your local cache. Replace <EDB_SUBSCRIPTION_TOKEN> with your EDB Repos 2.0 token.

helm repo add enterprisedb-edbpgai \
  "https://downloads.enterprisedb.com/${EDB_SUBSCRIPTION_TOKEN}/pgai-platform/helm/charts/"
helm repo update

Create namespace

Create a dedicated namespace for the operator:

kubectl create namespace edbpgai-bootstrap --dry-run=client -o yaml | kubectl apply -f -
___OUTPUT___
namespace/edbpgai-bootstrap created

Install the operator helm chart

Execute the operator deployment using Helm:

kubectl create namespace edbpgai-bootstrap --dry-run=client -o yaml | kubectl apply -f -

# Create a pull secret for the EDB cloudsmith:
kubectl create secret docker-registry edb-cred \
  --namespace edbpgai-bootstrap \
  --docker-server=docker.enterprisedb.com \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD> \
  --dry-run=client -o yaml | kubectl apply -f -

# Install the operator using Helm:
helm template \
  --namespace edbpgai-bootstrap \
  --install \
  --version <OPERATOR_VERSION> \
  --include-crds \
  edb-hcp-operator enterprisedb-edbpgai/edb-hcp-operator \
  --set "controllerManager.manager.image.repository=docker.enterprisedb.com/pgai-platform/edb-hcp-operator/manager" \
  --set "controllerManager.manager.image.tag=<OPERATOR_VERSION>" \
  --set "imagePullSecrets[0].name=edb-cred" \
  | kubectl apply -f -

If you are using an air-gapped environment, you can load the operator image into your cluster and reference it in the Helm command:

kubectl create namespace edbpgai-bootstrap --dry-run=client -o yaml | kubectl apply -f -

# Create a pull secret for your private registry:
kubectl create secret docker-registry edb-cred \
  --namespace edbpgai-bootstrap \
  --docker-server=<PRIVATE_REGISTRY_URL> \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD> \
  --dry-run=client -o yaml | kubectl apply -f -

# Load the operator image into your private registry from cloudsmith:
edbctl operator sync-to-local-registry \
  --source-registry-username=<CLOUDSMITH_REGISTRY_USERNAME> \
  --source-registry-password=<CLOUDSMITH_REGSIRT_PASSWORD> \
  --destination-registry-uri=<PRIVATE_REGISTRY_URL> \
  --destination-registry-username=<PRIVATE_REGISTRY_USERNAME> \
  --destination-registry-password=<PRIVATE_REGISTRY_PASSWORD> \
  --version <OPERATOR_VERSION>

# Install the operator using Helm, referencing your private registry:
helm template \
  --namespace edbpgai-bootstrap \
  --install \
  --version <OPERATOR_VERSION> \
  --include-crds \
  edb-hcp-operator enterprisedb-edbpgai/edb-hcp-operator \
  --set "controllerManager.manager.image.repository=<PRIVATE_REGISTRY_URL>/edb-hcp-operator/manager" \
  --set "controllerManager.manager.image.tag=<OPERATOR_VERSION>" \
  --set "imagePullSecrets[0].name=edb-cred" \
  | kubectl apply -f -

Verify operator installation

Check that the operator pod is running:

kubectl get pods -n edbpgai-bootstrap

You should see output similar to:

NAME                                READY   STATUS    RESTARTS   AGE
edb-hcp-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          30s

Create the HybridControlPlane resource

Prepare your HM manifest

Create a file named hybridmanager.yaml with your configuration. Use the example above as a template, customizing the values based on your environment preparation.

Critical fields to verify:

spec.flavour: Your Kubernetes distribution
spec.imageRegistry: Your container registry URL
spec.version: The HM version you want to install
spec.globalParameters.portal_domain_name: Your portal FQDN
spec.beaconAgent.provisioning: Your provisioning configuration

Apply the HM resource

Deploy the HybridControlPlane:

kubectl apply -f hybridmanager.yaml
___OUTPUT___
hybridcontrolplane.edbpgai.edb.com/edbpgai created

Monitor installation progress

Once the HM resource is created, the operator begins reconciling and deploying HM components.

Check HM status

Monitor the HybridControlPlane resource status:

kubectl get hybridcontrolplane edbpgai -o yaml

Look for the status section:

status:
  phase: deployed  # Can be: "", "deploying", "deployed", "failed", "deleting"
  components:
    - name: component-name
      state: success  # Can be: pending, success, failed, deleted
      version: "2026.1.0"
      timestamp: "2026-03-09T10:30:00Z"
  preflightChecks:
    phase: passed
    totalChecks: 10
    failedChecks: 0
  postflightChecks:
    phase: passed
    totalChecks: 8
    failedChecks: 0

Use kubectl to monitor

Get a quick status view:

kubectl get hcp

Expected output:

NAME      PHASE      PREFLIGHT   POSTFLIGHT
edbpgai   deployed   passed      passed

Check component deployment

View all components and their status:

kubectl get hcp edbpgai -o jsonpath='{.status.components[*].name}' | tr ' ' '\n'
___OUTPUT___
upm-beacon
upm-istio-gateway
transporter-rw-service
transporter-dp-agent
transporter-data-operator

Check for failed components:

kubectl get hcp edbpgai -o jsonpath='{.status.components[?(@.state=="failed")]}'

If no output is returned, all components deployed successfully.

Check postflight

Verify postflight status of the HM:

kubectl get postflights.edbpgai.edb.com edbpgai -o yaml
___OUTPUT___
...
status:
  checkResults:
  - description: Check whether all pods belonging to the Hybrid Manager are ready.
    name: PodsChecker
    state: Passed
  - description: Check whether all internal databases belonging to the Hybrid Manager
      are ready.
    name: DBsChecker
    state: Passed
  - description: Check whether the latest Velero Backup has been completed.
    name: VeleroChecker
    state: Passed
  - description: Check whether all nodes are ready.
    name: NodesChecker
    state: Passed
  - description: Check whether all certificates belonging to the Hybrid Manager are
      valid.
    name: CertificatesChecker
    state: Passed
  lastTransitionTime: "2026-01-27T08:50:25Z"
  phase: Healthy

What to look for:

Postflight should transition from `→Healthy`
All .status.checkResults should have a Passed state

Note

If the HM phase shows failed, check component status for error messages. If postflight checks fail, review the checkResults for specific failure reasons.

Managing the HybridControlPlane

Updating configuration

To update your HM configuration:

Edit your hybridmanager.yaml manifest

Apply the changes:

kubectl apply -f hybridmanager.yaml
___OUTPUT___
hybridcontrolplane.edbpgai.edb.com/edbpgai configured

The operator will reconcile and apply the changes

Checking operator logs

If you encounter issues, check the operator logs:

kubectl logs -n edbpgai-bootstrap deployment/edb-hcp-operator -f

Upgrading HM version

To upgrade to a new HM version, upgrade the operator version to your target HM version first, then update the spec.version field in your HCP manifest to the new version and apply the changes.

Warning

The Bootstrap method is deprecated and will be removed in a future release. For new installations, use the Operator tab above. If you have an existing Bootstrap installation and want to migrate, see the Migration guide.

Verify final configuration

Perform one final sanity check on the critical values in your values.yaml before proceeding to ensure a smooth install procedure.

These are the most common causes of deployment failures.

Open your values.yaml and confirm:

Global & image settings

containerRegistryURL: Ensure this points to the registry containing your images (e.g., docker.enterprisedb.com/pgai-platform or your private mirror).
bootstrapImageName: Must match the bootstrap image path defined in Environment Prep.
bootstrapImageTag: Must match the target version you are installing.

Domain & network parameters

parameters.global.portal_domain_name: The FQDN for the HM UI (e.g., portal.my-company.com).
parameters.transporter-rw-service.domain_name: The FQDN for the migration service.
parameters.transporter-dp-agent.rw_service_url: The full URL for the data plane agent (e.g., https://<migration-domain>/transporter).
parameters.upm-beacon.server_host: The hostname the HM-internal beacon agent will use to connect back to the control plane.
beaconAgent.provisioning.nodePortDomain: If using NodePort instead of a load balancer, ensure this domain is set.

Security & authentication

pgai.portal.authentication.staticPasswords: You must have the email, hash, username, and userID set for the initial admin user ("User-0").
parameters.upm-istio-gateway.cookie_aeskey: Ensure this 16/32-byte key is set for session encryption.
transporter-data-operator.fips_enabled: Set this to false. (FIPS support is not yet universal for all components).

Note

Ensure transporter-data-operator:fips_enabled is set to false unless you have explicitly configured a FIPS-compliant environment.

Installation scenarios

spec.scenarios: Optional. Ensure you have listed the installation scenarios you require (options are core, migration, ai, and analytics). However, if you don't have this option in your values.yaml, all scenarios are installed by default.

Install Hybrid Manager

Use the following Standard Kubernetes installation flow, unless you are deploying on RHOS and prefer to install using the EDB Postgres AI Operator from the catalog in the RHOS UI.

Standard Kubernetes

Use the Helm client to install the Hybrid Manager chart (values.yaml). We use the --install flag (or upgrade --install) to ensure the command is idempotent.

Add the EDB Helm repository

If you haven't already added the EDB Helm chart repository (for example, during the Operator installation), register it now. Replace <EDB_SUBSCRIPTION_TOKEN> with your EDB Repos 2.0 token.

helm repo add enterprisedb-edbpgai \
  "https://downloads.enterprisedb.com/${EDB_SUBSCRIPTION_TOKEN}/pgai-platform/helm/charts/"
helm repo update

Create namespace

Create a dedicated namespace for the bootstrap operator.

kubectl create namespace edbpgai-bootstrap --dry-run=client -o yaml | kubectl apply -f -

Run installation

Execute the deployment using the OCI registry path.

[REGISTRY]: Use docker.enterprisedb.com (Public) or your private registry domain.
<"VERSION">: The target version tag (e.g., 1.3.0).

helm upgrade \
  --namespace edbpgai-bootstrap \
  --install \
  --version "<helm-version>" \
  -f <path>/values.yaml \
  edbpgai-bootstrap enterprisedb-edbpgai/edbpgai-bootstrap

Use OpenShift Console

If you are deploying on RHOS, you can install the operator directly from the Catalog:

Adapt Configuration: Ensure your values.yaml is compatible with OpenShift Security Context Constraints (SCC).
Install from Catalog:
- Navigate to Operators > OperatorHub in the OpenShift Console.
- Search for EDB Postgres AI.
- Follow the on-screen wizard to deploy into the edbpgai-bootstrap project.

Monitor installation progress

Once the Helm command completes, the bootstrap operator takes over. It interprets your configuration and spins up the HM platform.

Check preflight status

After the bootstrap operator creates the HybridControlPlane resource, it automatically generates a Preflight resource to validate required secrets. This controller reflects the cluster state and will re-run every 30 seconds until all requirements pass (or fail). If the resource hasn't been created yet, the command will return "No resources found."

kubectl get preflight -o yaml

If all entries in status.secretRequirementsStatus show the Valid status, proceed with the next checks.

If any entry in status.secretRequirementsStatus shows SecretNotFound or Invalid, the operator is blocked waiting for those secrets to be fixed. See Understanding Preflight checks for details on interpreting results and resolving failures.

Check HM control plane status

Monitor the custom resource to see the high-level status of the platform:

kubectl get hybridcontrolplane edbpgai -o yaml

Expected output: You should see an object named edbpgai (or similar).
Status column: Look for Running or Ready. If it says Reconciling, wait a few moments.

Check pod health

Verify that all pods in the namespace are coming up healthy.

kubectl get pods -n edbpgai-bootstrap

What to look for:

edbpgai-operator: Must be Running.
edb-portal: The web interface.
edb-beacon: The agent handling cluster communication.
transporter: Services related to migration.

Troubleshooting

If pods are stuck in ImagePullBackOff, verify your Image Pull Secret from Phase 4. If they are Pending, verify your Storage Class availability.

Monitor deployment with postflight check

The bootstrap operator automatically creates a Postflight resource once the HybridControlPlane reaches the Deployed phase. This resource monitors your installation by verifying that pods, databases, backups, nodes, and certificates are correctly configured and valid.

Before moving on to post-installation configurations, ensure your installation is healthy:

kubectl get postflight

The output should look like this:

NAME                  PHASE     LAST CHECK
edbpgai-postflight    Healthy   2025-01-15T10:30:00Z

If the phase is Healthy continue with the next phase. If the phase is Unhealthy, obtain more detailed results with kubectl get postflight <name> -o yaml. See Monitoring with postflight checks for details on interpreting results and resolving failures.

Verify portal access

Once your installation is healthy, verify that you can access the HM console.

Open your browser and navigate to the portal domain you defined during Phase 4: Preparing your environment (e.g., https://portal.my-company.com).
Accept the certificate: If you used a self-signed certificate (or haven't trusted your custom CA yet), you may see a browser warning. Proceed past it for now.
Log In: Use the User-0 credentials you configured during environment preparation.

Success: You should see the HM console landing page.

Next phase

The platform is installed and running. You are now ready to perform the initial post-installation configuration, such as connecting your first self-managed cluster or adding team members.

Proceed to Phase 6: Exploring your post-installation options →

← Prev

Preparing your environment

↑ Up

Installing: step-by-step guide

Exploring your post-installation options

Install Hybrid Manager Innovation Release

Overview

Prerequisites

Outcomes

Note

Choose your installation method

Warning

Important

Warning

Understanding the HybridControlPlane Custom Resource

Key benefits of the operator approach

Verify final configuration

Coming from Bootstrap?

Example HybridControlPlane manifest

Install the EDB Postgres AI Operator

Add the EDB Helm repository

Create namespace

Install the operator helm chart

Verify operator installation

Create the HybridControlPlane resource

Prepare your HM manifest

Apply the HM resource

Monitor installation progress

Check HM status

Use kubectl to monitor

Check component deployment

Check postflight

Note

Managing the HybridControlPlane

Updating configuration

Checking operator logs

Upgrading HM version

Warning

Verify final configuration

Global & image settings

Domain & network parameters

Security & authentication

Note

Installation scenarios

Install Hybrid Manager

Standard Kubernetes

Add the EDB Helm repository

Create namespace

Run installation

Use OpenShift Console

Monitor installation progress

Check preflight status

Check HM control plane status

Check pod health

Troubleshooting

Monitor deployment with postflight check

Verify portal access

Next phase

← Prev

↑ Up

Next →