Container images

Container images are the standard for production workloads. These isolated environments encapsulate all necessary elements for software execution, including code, runtime, system tools, libraries, and settings, ensuring consistent operation across different computing environments. Anyscale integrates container images as a core concept; all clusters (Workspaces, Jobs, or Services) run with a predefined container image. Simply pass the URI of any image using --image-uri to use it in your application.

Base Images

Anyscale provides a set of pre-built container images out of the box with permutations of Ray versions, Python, and other common dependencies.

info

You can distinguish the image type by the naming convention.

For example: anyscale/ray:2.30.0-slim-py310-cu123 means:

• Ray version is 2.30.0.
• Image type is slim.
• Python version is 3.10.
• CUDA version is 12.3.

Anyscale base images come in multiple flavors:

1. Slim images: These images contain the minimum set of dependencies required to run on Anyscale. We recommend starting with slim images for the best performance, for example, anyscale/ray:2.30.0-slim-py310.

2. Ray images: These are the official rayproject/ray images, for example, anyscale/ray:2.30.0.

3. Ray ML CPU images: These are the CPU flavor of the rayproject/ray-ml pipeline, for example, anyscale/ray-ml:2.30.0-py310-cpu.

4. Ray ML GPU images: These are the GPU flavor of the rayproject/ray-ml pipeline, for example, anyscale/ray-ml:2.30.0-py310-gpu.

Customizing a container image

Anyscale offers a cloud-hosted image build-farm that provides a simple and powerful way to quickly iterate over the Anyscale base images. On every iteration, Anyscale generates a new revision number, making it easy to revert to previous versions if needed.

To build a custom container image, you can use a Dockerfile-like interface where you specify the base Anyscale image. This interface supports the following Dockerfile instructions:

• FROM: Create a new build from an Anyscale base image. Currently, only Anyscale base images are supported. Reach out to preview-support@anyscale.com if you would like to use other images in the build farm.

• ENV: Set environment variables.
• WORKDIR: Change the working directory. Note, this is only for build time and does not affect where Anyscale starts your job, service, or the workspace default working directory.
• COPY: Copy files and directories only from a previous build stage, not from local storage.
• RUN: Execute build commands.

You can create a container image from the UI, CLI, or SDK.

UI

1. Go to container images.

2. Click on the Create button.

3. Define the name of the image. Note how the URI of the image is generated. This URI is how you reference this image in the future when creating your Anyscale workspace, jobs, or services.
4. Define the content of the image.

CLI

1. Define the content of the image:

FROM anyscale/ray:2.30.0-slim-py310
RUN pip install --no-cache-dir pandas

2. Build the image:

$ anyscale image build -n my-image-name --ray-version 2.30.0 -f Dockerfile

(anyscale +2.9s) Building image... See details: https://console.anyscale.com/v2/container-images/XXXXX.
(anyscale +1m33.3s) Waiting for image build to complete. Elapsed time: 87 seconds.
(anyscale +1m33.3s) Image build succeeded
Image built successfully with URI: anyscale/image/my-image-name:1

SDK

import anyscale

containerfile = '''
FROM anyscale/ray:2.30.0-slim-py310
RUN pip install --no-cache-dir pandas
'''

image_uri: str = anyscale.image.build(containerfile, name="mycoolimage")

Start a cluster with a container image

You can use the image-uri generated above to start any cluster on Anyscale.

Workspace

For new workspaces:

1. Go to the workspaces page.
2. Click on the Create button, then "Custom blank workspace".

3. In the "Container image" section, select use my own image and configure the image_uri and the ray version.

For existing workspaces:

1. Go to the dependency tab
2. Click the edit button on the container image.
3. Select "Use my own image" option.

Job

1. From the CLI, you can pass the image as an argument:

# Pass this in the command line
anyscale job submit -f job.yaml --image-uri anyscale/image/my-image-name:1 --ray-version 2.30.0

Or you can pass it inside the job configuration.

# Add it to the job config
image_uri: anyscale/image/my-image-name:1
ray_version: 2.30.0
...

2. From the SDK:

import anyscale
from anyscale.job.models import JobConfig

anyscale.job.submit(
    JobConfig(
        name="my-job",
        image_uri="anyscale/image/my-image-name:1",
        ray_version="2.30.0",
    ),
)

Service

1. From the CLI, you can pass the image as an argument:

anyscale service deploy -f service.yaml --image-uri anyscale/image/my-image-name:1 --ray-version 2.30.0

Or you can pass it inside the service configuration.

image_uri: anyscale/image/my-image-name:1
ray_version: 2.30.0
...

2. From the SDK:

import anyscale
from anyscale.service.models import ServiceConfig

anyscale.service.deploy(
    ServiceConfig(
        name="my-service",
        image_uri="anyscale/image/my-image-name:1",
        ray_version="2.30.0",
    ),
)

Bring your own image

Anyscale supports externally built images. Simply pass in the URI of your image in the image_uri field as you would for Anyscale-hosted images. However, ensure that your image adheres to Anyscale's minimum requirements.

For customer-hosted clouds, these images need to be accessible by your cloud (for example, an ECR registry in AWS). For Anyscale-hosted clouds, the images must be in a public registry (for example, Docker Hub).

You can review our complete guide on how to build your own custom image for more information.

Workspace

1. Go to the dependency tab.
2. Click the edit button on the container image.
3. Select the "Use my own image" option.

4. Make sure to choose the version of Ray you have installed in your image.

Job

1. From the CLI, you can pass the image as an argument:

# Pass this in the command line
anyscale job submit -f job.yaml --image-uri hub.docker.com/image/my-image-name:latest --ray-version 2.30.0

Or you can pass it inside the job configuration.

# Add it to the job config
image_uri: hub.docker.com/image/my-image-name:latest
ray_version: 2.30.0

2. From the SDK:

import anyscale
from anyscale.job.models import JobConfig

anyscale.job.submit(
    JobConfig(
        name="my-job",
        image_uri="hub.docker.com/image/my-image-name:latest",
        ray_version="2.30.0",
    ),
)

Service

1. From the CLI, you can pass the image as an argument:

anyscale service deploy -f service.yaml --image-uri hub.docker.com/image/my-image-name:latest --ray-version 2.30.0

Or you can pass it inside the service configuration.

image_uri: hub.docker.com/image/my-image-name:latest
ray_version: 2.30.0
...

2. From the SDK:

import anyscale
from anyscale.service.models import ServiceConfig

anyscale.service.deploy(
    ServiceConfig(
        name="my-service",
        image_uri="hub.docker.com/image/my-image-name:latest",
        ray_version="2.30.0",
    ),
)