Skip to main content
Version: latest

Deploy Cluster with a Private External Registry

Palette Edge provides support for downloading images from authenticated external registries. You can instruct the Palette agent to download images from an authenticated external registry by specifying the address and the credentials for the registry in the user data used to build your Edge Installer ISO.

Once you specify an external registry, images for all elements of the cluster are expected to be in the external registry. This includes the provider images, images for the network and storage layer, and images for all application layers. All images specified in the cluster profile will have their registry URL prefixed by the registry URL of the external image registry. For example, if your OS pack specified that the provider images be downloaded from, but in your user data, you have specified an external registry The Palette agent will automatically download the image using the tag instead of looking for the image in the original registry.

The provider image also includes core Kubernetes images such as images for api-server, etcd, and kube-controller-manager, which will be loaded directly from the provider image to containerd without fetching them from another registry.


You can use a private external registry together with a local Harbor image registry by adding the Harbor Edge-Native Config pack to your cluster profile. All images for add-on layers of the cluster will be stored in the local Harbor registry after the initial download, which allows you to reduce the bandwidth use and protect against outages. For more information, refer to Enable Local Harbor Registry.


  • Palette Edge supports basic username/password authentication. Token authentication schemes used by services such as AWS ECR and Google Artifact Registry are not supported.


  • Specifying the external registry and providing credentials happens during the EdgeForge process. You should become familiar with EdgeForge before following this guide. Refer to Build Edge Artifacts to learn how to build Edge Installer ISO and provider images.

  • A physical or virtual Linux machine with AMD64 (also known as x86_64) processor architecture to build the Edge artifacts. You can issue the following command in the terminal to check your processor architecture.

    uname -m
  • Minimum hardware configuration of the Linux machine:

    • 4 CPU
    • 8 GB memory
    • 50 GB storage
  • Git. You can ensure git installation by issuing the git --version command.

  • Docker Engine version 18.09.x or later. You can use the docker --version command to view the existing Docker version.

    • You should have root-level or sudo privileges on your Linux machine to create privileged containers.
  • A Palette account. If you have not signed up, you can sign up for a free trial.

  • Palette registration token for pairing Edge hosts with Palette. You will need tenant admin access to Palette to generate a new registration token. For detailed instructions, refer to the Create Registration Token guide.

  • A private external registry that stores all images required by your cluster.

Deploy Cluster with a Private External Registry

  1. Check out the CanvOS GitHub repository containing the starter code.

    git clone
  2. Change to the CanvOS/ directory.

    cd CanvOS
  3. In the user data file, provide the URL and the credentials in stylus.registryCredentials. The following is an example:

    username: ubuntu
    password: *******
    insecure: true

    Refer to Installer Configuration for a description of each field.

  4. Follow the rest of the Build Edge Artifact guide and build the Installer ISO with the user data containing the registry credentials.

  5. Follow the Perform Site Install guide to perform the installation.

  6. Log in to Palette.

  7. From the left Main Menu, click on Profiles. Then select the profile you are using to deploy the cluster.

  8. Go through each layer of the profile and ensure that all images referenced in the profile are present in the external registry. If you do not want to do this manually image by image, refer to Upload Cluster Images to External Registry with Palette Edge CLI to learn how to use the Palette Edge CLI to upload all images in a cluster profile to an external registry.

  9. In the Kubernetes layer of your cluster profile, remove AlwaysPullImages from cluster.config.clusterConfiguration.apiServer.extraArgs.enable-admission-plugins.

    For example, if the original enable-admission-plugins parameter is the following.

    enable-admission-plugins: AlwaysPullImages,NamespaceLifecycle,ServiceAccount,NodeRestriction

    The resulting layer configuration should look like the following.

    enable-admission-plugins: NamespaceLifecycle,ServiceAccount,NodeRestriction
  10. Follow the Create Cluster Definition guide and deploy your cluster.


  1. Log in to Palette.

  2. From the left Main Menu, click on Clusters.

  3. Verify that the cluster you provisioned is in running status. Since your cluster profile only references images in the private external registry, you can confirm that the images were downloaded successfully.