Configuring image discovery Innovation Release

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 tell HM where your registry is and how to reach it.

All of the container registry settings of a HybridControlPlane live under a single spec.registry block:

• spec.registry.url and spec.registry.imagePullSecrets for pulling the HM images
• spec.registry.tls for the trust used to reach the registry
• spec.registry.discovery for image discovery itself

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

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  registry:
    # The registry the HM images are pulled from. Image discovery scans this
    # same registry unless you set spec.registry.discovery.url.
    url: "<your-private-registry-uri>"
    imagePullSecrets:
      - name: edb-cred
        namespace: edbpgai-bootstrap
    discovery:
      enabled: true
      provider: "oci"
      authenticationType: "token"
      credentialsSecretName: "edb-cred"
    tls:
      # Optional: PEM-encoded CA certificate to verify a private-CA registry over HTTPS
      caCerts: |
        -----BEGIN CERTIFICATE-----
        <your-private-CA-certificate>
        -----END CERTIFICATE-----
      # Keep false; to trust a private or internal CA, set caCerts above
      dangerousSkipTLSVerify: false

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

Deprecated registry fields

The registry fields that spec.registry replaces are deprecated. An existing manifest keeps working unchanged where the corresponding spec.registry value is unset, but applying it returns an admission warning naming the field to use instead. A future API version removes the deprecated fields. A value under spec.registry takes precedence over its older counterpart.

When you point at an in-cluster registry with spec.hmRegistryRef, the operator populates spec.registry.url, spec.registry.tls.dangerousSkipTLSVerify, and the spec.registry.discovery URL, provider, and authentication type for you.

discovery.enabled

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

discovery.url

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

It's optional. When it's unset, discovery scans the registry that pulls the HM images (spec.registry.url). In the common case where both are the same registry, you declare the URL only once. Set it only when discovery targets a different repository or host. Like spec.registry.url, it can include a repository path.

discovery.provider

This option defines the provider for the registry that discovery scans. It defaults to oci.

The recommended provider value per registry provider is as follows:

discovery.authenticationType

This option indicates the type of authentication to use when connecting to the registry during image discovery.

The supported authentication types by registry provider are as follows:

discovery.credentialsSecretName

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

tls.caCerts

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

Provide the CA as an inline, PEM-encoded certificate bundle. When this option is set and dangerousSkipTLSVerify is false, HM verifies the CA in addition to the system trust store, and the connection uses 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 can't enable insecure mode.

You supply the CA once, and both consumers that contact the registry from inside HM use it: the beacon agent scanning for image tags, and kapp-controller pulling the HM component packages. Earlier releases required the same PEM bundle in two independent fields, which risked drifting out of sync.

spec:
  registry:
    tls:
      caCerts: |
        -----BEGIN CERTIFICATE-----
        <your-private-CA-certificate>
        -----END CERTIFICATE-----
      dangerousSkipTLSVerify: false

Rotating the CA

To rotate or replace the CA, replace the spec.registry.tls.caCerts value on the HybridControlPlane CR with the new CA certificate and apply it. You don't need to keep the old certificate alongside the new one. For image discovery, 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 to the system trust store only, so a private-CA registry stops being trusted.

tls.dangerousSkipTLSVerify

Enabling this option treats the registry as fully insecure: it disables certificate validation and permits a plaintext HTTP fallback. It defaults to false.

Because both image discovery and kapp-controller image pulls read the same spec.registry.tls block, enabling this option makes both connections insecure.

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.registry.discovery:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  registry:
    discovery:
      credentialsSecretName: "edb-cred"
    # ... your other registry settings

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.