Custom images on Anyscale

Anyscale recommends building a custom image before moving any workload from development to production.

Custom images package environment variables, dependencies, and code assets into an immutable container image. Anyscale provides the following options for building, uploading, and configuring access to custom images:

• Build an image using the Anyscale console, SDK, or CLI. See Build a custom image on Anyscale.
• Reference an image from an external image registry. See Use container images from an external registry.
• Register a custom image in your Anyscale organization. See Register a custom image.

For a tutorial on building custom images and referencing them from an external registry, see Tutorial: Build a custom container image.

Anyscale-compatible custom images

Most custom images extend a base image provided by Anyscale. For a full list of base images and their dependencies, see Anyscale base images.

You can build an image that's not based on an Anyscale base image, but must follow minimum specifications. See Requirements for an Anyscale container image.

If you're building your custom image on Anyscale, you can use init scripts to run arbitrary programs as part of the build process. See Use init scripts with custom images.

The Anyscale base images come with a default entrypoint set. Overwriting this entrypoint may break the web terminal and Jupyter notebook server when you launch your cluster.

Register a custom image

You can use the Anyscale console, CLI, or SDK to register custom images from an external image registry to your Anyscale organization. When you register an image, it becomes available to all users in your Anyscale organization.

Once you've registered an image to Anyscale, you can use it the same way you use a custom image built on Anyscale. The Anyscale URI for registered images uses the following format:

anyscale/image/<image-name>:<version>

note

Unlike the custom images built on Anyscale that appear in the Anyscale image registry, registering a custom image from an external registry doesn't store the built image in the Anyscale control plane.

After accessing your image from an external registry, Anyscale builds and caches an optimized version of your image in the object storage configured for the Anyscale cloud in which your job, service, or workspace runs. Anyscale uses the cached image to deploy all nodes in your Ray cluster.

You can use images from external image registries without registering them to your organization. See Use container images from an external registry.

The following table describes the fields you must configure when registering an image:

Field	Description
Name	The name used to register the image in the Anyscale container image registry. If you reuse an existing name, registering an image creates a new version.
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. Required unless the image registry is public or accessible through the IAM role of your Anyscale cloud. You must configure a secret to store login credentials. See Store credentials for a private image registry.

important

If you're using a serverless Anyscale cloud (also called an Anyscale-hosted cloud), you can only use images in external registries that are publicly accessible.

To register an image from an external registry, complete the following steps:

Console

note

The Anyscale console does not include the option to specify a registry login secret. Use the CLI or SDK if you need to access a private registry outside your cloud provider account.

1. Navigate to the Anyscale console.
2. From the console home screen, select Advanced > Container images.
3. Click + Build.
4. In the Name field, provide a unique name for the image.
   • The URI of the image generates automatically. Use this URI to reference this image when you create a workspace, job, or service.
5. Under Build step, select Use an image from an external registry.
6. Enter the URI for the image in your external registry in the Image URI field.
7. For the Ray version option, select the version that corresponds to your image.
8. Click Build.

CLI

Run the following command from the Anyscale CLI, substituting the correct values for each placeholder value in the example syntax:

anyscale image register --image-uri <image-registry>:<image-tag> \
    --name <anyscale-image-name> \
    --ray-version <version> \
    --registry-login-secret <secret-name>

SDK

When you register an image, the SDK returns the URI identifying the image in the Anyscale container image registry.

Use the following command to register an image from the SDK, substituting the correct values for each placeholder value in the example syntax:

import anyscale

image_uri = anyscale.image.register(
    image_uri = "<image-registry>:<image-tag>", 
    name="<anyscale-image-name>",
    ray_version="<version>",
    registry_login_secret="<secret_name>"
    )