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:
- Define and build an Anyscale-compatible image. See Anyscale-compatible custom images.
- Upload your image to an image registry. See Supported external image registries.
- If necessary, store login credential in a secret manager. See Store credentials for a private image registry.
- Specify the image URI and credentials when configuring your Anyscale workload. See Launch a cluster with an image 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:
| Option | Description |
|---|---|
| Image URI | The URI for the image in your external registry. |
| Ray version | The version of Ray in the image. |
| Registry login secret | The 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 type | CLI | SDK | Config YAML |
|---|---|---|---|
| Workspace | anyscale workspace_v2 create | anyscale.workspace.create | WorkspaceConfig |
| Job | anyscale job submit | anyscale.job.submit | JobConfig |
| Service | anyscale service deploy | anyscale.service.deploy | ServiceConfig |
Supported external image registries
The following table describes common external image registries supported on Anyscale:
| Image registry | Description |
|---|---|
| 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 Registry | Artifact 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 registries | Many 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 registries | Public 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.
- For Anyscale clouds on AWS, see Configure access to Amazon Secrets Manager.
- For Anyscale clouds on Google Cloud, see Configure access to Google Secret Manager.
Anyscale uses the same credentials as the docker login CLI command.
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>"
}
| Value | Description |
|---|---|
<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.