Syncing images to a local private registry v1.4.3 (LTS)

Related installation phase: Phase 4: Preparing the Environment

For the full inventory of artifact types HM distributes, where each one lives, and what your registry and network need to support them, see Container registry and artifact reference.

Prerequisites

• edbctl CLI tool installed and configured.

• A valid EDB Repos 2.0 Token.

• Write access to your target local private registry (examples: AWS ECR, Google Artifact Registry, Harbor).

Hosting images internally ensures:

• Security & compliance: You control the scanning and approval of artifacts.

• Reliability: Your deployment is not dependent on external internet connectivity or third-party uptime.

• Performance: Lower latency for cluster nodes pulling images.

• Air-gapped and disconnected clusters: Gets HM's artifacts to a cluster with no route to EDB's registry, as long as edbctl can run somewhere with access to both, such as a bastion or jump host. For environments where nothing can reach EDB's registry directly, see Mirroring without edbctl.

This process uses the edbctl tool to copy artifacts from EDB Repos 2.0 to your private registry while preserving SHA256 digests.

The software stack of HM is pushed into EDB Repos 2.0 registry to provide artifacts for you to use in your local private registry: customer-managed internal registry for RHOS or Rancher RKE2 on-premises scenarios, or a self-managed registry on your cloud service provider (CSP) registry AWS Elastic Container Registry (ECR), Google Cloud Artifact Registry (GAR), or Azure Container Registry (ACR) for HM on CSP scenarios.

Before you begin, ensure you have a secure, approved private registry ready to host the container images.

You need the registry's URI, along with a username and password (or token) that has write access. Additionally, confirm the specific version of EDB Postgres AI you intend to install.

Using these credentials, the sync process copies all necessary artifacts from EDB Repos 2.0 directly into your local private registry, ensuring they are available for your Helm chart installation or upgrade.

Preserving digests

HM resolves artifacts by digest (a SHA-256 hash of the artifact's exact contents) in addition to tag. edbctl image sync-to-local-registry preserves digests automatically. If you build your own mirroring pipeline instead (see Mirroring without edbctl), preserving digests is something you have to ensure yourself, because several common tools don't:

• A docker pull followed by docker push unpacks and reconstructs the artifact, which can change its digest even though the content looks identical and the copy appears to succeed.
• Some proxying or caching registry configurations behave the same way: they re-serialize what passes through them rather than storing the exact bytes.

The resulting failure is easy to misdiagnose: the artifact arrives, is correctly named, and scans cleanly, but the specific digest HM asks for no longer exists, and nothing in the copy step reported an error. See Registry and artifact errors for what this failure looks like when it happens.

skopeo is a command-line tool for copying and inspecting container images and OCI artifacts between registries without needing a container daemon. To copy artifacts while preserving digests with it:

skopeo copy --preserve-digests \
  --override-os linux --override-arch amd64 \
  docker://docker.enterprisedb.com/pgai-platform/<image>:<tag> \
  docker://<your-registry>/<repository-name>/<image>:<tag>

Mirroring with edbctl

Configure sync variables

Required Information:

• Release Version: The tag of Hybrid Manager (HM) you intend to install (example:v2026.5.1).
• EDB Token: Your access token for docker.enterprisedb.com.
• Local Registry: The URI and credentials for your organization's registry.

1. Define the EDB release version

   → WrapCopy

   export EDBPGAI_RELEASE=<EDB-pgai-release-version>

2. Define EDB credentials (Source)

   → WrapCopy

   export CS_EDB_TOKEN=<your-edb-repos-token>
   export EDB_SOURCE_REGISTRY=pgai-platform

   CS_EDB_TOKEN is your EDB Repos 2.0 API token, passed as the password. EDB_SOURCE_REGISTRY isn't a personal username, it's passed as --source-registry-username, but the value is your subscription namespace (pgai-platform). See Registry credentials.

3. Define private registry credentials (Destination)

   → WrapCopy

   export LOCAL_REGISTRY_URI=<your_local_container_registry_uri>
   export LOCAL_REGISTRY_USER=<your_local_registry_user>
   export LOCAL_REGISTRY_PWD=<your_local_registry_password>

Sync platform images

Execute the following command to sync the platform images and the operator artifacts in a single step:

edbctl image sync-to-local-registry \
    --destination-registry-uri "${LOCAL_REGISTRY_URI}" \
    --version "${EDBPGAI_RELEASE}" \
    --source-registry-username "${EDB_SOURCE_REGISTRY}" \
    --source-registry-password "${CS_EDB_TOKEN}" \
    --destination-registry-username "${LOCAL_REGISTRY_USER}" \
    --destination-registry-password "${LOCAL_REGISTRY_PWD}"

The command mirrors the following artifacts to your private registry:

• Platform images — Portal, Beacon, Transporter, and other HM components.
• Operator manager image — edb-hcp-operator controller image.
• Operator bundle image — OCP-certified bundle, used to build self-hosted OperatorHub catalogs in air-gapped OpenShift clusters.
• Operator helm chart — edb-hcp-operator chart, mirrored as an OCI artifact alongside the images.

Mirroring without edbctl

edbctl image sync-to-local-registry is the supported path and the only one that doesn't require you to track every artifact class yourself. Use it wherever your environment allows it.

Some environments can't use edbctl image sync-to-local-registry, including fully air-gapped or disconnected clusters with no route from edbctl to EDB's registry. edbctl needs direct network access to both the source and destination registries and broad enough credentials to read from one and write to the other. If your organization instead requires artifacts to be submitted individually through a governed ingestion or approval process, you're effectively performing the same job edbctl automates, by hand: for each artifact class, pull it from EDB's registry with the recommended tool, carry it through whatever approval or transfer step your organization requires, then push it into your destination registry or repository using that same tool.

Avoid docker or podman as your primary mirroring tool for anything beyond a quick, single-platform test copy. Both parse and regenerate manifests on pull/push, which risks the same digest-preservation problem described in Preserving digests, and, with Docker Content Trust enabled, they reject OCI artifacts outright rather than mirroring them.

Updating your configuration

Once the sync is complete, you must configure HM to pull images from your private registry.

Edit your HybridControlPlane CR to set spec.imageRegistry to your private registry URI:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  imageRegistry: "<your_local_container_registry_uri>"
  # ... your other spec fields

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

Next steps

With your images synced and your configuration updated, you are ready to proceed with the installation.

Return to Phase 4: Preparing your Environment or Phase 5: Installing Hybrid Manager.