Configuring image discovery v1.4.1 (LTS)

Related installation phase: Phase 4: Preparing the Environment

Prerequisites

• Synced images to your local container registry (Completed) - You must have a private registry populated with EDB images.

• Registry Compliance: Your registry must be OCI compliant.

• Permissions: Access to configure IAM roles (AWS/GCP) or Registry Access Control (On-Prem).

Overview

Image discovery is a background process running within the HM-internal beacon agent. It connects to your private container registry, scans for available Postgres versions (tags), and registers them in the Hybrid Manager (HM).

Image discovery ensures that when you sync new database versions to your registry, they automatically become available for your users to provision without manual intervention.

Configure image discovery

To enable this feature, you must configure the Beacon agent with your registry details.

Edit your HybridControlPlane CR to add the image discovery settings under spec.beaconAgent:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  beaconAgent:
    provisioning:
      imageDiscovery: true
      imagesetDiscoveryContainerRegistryURL: "<your-private-registry-uri>"
      # Keep false; to trust a private/internal CA, set imageset_discovery_ca_certs below
      imagesetDiscoveryAllowInsecureRegistry: false
    # ... your other beaconAgent settings
  componentsParameters:
    upm-beacon:
      # Optional: PEM-encoded CA certificate to verify a private-CA registry over HTTPS
      imageset_discovery_ca_certs: |
        -----BEGIN CERTIFICATE-----
        <your-private-CA-certificate>
        -----END CERTIFICATE-----
    # ... your other componentsParameters

imageDiscovery

This boolean option enables or disables the image discovery feature. It defaults to false.

imagesetDiscoveryContainerRegistryURL

This option specifies the URL of the container registry from which to discover PostgreSQL container images.

imagesetDiscoveryContainerRegistryProvider

This option defines the provider for the registry located at imagesetDiscoveryContainerRegistryURL. It defaults to oci.

The recommended provider value per registry provider is as follows:

imagesetDiscoveryAllowInsecureRegistry

If this option is enabled, it allows establishing a TLS connection without certificate validation. It defaults to false.

imageset_discovery_ca_certs

Use this option to have image discovery trust a container registry that is served with a certificate signed by a private or internal certificate authority (CA), without disabling certificate validation.

Set it under spec.componentsParameters.upm-beacon (not under spec.beaconAgent.provisioning). Provide the CA as an inline, PEM-encoded certificate. When this option is set and imagesetDiscoveryAllowInsecureRegistry is false, the beacon agent verifies the registry's TLS certificate against this CA in addition to the system trust store, and connects using TLS 1.2 or later.

This is the recommended way to reach a private-CA registry over HTTPS in regulated or air-gapped environments that must use HTTPS and cannot enable insecure mode.

spec:
  beaconAgent:
    provisioning:
      imagesetDiscoveryAllowInsecureRegistry: false
  componentsParameters:
    upm-beacon:
      imageset_discovery_ca_certs: |
        -----BEGIN CERTIFICATE-----
        <your-private-CA-certificate>
        -----END CERTIFICATE-----

Rotating the CA

To rotate or replace the CA, replace the imageset_discovery_ca_certs value under spec.componentsParameters.upm-beacon on the HybridControlPlane CR with the new CA certificate and apply it. You do not need to keep the old certificate alongside the new one. The change is applied automatically and no beacon agent pod restart is required:

1. The edb-hcp-operator reconciles the updated CR and refreshes the ConfigMap that holds the CA certificate.
2. Kubernetes syncs the updated certificate into the beacon agent pod's mounted volume (typically within about a minute).
3. The beacon agent re-reads the certificate file on its next discovery cycle and uses the new CA from then on.

The new CA typically takes effect within a couple of minutes. Removing the field reverts image discovery to the system trust store only, so a private-CA registry stops being trusted.

imagesetDiscoveryAuthenticationType

The supported authentication types by registry provider are as follows:

image_discovery_credentials_secret_name

This value is the name of the Kubernetes secret containing the credentials of registry for image discovery. Defaults to "edb-cred".

Configure registry permissions

The HM-internal beacon agent requires specific permissions to scan your registry.

It must be able to:

• List repositories
• List tags
• Read tag manifests

Select your platform below to configure the necessary permissions.

Generic / on-Premises (RKE2/OpenShift)

