Add and Manage External Registries

This topic describes how to add credentials for an external private registry using the Replicated Vendor Portal or Replicated CLI. Adding an external registry allows you to grant proxy access to private images using the Replicated proxy registry. For more information, see About the Replicated Proxy Registry.

For information about adding a registry with the Vendor API v3, see Create an external registry with the specified parameters in the Vendor API v3 documentation.

Supported Registries

Replicated recommends that application vendors use one the following external private registries:

• Amazon Elastic Container Registry (ECR)
• DockerHub
• GitHub Container Registry
• Google Artifact Registry
• Google Container Registry (Deprecated)
• Sonatype Nexus
• Quay.io

These registries have been tested for compatibility with KOTS.

You can also configure access to most other external registries if the registry conforms to the Open Container Initiative (OCI) standard.

Add Credentials for an External Registry

All applications in your team have access to the external registry that you add. This means that you can use the images in the external registry across multiple apps in the same team.

Using the Vendor Portal

To add an external registry using the Vendor Portal:

1. Log in to the Vendor Portal and go to the Images page.

2. Click Add External Registry.

3. In the Provider drop-down, select your registry provider.

4. For Registry Name, optionally add a unique name for the registry. This can be useful if you intend to add multiple registries or duplicate any of your registries.

5. Complete the fields in the dialog, depending on the provider that you chose:

   note

   Replicated stores your credentials encrypted and securely. Your credentials and the encryption key do not leave Replicated servers.

   • Amazon ECR

     Field	Instructions
     Hostname	Enter the host name for the registry, such as 123456689.dkr.ecr.us-east-1.amazonaws.com
     Access Key ID	Enter the Access Key ID for a Service Account User that has pull access to the registry. See Setting up the Service Account User.
     Secret Access Key	Enter the Secret Access Key for the Service Account User.

   • DockerHub

     Field	Instructions
     Hostname	Enter the host name for the registry, such as index.docker.io.
     Auth Type	Select the authentication type for a DockerHub account that has pull access to the registry.
     Username	Enter the host name for the account.
     Password or Token	Enter the password or token for the account, depending on the authentication type you selected.

   • GitHub Container Registry

     Field	Instructions
     Hostname	Enter the host name for the registry.
     Username	Enter the username for an account that has pull access to the registry.
     GitHub Token	Enter the token for the account.

   • Google Artifact Registry

     Field	Instructions
     Hostname	Enter the host name for the registry, such as us-east1-docker.pkg.dev
     Auth Type	Select the authentication type for a Google Cloud Platform account that has pull access to the registry.
     Service Account JSON Key or Token	Enter the JSON Key from Google Cloud Platform assigned with the Artifact Registry Reader role, or token for the account, depending on the authentication type you selected. For more information about creating a Service Account, see Access Control with IAM in the Google Cloud documentation.

   • Google Container Registry

     important

     Google Container Registry is deprecated. For more information, see Container Registry deprecation in the Google documentation.

     Field	Instructions
     Hostname	Enter the host name for the registry, such as gcr.io.
     Service Account JSON Key	Enter the JSON Key for a Service Account in Google Cloud Platform that is assigned the Storage Object Viewer role. For more information about creating a Service Account, see Access Control with IAM in the Google Cloud documentation.

   • Quay.io

     Field	Instructions
     Hostname	Enter the host name for the registry, such as quay.io.
     Username and Password	Enter the username and password for an account that has pull access to the registry.

   • Sonatype Nexus

     Field	Instructions
     Hostname	Enter the host name for the registry, such as nexus.example.net.
     Username and Password	Enter the username and password for an account that has pull access to the registry.

   • Other

     Field	Instructions
     Hostname	Enter the host name for the registry, such as example.registry.com.
     Username and Password	Enter the username and password for an account that has pull access to the registry.

6. For App Access, select one of these options:

   • All Apps: Make the registry available to all applications in your Vendor Portal team. This means that all customers have pull-through access to the images in this registry with their valid license.
   • Specific apps: Make this registry available only to the applications that you specify. When the registry is scoped to specific applications, only customers with a valid license for the specified applications have pull-through access to the images in the registry.

7. Click Test and provide your image name and tag (for example, api:v1.0.1 or my-app/api:v1.01.). Click Test to confirm that the Vendor Portal can access the image.

   note

   This tests credential validity only. Replicated strongly recommends that you still test your application end-to-end in a development environment.

8. Click Save.

Using the CLI

To configure access to private images in an external registry using the Replicated CLI:

1. Install and configure the Replicated CLI. See Install the Replicated CLI.

2. Run the registry add command for your external private registry. For more information about the registry add command, see registry add in Replicated CLI.

   For example, to add a DockerHub registry:

   replicated registry add dockerhub --username USERNAME \
     --password PASSWORD

   Where:

   • USERNAME is the username for DockerHub credentials with access to the registry.
   • PASSWORD is the password for DockerHub credentials with access to the registry.
   note

   To prevent the password from being saved in your shell history, Replicated recommends that you use the --password-stdin flag and entering the password when prompted.

Test External Registry Credentials

Replicated recommends that you test external registry credentials to ensure that the saved credentials on Replicated servers can pull the specified image.

To validate that the configured registry can pull specific images:

replicated registry test HOSTNAME \
    --image IMAGE_NAME

Where:

• HOSTNAME is the name of the host, such as index.docker.io.
• IMAGE_NAME is the name of the target image in the registry.

For example:

replicated registry test index.docker.io --image my-company/my-image:v1.2.3

Scope a Registry to Specific Applications

You can scope each external registry to one or more applications in your Vendor Portal team.

When the registry is scoped to specific applications, only customers with a valid license for the specified applications have pull-through access to the images in the registry. Additionally, when you add new applications to your team, those applications do not automatically get access to the registry.

To scope a registry to specific applications:

1. In the Vendor Portal, go to Images and click Edit next to the target registry.

2. For App Access, select one of these options:

   • All Apps: Make the registry available to all applications in your Vendor Portal team. This means that all customers have pull-through access to the images in this registry with their valid license.
   • Specific apps: Make this registry available only to the applications that you specify.

3. Click Save.

Duplicate a Registry

You can duplicate an existing registry. This can be useful when you want to add an external registry with the same credentials, but make the registry available to a different application in your Vendor Portal team.

To duplicate an existing external registry:

1. In the Vendor Portal, go to Images and click Edit next to the registry that you want to duplicate.

2. Click Duplicate.

   The fields are automatically populated with the credentials and provider from the duplicated registry.

3. For Registry Name, provide a name for the registry.

4. For App access, specify the application or applications that have access to the images in this registry.

5. Click Save.