Install Hybrid Manager Innovation 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.

Next phase: Phase 6: Exploring post-installation options

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

This phase involves applying the Helm chart (values.yaml) to your cluster and monitoring the operator as it bootstraps the platform services.

Verify final configuration

Before running the install command, perform one final sanity check on the critical values in your values.yaml.

These are the most common causes of deployment failures.

Open your values.yaml and confirm:

Global & image settings

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

Domain & network parameters

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

Security & authentication

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

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.

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 <"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:

1. Adapt Configuration: Ensure your values.yaml is compatible with OpenShift Security Context Constraints (SCC).
2. 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.

Verify HM console access

Once the pods are running, verify that you can access the user interface.

1. Open your browser and navigate to the domain defined in portal_domain_name (e.g., https://portal.my-pgai.com).
2. 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.
3. Log In: Use the User-0 credentials you defined in values.yaml (under staticPasswords).

Success: You should see the landing page of the HM console.

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.

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 →