#Prepare an External Platform Image Registry

For new production deployments, you can use a customer-managed external image registry as the central image source for Core, managed clusters, and Extensions. The registry must contain the complete target-version payload before you start the installer.

#Understand the Registry Roles

The following registry roles are independent:

This page configures the platform image source used by components and clusters. It does not configure an image service for application workloads.

The platform built-in Registry remains supported for existing environments and non-production evaluation. This page does not describe an online migration from the built-in Registry to an external registry.

#Registry Requirements

#Required Capabilities and Access

Before uploading the target-version payload, confirm that the registry:

• Supports the standard container image push and pull operations performed by the Core Package tools.
• Uses an address in the form <host-or-IP>[:port], for example registry.example.com:5000. Do not include http:// or https:// in the installer registry address.
• Is reachable through the required firewalls, proxies, and network routes from the installation node and every cluster node that pulls platform images.
• Provides upload credentials that can create or update the required repository paths and push images. Credentials passed to setup.sh must have pull permission. The upload and pull credentials may belong to different accounts; when you authenticate setup.sh, provide its username and password together.
• Has enough available storage for the target-version Core and Extension payload that you upload.

#Production Recommendations

For a production registry:

• Use HTTPS with a certificate that is valid for the registry address. Ensure that the installation node and every cluster node that pulls platform images trust the issuing CA.
• Use a stable DNS name that resolves from the installation node and all cluster nodes.
• Plan capacity for every required CPU architecture and for the versions retained for upgrade, rollback, and node recovery.
• Provide availability, monitoring, backup, and recovery appropriate to your environment. Registry availability is required when new Pods start, nodes are replaced, clusters are created or upgraded, and Extensions are installed or upgraded.
• Configure retention so it does not delete manifests or digests still referenced by installed platform versions, clusters, or Extensions.

#Prepare the Target-Version Payload

Use the Core Package that exactly matches the Distribution Version and CPU architecture that you will install. Do not reuse a payload from another version or architecture.

1. Complete Download, extract the Core Package, and change to its installer/ directory.

2. Copy the required Aligned Extension packages into plugins/ as described in Installing. The all upload mode processes the packages currently present in this directory.

3. Set the registry address and upload credentials in the current shell. Read the password without writing it into shell history:

   export REGISTRY_ADDRESS="registry.example.com"
   export REGISTRY_USERNAME="<registry-username>"
   read -rsp "Registry password: " REGISTRY_PASSWORD
   export REGISTRY_PASSWORD
   printf '\n'

   For a registry that allows anonymous push, set both REGISTRY_USERNAME and REGISTRY_PASSWORD to empty values.

4. From the extracted installer/ directory, run both upload modes. You can run the commands in either order, but both must finish successfully:

   bash res/upload.sh all \
     "$REGISTRY_ADDRESS" "$REGISTRY_USERNAME" "$REGISTRY_PASSWORD"
   
   bash res/upload.sh necessary \
     "$REGISTRY_ADDRESS" "$REGISTRY_USERNAME" "$REGISTRY_PASSWORD"

   The modes overlap, but neither replaces the other:

   • all uploads the product image, the cluster version operator image, and every *.tgz package currently in plugins/. It does not upload the installer artifact.
   • necessary uploads the product image, the cluster version operator image, the installer artifact, and the bootstrap plugins required to create the global cluster. It does not upload every package in plugins/.

5. In the registry administration interface or API, confirm that the newly uploaded repositories and manifests are present and are not immediately eligible for cleanup.

#Start the Installer

Start the installer from the same extracted installer/ directory. The following example reuses the upload credentials. If your registry uses a separate pull account, replace REGISTRY_USERNAME and REGISTRY_PASSWORD with credentials that have pull permission before running setup.sh.

For an authenticated registry, provide the username and password together:

bash setup.sh \
  --registry "$REGISTRY_ADDRESS" \
  --username "$REGISTRY_USERNAME" \
  --password "$REGISTRY_PASSWORD"

For a registry that permits anonymous pull, omit both --username and --password:

bash setup.sh --registry "$REGISTRY_ADDRESS"

Add other required installer options to the same command, such as --ip-family ipv6 for an IPv6 single-stack global cluster. Continue with Installing and keep Image Repository set to External with the same address and pull credentials used for setup.sh.

After setup.sh no longer needs the shell variable, remove the password from the current shell:

unset REGISTRY_PASSWORD

#Validate the External Registry Configuration

After installation completes, run the following checks from an administrative machine with access to the global cluster.

Confirm that ProductBase records the expected address and marks the registry as external:

kubectl get productbase base \
  -o jsonpath='{.spec.registry.address}{"\t"}{.spec.registry.external}{"\n"}'

The output must contain the configured address followed by true.

For an authenticated registry, confirm that the pull Secret exists without printing its contents:

kubectl -n cpaas-system get secret global-registry-auth

Confirm that the global cluster records the same registry address. Check only whether the password annotation exists; do not print its value:

kubectl get cluster global \
  -o jsonpath='{.metadata.annotations.cpaas\.io/registry-address}{"\n"}'

kubectl get cluster global -o json \
  | jq -e '.metadata.annotations | has("cpaas.io/registry-password")'

Confirm that every discovered artifact is ready. No output is expected from this command:

kubectl get productbase base -o json | jq -r '
  .status.artifacts[] as $artifact
  | $artifact.channels[]
  | select(.artifactStatus != "Ready")
  | [$artifact.name, .channel, .tag, .artifactStatus]
  | @tsv'

Confirm that the Extension catalog was created and that running Pods are not blocked by image pulls:

kubectl get moduleplugins

kubectl get pods --all-namespaces \
  | awk '$4 ~ /ImagePullBackOff|ErrImagePull/'

The Pod command must produce no output. Complete the remaining installation checks in Validation.

#Prepare the Registry Before an Upgrade

An environment installed with an external registry keeps using that registry during upgrades. Before every upgrade:

1. Download and extract the Core Package for the exact target Distribution Version and architecture.
2. Prepare the required target-version Aligned packages as described in Pre-Upgrade Preparation.
3. From the target Core Package's installer/ directory, run both res/upload.sh all and res/upload.sh necessary against the external registry, using the commands on this page.
4. Use violet push to publish the other Aligned and Agnostic Extension packages required for the upgrade. See Upload Packages.
5. Repeat the artifact, ModulePlugin, registry reachability, and image-pull checks before opening the maintenance window.

#Troubleshooting