Preparing your environment 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 (Completed & Running)

Outcomes

A Kubernetes cluster configured with necessary secrets (TLS, Auth, Storage, other necessary secrets)
Any chosen advanced features configured (IDP, multi-location, KMS for TDE)
A finalized and validated values.yaml configuration file ready for Hybrid Manager (HM) installation

Note

EDB Support Context: Final preparation for Hybrid Manager is primarily the customer's responsibility (except for Sovereign Systems), as is the cluster's lifecycle operation. Professional Services can be engaged via a Statement of Work (SoW), and Support can offer assistance through knowledge base articles.

Next phase: Phase 5: Install Hybrid Manager

Phase 4 guide

Now that your Kubernetes cluster is running, you must prepare it for the HM platform.

This involves establishing administrative access through a remote management workstation, staging required artifacts and secrets into the cluster, and translating your architectural decisions into the final configuration file.

Creating secrets

Create image pull secret

Use edbctl to create the ImagePullSecret. It will give your Kubernetes cluster access to the EDB registry to pull images required for the installation.

edbctl image-pull-secret create

For more CLI options, see edbctl image-pull-secret.

Create component secrets

Use edbctl to create secrets required by all HM components (core, ai, migration, analytics).

edbctl setup create-install-secrets

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

Create object storage secret

To implement the object storage requirement, you must create a secret named edb-object-storage in the default namespace.

Select the configuration matching your provider:

AWS IAM (EKS/ROSA)

apiVersion: v1
kind: Secret
metadata:
  name: edb-object-storage # the name cannot be changed
  namespace: default # the namespace cannot be changed
stringData:
  auth_type: workloadIdentity
  aws_region: <AWS_BUCKET_REGION>
  aws_role_arn: <PRIMARY_IDENTITY_ROLE_ARN>
  bucket_name: <AWS_BUCKET_NAME>
  secondary_role_arn: <SECONDARY_IDENTITY_ROLE_ARN>
  secondary_role_external_id: <SECONDARY_IDENTITY_EXTERNAL_ID>

AWS / Other K8s (Static Credentials)

apiVersion: v1
kind: Secret
metadata:
  name: edb-object-storage
  namespace: default
stringData:
  auth_type: credentials
  aws_region: <AWS_BUCKET_REGION>
  bucket_name: <AWS_BUCKET_NAME>
  aws_access_key_id: <AWS_ACCESS_KEY_ID>
  aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
  secondary_role_arn: <SECONDARY_IDENTITY_ROLE_ARN>
  secondary_role_external_id: <SECONDARY_IDENTITY_EXTERNAL_ID>

Azure Blob Storage

apiVersion: v1
kind: Secret
metadata:
  name: edb-object-storage
  namespace: default
stringData:
  provider: azure
  subscription_id: <AZURE_SUBSCRIPTION_ID>
  resource_group_name: <AZURE_RESOURCE_GROUP>
  storage_account_name: <AZURE_STORAGE_ACCOUNT>
  storage_account_container_name: <AZURE_STORAGE_CONTAINER>
  storage_account_key: <AZURE_STORAGE_KEY>
  region: <AZURE_REGION>
  client_id: <AZURE_CLIENT_ID>
  client_secret: <AZURE_CLIENT_SECRET>
  tenant_id: <AZURE_TENANT_ID>

GCP Object Storage

apiVersion: v1
kind: Secret
metadata:
  name: edb-object-storage
  namespace: default
stringData:
  provider: gcp
  location_id: <GCP_BUCKET_REGION>
  project_id: <GCP_PROJECT_ID>
  bucket_name: <GCP_BUCKET_NAME>
  credentials_json_base64: <GCP_CREDENTIAL_BASE64>

Other S3 Compatible Storage

apiVersion: v1
kind: Secret
metadata:
  name: edb-object-storage
  namespace: default
stringData:
    auth_type: credentials
    # Optional: Base64 CA bundle if not using a well-known CA
    aws_ca_bundle_base64: <CA_BUNDLE_BASE64>
    aws_endpoint_url_s3: <S3_ENDPOINT_URL>
    aws_access_key_id: <AWS_ACCESS_KEY_ID>
    aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
    bucket_name: <S3_BUCKET_NAME>
    aws_region: <S3_REGION>
    # Set to true if server-side encryption is disabled on the bucket
    server_side_encryption_disabled: <true|false>
    # often needed for on-premise storage, added in 2025.12
    aws_request_checksum_calculation: when_required
    aws_response_checksum_validation: when_required

Implementing TLS

You must implement the TLS strategy chosen during the Gathering your system requirements phase, some of which require secrets to be created.

Implementing TLS certificates describes several implementation options.

Configuring advanced features

Configuring multi-location architecture

Deploying HM across multiple locations (multi-DC) requires significant preparation to ensure the primary and secondary clusters can communicate securely.

You must establish trust domains, sync storage secrets, and configure the HM-internal beacon agent to register the secondary location.

Preparation checklist:

Network: Ensure connectivity on ports 8444 (SPIRE) and 9445 (Beacon) between clusters.
Storage: Synchronize the edb-object-storage secret across all clusters.
Identity: Configure SPIRE federation to allow cross-cluster trust.
Configuration: Define unique beacon_location_id values and trust domains in values.yaml.

