Connecting to an Image Registry

This topic describes how to connect to an external private registry using the Replicated vendor portal or the replicated CLI.

For information about how Replicated KOTS processes images in external private registries, see About Using an External Registry.

For information about using the Replicated private registry, see Push Images to the Replicated Private Registry.

About Using External Private Registries

When packaging an application with Replicated KOTS, you can include private images for the application without distributing registry credentials to your customer.

The customer license file can grant revokable image pull access to private images, whether the images are stored in the Replicated private registry or a supported external registry.

If you use the Replicated private registry or proxy service, you can configure custom domains to alias registry.replicated.com and proxy.replicated.com, to remove the Replicated domains from a customer security review and reduce exposure. This feature is configured at the Team level. For more information about custom domains, see Using Custom Domains.

Supported Registries

Replicated recommends that application vendors use one the following external private registries, which have been tested for compatibility with KOTS:

• Amazon Elastic Container Registry (ECR)
• DockerHub
• GitHub Container Registry
• Google Container Registry
• Quay.io

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

Configure Access to an External Registry

You can provide the credentials for an external registry in the vendor portal to grant KOTS proxy access to the private application images in the registry.

All applications in your vendor portal 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 Team.

Using the Vendor Portal

To configure access to your private images in 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 private registry provider.

4. 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
     Endpoint	Enter the host name for the registry.
     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
     Endpoint	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
     Endpoint	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 Container Registry

     Field	Instructions
     Endpoint	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
     Endpoint	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.

   • Other

     Field	Instructions
     Endpoint	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.

5. For Image name & tag, enter the image name and image tag and click Test to confirm that the vendor portal can access the image. For example, api:v1.0.1 or my-app/api:v1.01.

6. Click Link registry.

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 Installing 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

Related Topic

Tutorial: Using ECR for Private Images