If you are using a standard OCI registry (like Harbor, Quay, or Artifactory), ensure the username/password you provided when creating your *Image Pull Secret* has read and list permissions on the target repositories.

Refer to your registry's documentation (examples: Quay.io Permissions) to configure the service account.

Azure Container Registry (ACR)

The ACR token used as a Kubernetes image pull secret must have the _repositories_pull_metadata_read scope-map.

az acr token create --name <token-name> --registry <registry-name> \
    --scope-map "_repositories_pull_metadata_read"

AWS Elastic Container Registry (ECR)

When running on EKS with ECR, EKS Managed Identity is the required authentication method.

You must create an IAM role with the AmazonEC2ContainerRegistryReadOnly policy and associate it with the Beacon's service account.

Run this script to configure the IAM Role and Pod Identity:

# Configuration Variables
EKS_CLUSTER_NAME="<eks_cluster_name>"
EKS_CLUSTER_REGION="<eks_cluster_region>"
IMAGE_DISCOVERY_IAM_ROLE_NAME="<iam_role_name>"

# 1. Create Trust Policy
cat <<EOF > ./image-discovery-trust.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
            "Effect": "Allow",
            "Principal": {
                "Service": "pods.eks.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ]
        }
    ]
}
EOF

# 2. Create Role & Attach Policy
aws iam create-role --role-name "${IMAGE_DISCOVERY_IAM_ROLE_NAME}" \
    --assume-role-policy-document file://image-discovery-trust.json

aws iam attach-role-policy --role-name "${IMAGE_DISCOVERY_IAM_ROLE_NAME}" \
    --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

# 3. Associate with EKS Service Account
IMAGE_DISCOVERY_IAM_ROLE_ARN=$(aws iam get-role --role-name ${IMAGE_DISCOVERY_IAM_ROLE_NAME} | jq -r '.Role.Arn')

aws eks create-pod-identity-association --cluster-name "${EKS_CLUSTER_NAME}" \
    --namespace upm-beacon \
    --service-account upm-beacon-agent-k8s \
    --role-arn "${IMAGE_DISCOVERY_IAM_ROLE_ARN}" \
    --region "${EKS_CLUSTER_REGION}"

Additional configuration for package installation

To allow package installation for downloading and deploying packages, you must also grant ECR access to the kapp-controller component.

The kapp-controller is responsible for pulling Helm charts and package manifests from ECR during application deployment. Without this configuration, package installations will fail with credential errors.

Add Pod Identity association for kapp-controller:

# Use the same IAM role ARN from above
aws eks create-pod-identity-association --cluster-name "${EKS_CLUSTER_NAME}" \
    --namespace kapp-controller \
    --service-account kapp-controller-sa \
    --role-arn "${IMAGE_DISCOVERY_IAM_ROLE_ARN}" \
    --region "${EKS_CLUSTER_REGION}"

Google Artifact Registry (GAR)

When running on GKE, the Service Account used by the Beacon must have permissions to list projects and read artifacts.

Required Roles:

• roles/artifactregistry.reader (to read images)
• roles/browser (specifically resourcemanager.projects.list to find repositories)

Run this script to apply the IAM bindings:

# Replace with your Project ID and Service Account Name
PROJECT_ID="<your-project-id>"
SERVICE_ACCOUNT_EMAIL="<service-account-name>@${PROJECT_ID}.iam.gserviceaccount.com"

# Grant Reader Role
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role="roles/artifactregistry.reader"

# Grant Browser Role (Required for discovery)
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role="roles/browser"

GitLab Container Registry

The Personal access token used as a Kubernetes image pull secret must have the following scopes:

• read_registry — allows read-only access to container registry images on private projects.
• read_api — allows read access to projects and container repositories.

For more details, see the GitLab Personal access token scopes.

Configure Kubernetes Secret

The final step is ensuring HM knows which Kubernetes Secret contains the registry credentials (if not using Cloud Identity).

Confirm or update the credentials secret name in your HybridControlPlane CR under spec.componentsParameters.upm-beacon:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  componentsParameters:
    upm-beacon:
      image_discovery_credentials_secret_name: "edb-cred"
    # ... your other componentsParameters

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

Verification:

After applying these changes, check the logs of the HM-internal beacon agent pod. You should see messages indicating that it is scanning the registry and discovering image tags.