Prepare an External Platform Image Registry

A new installation of 4.5 or later requires an image registry that stores the platform images for Core, managed clusters, and Extensions. The registry must contain the complete target-version payload before you start the installer.

About the Platform Image Registry

An image registry provided by your organization, such as Harbor, is strongly recommended. If no image registry is available, you can create one with mirror-registry.

Every machine in the clusters must have access to this registry. If the registry is unreachable, tasks such as installation, upgrades, and routine operations such as workload relocation might fail. Therefore, a production image registry must be operated in a highly available manner, and its availability must at least match the production availability of your clusters.

Prerequisites

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

  • Supports the standard container image push and pull operations performed by the Core Package tools.
  • Uses an address in the form <host-or-IPv4>[:port], for example registry.example.com:5000. Do not include http:// or https:// in the installer registry address. If the registry uses IPv6, use a domain name.
  • Is reachable through the required firewalls, proxies, and network routes from the installation node and every cluster node that pulls platform images. See Image Registry in the Communication Matrix.
  • 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 every required CPU architecture and for the versions retained for upgrade, rollback, and node recovery.
  • Uses a retention policy that does not delete images still referenced by installed platform versions, clusters, or Extensions.

Prepare the Target-Version Payload

The installer does not copy missing images or packages into the registry. Complete the upload in this section before running setup.sh.

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 all packages of ACP Common Aligned Extensions into plugins/ as described in Download.

  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 the following commands to upload the target-version payload. Both commands 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"
  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

SymptomLikely causeAction
unauthorized or authentication requiredThe upload credentials are incorrect or lack push permission.Verify the account used by res/upload.sh and confirm that it can push to the required repository paths.
denied or repository creation failsThe upload account cannot create or update the required repository paths.Grant the account the required repository permissions and rerun the upload commands.
A required package is reported as not foundThe Core Package is incomplete, the wrong version or architecture was extracted, or required Extension packages were not copied into plugins/.Verify the package checksum, version, architecture, and plugins/ contents before retrying.

Next Step

After the upload succeeds and the registry contains the target payload, continue with the installation path that you selected: