Configuring image discovery#

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>"
      # Set to true only for self-signed/internal CA scenarios
      imagesetDiscoveryAllowInsecureRegistry: false
    # ... your other beaconAgent settings

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.

Registry provider	Registry URL	Example
EDB Repo 2.0	docker.enterprisedb.com/pgai-platform	docker.enterprisedb.com/pgai-platform
Azure Container Registry (ACR)	<registry-name>.azurecr.io	myregistry.azurecr.io
Amazon Elastic Container Registry (ECR)	<aws-account-id>.dkr.ecr.<aws-region-id>.amazonaws.com	123456079902.dkr.ecr.us-east-1.amazonaws.com
Google Artifact Registry (GAR)	<gcp-region-id>-docker.pkg.dev	us-east1-docker.pkg.dev
GitLab Container Registry	registry.gitlab.com	registry.gitlab.com
MicroK8s Built-in Registry	localhost:32000	localhost:32000

imagesetDiscoveryContainerRegistryProvider#

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

Provider	Description
oci	Set this if your container registry provider is fully OCI compliant , including the /v2/_catalog endpoint.
gitlab	Set this if your container registry provider is GitLab Container Registry .

The recommended provider value per registry provider is as follows:

Registry provider	Provider value
EDB Repo 2.0	oci
Azure Container Registry (ACR)	oci
Amazon Elastic Container Registry (ECR)	oci
Google Artifact Registry (GAR)	oci
GitLab Container Registry	gitlab
Harbor Registry	oci
MicroK8s Built-in Registry	oci

imagesetDiscoveryAllowInsecureRegistry#

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

imagesetDiscoveryAuthenticationType#

The supported authentication types by registry provider are as follows:

Registry provider	Supported	Recommended
EDB Repo 2.0	token	token
Azure Container Registry (ACR)	token, basic	token
Amazon Elastic Container Registry (ECR)	eks_managed_identity	eks_managed_identity
Google Artifact Registry (GAR)	token, basic	basic
GitLab Container Registry	token	token
MicroK8s Built-in Registry	none	none

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 .

Note

Only legacy tokens are supported. !!!

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.

Configuring image discovery

Contents

Configuring image discovery#

Prerequisites#

Overview#

Configure image discovery#

imageDiscovery#

imagesetDiscoveryContainerRegistryURL#

imagesetDiscoveryContainerRegistryProvider#

imagesetDiscoveryAllowInsecureRegistry#

imagesetDiscoveryAuthenticationType#

image_discovery_credentials_secret_name#

Configure registry permissions#

Generic / on-Premises (RKE2/OpenShift)#

Azure Container Registry (ACR)#

AWS Elastic Container Registry (ECR)#

Additional configuration for package installation#

Google Artifact Registry (GAR)#

GitLab Container Registry#

Configure Kubernetes Secret#