Skip to main content

Push images to the Replicated registry

important

Pushing images to the Replicated registry is not available to new vendors. If your team already pushes images to the Replicated registry, you can continue to push and pull them. There is no end date for push access, and Replicated will give advance notice before this changes.

Replicated recommends that all software vendors use the Replicated proxy registry instead of the Replicated registry. The proxy registry provides a globally-distributed and highly-performant method to grant pull-through access to application images stored in your own external registry. For more information, see About the Replicated proxy registry.

If you already host any Docker images on the Replicated registry, Replicated recommends that you move your images to an external registry and use the Replicated proxy registry. For more information, see Migrate from the Replicated registry to the proxy registry.

This topic describes the Replicated registry. The information in this topic applies only to installations managed with Replicated KOTS.

Overview​

The Replicated registry (registry.replicated.com) allows vendors to host private container images for KOTS-managed applications.

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

Limit image access to specific applications​

By default, All apps allows customers with a valid license for any application in your Vendor Portal team to pull an application's images from the Replicated registry. You can limit access to customers of specific applications on the same team.

To limit access:

  1. In the Vendor Portal, select the application whose images you want to protect and go to Image Registries.
  2. On the Replicated Private Registry card, click Edit. This requires the kots/app/<app-id>/update permission.
  3. Under App Access, select Specific apps and select the applications whose customers can pull these images. The current application is always selected and cannot be removed: its own customers always have access.
  4. Click Save changes.

The card displays the selected applications. To restore team-wide customer access, select All apps and save. Newly added applications have access only when All apps is selected or you explicitly add them to the list.

The setting applies to customer image and Helm chart pulls authenticated using a license ID or an Enterprise Portal service account token. It covers both direct pulls from registry.replicated.com and pulls through proxy.replicated.com/registry. Vendor pushes and pulls are unchanged.

Changes apply when a customer next authenticates to the registry. Customers who already have a registry token can continue to pull until that token expires.

Blocked customers receive a 403 Forbidden error with the message Customers of this app are not allowed to pull images from app "<slug>".

Limitations​

The Replicated registry has the following limitations:

  • 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.

  • You might encounter a timeout error when pushing images with layers close to or exceeding 2GB in size, such as: "received unexpected HTTP status: 524." To work around this, reduce the size of the image layers and push the image again. If the 524 error persists, continue decreasing the layer sizes until the push is successful.

  • The ability to push images to the Replicated registry is available only for KOTS-managed installations. Pushing images to the Replicated registry is not supported for Helm installations.

Push images​

View push instructions for existing Replicated registry users

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.

Delete images from the Replicated registry​

You can delete images from the Replicated registry on the Image Registries page in the Vendor Portal. For API details, including examples, see the Delete App Images API documentation.

You can still pull images by digest until you delete all tags for the image across all applications.

On this page