Skip to main content

Using the Replicated Registry for KOTS Installations

This topic describes how to push images to the Replicated private registry.

Overview​

For applications installed with KOTS, you can host private images on the Replicated registry. Hosting your images on the Replicated registry is useful if you do not already have your images in an existing private registry. It is also useful for testing purposes.

Images pushed to the Replicated registry are displayed on the Images page in the Vendor Portal:

Replicated Private Registry section of the vendor portal Images page

View a larger version of this image

For information about security for the Replicated registry, see Replicated Registry Security.

Limitations​

The Replicated registry has the following limitations:

  • You cannot delete images from the Replicated registry. As a workaround, you can push a new, empty image to the registry using the same tags as the target image. Replicated does not recommend removing tags from the registry because it could break older releases of your application.

  • When using Docker Build to build and push images to the Replicated registry, provenance attestations are not supported. To avoid a 400 error, include the --provenance=false flag to disable all provenance attestations. For more information, see docker buildx build and Provenance Attestations in the Docker documentation.

Known Issue​

There is a known issue with the Replicated registry that can cause a timeout error when attempting to push images with layers close to 2GB. This results in an error message similar to the following: received unexpected HTTP status: 524. If you see a 524 error, build your image with smaller image layers and then push the image again. If you continue seeing a 524 error, reduce the size of the image layers again.

Push Images to the Replicated Registry​

This procedure describes how to tag and push images to the Replicated registry. For more information about building, tagging, and pushing Docker images, see the Docker CLI documentation.

To push images to the Replicated registry:

  1. Do one of the following to connect with the registry.replicated.com container registry:

    • (Recommended) Log in with a user token: Use docker login registry.replicated.com with your Vendor Portal email as the username and a Vendor Portal user token as the password. For more information, see User API Tokens in Generating API Tokens.

    • Log in with a service account token: Use docker login registry.replicated.com with a Replicated Vendor Portal service account as the password. If you have an existing team token, you can use that instead. You can use any string as the username. For more information, see Service Accounts in Generating API Tokens.

      note

      Team API tokens are deprecated and cannot be generated. If you are already using team API tokens, Replicated recommends that you migrate to Service Accounts or User API tokens instead because these options provide better granular control over token access.

    • Log in with your credentials: Use docker login registry.replicated.com with your Vendor Portal email and password as the credentials.

  2. Tag your private image with the Replicated registry hostname in the standard Docker format:

    docker tag IMAGE_NAME registry.replicated.com/APPLICATION_SLUG/TARGET_IMAGE_NAME:TAG

    Where:

    • IMAGE_NAME is the name of the existing private image for your application.
    • APPLICATION_SLUG is the unique slug for the application. You can find the application slug on the Application Settings page in the Vendor Portal. For more information, see Get the Application Slug in Managing Applications.
    • TARGET_IMAGE_NAME is a name for the image. Replicated recommends that the TARGET_IMAGE_NAME is the same as the IMAGE_NAME.
    • TAG is a tag for the image.

    For example:

    docker tag worker registry.replicated.com/myapp/worker:1.0.1

  3. Push your private image to the Replicated registry using the following format:

    docker push registry.replicated.com/APPLICATION_SLUG/TARGET_IMAGE_NAME:TAG

    Where:

    • APPLICATION_SLUG is the unique slug for the application.
    • TARGET_IMAGE_NAME is a name for the image. Use the same name that you used when tagging the image in the previous step.
    • TAG is a tag for the image. Use the same tag that you used when tagging the image in the previous step.

    For example:

    docker push registry.replicated.com/myapp/worker:1.0.1

  4. In the Vendor Portal, go to Images and scroll down to the Replicated Private Registry section to confirm that the image was pushed.