#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.

#Troubleshooting

#Next Step

After both upload modes succeed and the registry contains the target payload, continue with Installing.