Skip to main content

Use container images from an external registry

You can configure Anyscale to access external image registries to launch Ray clusters with images built by external workflows or tools, such as CI/CD artifacts or local Docker builds. The following is an overview of the requirements to use images from an external registry:

You can also use a similar flow to register external images to the Anyscale container image registry. See Register a custom image.

For an example workflow using a local Docker build and a public Docker Hub repository, see Tutorial: Build a custom container image.

Launch a cluster with an image from an external registry

Workspaces, jobs, and services support launching Ray clusters using images from external image registries. You specify the following options to use an image from an external registry:

OptionDescription
Image URIThe URI for the image in your external registry.
Ray versionThe version of Ray in the image.
Registry login secretThe name of the secret that contains the login credentials to your registry. See Use registry login secrets on Anyscale.

The Anyscale console has a dedicated flow for using images in external registries when creating a workspace. Select Use an image from an external registry in the Container image > Select image field to view the configuration.

See the following sections in the CLI and SDK reference for details on using external registries with Anyscale workspace, jobs, and services:

Cluster typeCLISDKConfig YAML
Workspaceanyscale workspace_v2 createanyscale.workspace.createWorkspaceConfig
Jobanyscale job submitanyscale.job.submitJobConfig
Serviceanyscale service deployanyscale.service.deployServiceConfig

Supported external image registries

The following table describes common external image registries supported on Anyscale:

Image registryDescription
Elastic Container Registry (ECR)ECR is a managed image registry on AWS. Use ECR when you're using an Anyscale cloud deployed on AWS. Configure access through your cloud IAM role. See Accessing Amazon ECR.
Artifact RegistryArtifact Registry is a managed image registry on Google Cloud. Use Artifact Registry when you're using an Anyscale cloud deployed on Google Cloud. Configure access through the Google Cloud service account used by your Anyscale cloud.
Private registriesMany CI/CD tools use private artifact registries to store built images. You must configure a secret containing login credentials to use other private registries, for example Docker Hub or JFrog Artifactory. See Store credentials for a private image registry.
Public registriesPublic registries typically contain images intended for general use and do not require authorization to pull images. For example, Anyscale shares base images through a public Docker Hub registry.

Store credentials for a private image registry

Anyscale requires login credentials to pull images from private image registries. You must store these credentials in a secrets manager accessible in your Anyscale cloud.

Anyscale uses the same credentials as the docker login CLI command.

important

When available, Anyscale recommends using access token with read-only credentials instead of your personal username and password. For example, Docker Hub recommends using organization access tokens to manage access permissions for integrated services. See Docker Hub docs on organization access tokens.

Create a new secret in your secrets manager and add your login credentials using the following JSON format:

{
"username": "<username>",
"password": "<password>",
"server": "<server>"
}
ValueDescription
<username>The login username for a user or service account with read privileges on the image registry.
<password>The password or token used by the configured username.
<server>The URL for the server containing the private registry. For example, the server for Docker Hub is registry.hub.docker.com. Other registry providers might have a custom server for each customer. For example, JFrog Artifactory uses the pattern <company-name>.jfog.io.

Use registry login secrets on Anyscale

Use the registry_login_secret option when referring to images in private external image registries on Anyscale.

When you use this secret on Anyscale with the registry_login_secret option, Anyscale compares the server name configured with your secret to the server specified by the image URI. If the servers do not match, Anyscale does not submit your credentials to attempt to log in.

For Anyscale clouds on AWS, you can either specify the name of your secret or the full ARN. If you use the secret name, Anyscale uses the secret in the same account and region as the instance. To access secrets across accounts or regions, use the full ARN.

For Anyscale clouds on Google Cloud, you can either specify the name of your secret or the full identifier (/projects/<project-id>/secrets/<secret-name>/versions/<version>). If you use the secret name, Anyscale uses the latest version of the secret in the same project containing your Anyscale cloud. To access secrets across projects or specific versions, use the full identifier.