SOP: Configuring multiple data centers for Hybrid Manager
- Guidance: Detailed steps for setting up SPIRE federation and cross-DC wiring.

Implementing KMS for TDE

If you require encryption at rest for your databases (TDE), you should enable the Key Management Service (KMS) provider and create your keys now.

SOP: Adding KMS support

Depending on the KMS you are using, refer to the guides below to identify the necessary values.yaml flags and create the keys.

Implement the configuration strategies decided upon during the Phase 1: Planning your architecture and Gathering your system requirements phases.

Completing environmental preparation

Name your backup folder

This is a unique folder used to store the HM backups for disaster recovery. Assign a unique folder name (e.g., using a UUID generator) and provide it in your values.yaml under parameters.global.internal_backup_folder. The string must be 12 characters comprised of letters and numbers i.e. internal_backup_folder: "a7462dbc7106".

Add required component configuration

The following component-specific parameters should be added to your values.yaml under parameters:

parameters:
  edb-migration-portal:
    enable_pdb: "false"
  upm-api-pnxt-metric:
    log_level: "info"
    tsdb_host: "thanos-query.monitoring.svc.cluster.local"
    tsdb_port: "9090"
  upm-api-pnxt-pd:
    log_level: "info"
  upm-beaco-ff-base:
    aes_key_rotation_interval: 2160h
    usage_generator_interval: 24h
  upm-beaco-usages:
    usage_generator_interval: "24h"
  upm-beacon:
    beacon_location_id: <your-location-id>
    server_host: <your-beacon-server-host>
  upm-istio-gateway:
    enable_server_session: "true"
    openshift_console_domain_name: <your-openshift-console-domain>
  upm-prometheus:
    memory: "4Gi"
  upm-thanos:
    memcached_cpu: "500m"
    memcached_memory: "2Gi"
    query_frontend_cpu: "200m"
    query_frontend_memory: "120Mi"
  upm-trust-manager:
    cert_manager_namespace: "cert-manager"

Finalizing the cluster configuration (`values.yaml`)

You now construct (or update if you have previously created) the final values.yaml file.

This file references your system requirements (Storage, Network, etc), environment settings, and the feature configurations you just prepared.

Below is a template configuration with all of the keys you should have determined for a successful HM install:

system: <Kubernetes>
bootstrapImageName: <Container Registry Domain>/pgai-platform/edbpgai-bootstrap/bootstrap-<Kubernetes>
bootstrapImageTag: <image-tag-version>
containerRegistryURL: "<Container Registry Domain>/pgai-platform"
scenarios: "core,migration,ai,analytics"
parameters:
  global:
    internal_backup_folder: "<twelveCharacterString>"
    portal_domain_name: <Portal Domain>
    storage_class: <Block Storage>
    portal_certificate_issuer_kind: <ClusterIssuer>
    portal_certificate_issuer_name: <my-issuer>
    trust_domain: <Portal Domain>
  upm-beacon:
    beacon_location_id: "<Location>"
    server_host: <Beacon Server Domain>
beaconAgent:
  provisioning:
    openshift: <true | false>
    imagesetDiscoveryAuthenticationType: <token | basic | eks_managed_identity>
    imagesetDiscoveryContainerRegistryURL: "<Container Registry Domain>/pgai-platform"
  transparentDataEncryptionMethods:
    - passphrase
    - hashicorp_vault
    # Additional options: aws_kms, azure_kms, gcp_kms
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

Validating the configuration file and runtime

Before proceeding to deployment, validate both your configuration file and the runtime environment.

Validate configuration syntax

Ensure your values.yaml is valid and can be processed by Helm.

Replace <your-registry-url> with the registry you defined in values.yaml (e.g., docker.enterprisedb.com or your internal Harbor/Artifactory).

helm template edb-pgai oci://<your-registry-url>/pgai-platform/edb-pgai \
  --values values.yaml \
  --version <target-helm-version> > /dev/null

If this command completes without error, your YAML syntax is valid.

Validate secrets

Ensure the secrets referenced in your configuration exist in the cluster. To list the image pull secrets:

edbctl image-pull-secret list

To list the component secrets:

edbctl setup list-install-secrets

Validate LoadBalancer

Verify that your cluster can provision an external load balancer service (required for ingress).

kubectl create service loadbalancer test-lb --tcp=80:80
kubectl get svc test-lb

Success: If the load balancer controller is functioning, the test-lb service will be assigned an external IP or hostname.
Cleanup: kubectl delete svc test-lb

Run diagnostic tooling

For a comprehensive check of the cluster's readiness, use the diagnostic plugin.

SOP: Use kubectl-edb-diagnostic.

Next phase

Now that your management workstation is ready, images are synced, secrets are created, advanced features are configured, values.yaml is finalized, and then that YAML is validated, you are ready to install HM.

Proceed to Phase 5: Installing Hybrid Manager →

← Prev

Deploying your Kubernetes cluster

↑ Up

Installing and configuring Hybrid Manager

Install Hybrid Manager