Preparing your environment 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 (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 configuration ready for Hybrid Manager (HM) installation—either a HybridControlPlane Custom Resource manifest if using the recommended Operator method, or a values.yaml file if using the legacy "Bootstrap" method

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:

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

Creating secrets

Create image pull secret

Use edbctl to create the ImagePullSecret. Doing this gives 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 TLS strategoes require secrets to be created.

SOP: Implementing TLS certificates describes the 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:

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

• 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 create the corresponding key.

• HashiCorp Vault
• AWS Key Management Service (KMS)
• Google Cloud Key Management Service (Cloud KMS)

Completing environmental preparation

Name your backup folder

1. Create a new folder to store the HM backups for disaster recovery.
2. Assign a unique folder name (e.g., using a UUID generator) and provide it in your HM configuration under parameters.global.internal_backup_folder.
3. 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 HM configuration 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

You now construct or update the final configuration for your HM installation.

This configuration references your system requirements from Phase 2 and the environment settings and feature configurations you prepared here in Phase 4.

Choose your configuration method

There are two ways to configure your Hybrid Manager installation:

1. Operator method (HybridControlPlane CR) - Recommended - Kubernetes Custom Resource used with the edb-hcp-operator chart
2. Bootstrap method (values.yaml) - Deprecated - Helm values file used with the edbpgai-bootstrap chart

Both operator and bootstrap method use the same configuration values, just in different formats. The secrets and preparation steps are identical for both approaches.

Using the Operator method: HybridControlPlane Custom Resource (Recommended)

If you're using the recommended Operator method, create a HybridControlPlane Custom Resource.

• SOP: Install with the Operator guide for a complete HybridControlPlane manifest template and field mapping reference.

The Operator method is the recommended approach for all new installations. It provides better version management and Kubernetes-native resource handling.

Using the Bootstrap method: values.yaml template

Below is a template configuration with all of the necessary keys you have determined following the guide for a successful HM install using the Bootstrap method:

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, secrets, LoadBalancer, and cluster readiness

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

Validate configuration syntax

Validate your configuration file before proceeding.

Operator method: Use kubectl dry-run to validate your HybridControlPlane manifest:

kubectl apply --dry-run=client -f hybridmanager.yaml

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

Bootstrap method: Ensure your values.yaml 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, your HM configuration is finalized, and your configuration file is validated, you are ready to install HM.

Proceed to Phase 5: Installing Hybrid Manager →