Cluster Environments

Cluster environments are specially built Docker images that work efficiently with Ray inside of Anyscale. The following diagram illustrates the principles behind cluster environments:

Builds are individual Docker images and associated metadata for an environment at a point in time. Environment builds are immutable and never deleted, so you can always reproduce or rollback to an old state.

As time goes on, you can create new environment builds and incrementally update your application's code and dependencies over time.

Definition

Anyscale Cluster Environments

The following is a fully specified example of a cluster environment definition:

base_image: anyscale/ray-ml:2.7.0optimized-py39-gpu
env_vars:
  MY_VAR: '123'
debian_packages:
- vim
python:
  pip_packages:
  - pkutils
  conda_packages:
  - pkutils
post_build_cmds:
- ls

Note that you can specify the following in your cluster environments:

• (Required) A base Docker image, which must be some version of anyscale/ray (refer to the DockerHub page for details) or anyscale/ray-ml (refer to the DockerHub page for details).
• (Optional) Environment variables, which are available during the cluster environment build process and on runtime when the container starts.
• (Optional) Debian, pip and Conda packages, which will be installed on top of the packages included in the base image.
• (Optional) Post-build commands, which will run at the end of the build process for the cluster environment.

Custom Cluster Environments

Alternatively, you can manually specify a Docker image to use. See this section for more details on building and storing Anyscale compatible images.

docker_image: my-registry/my-image:tag
ray_version: 2.7.0 # Replace this with the version of Ray in your image
env_vars: # Optionally, specify environment variables
  MY_VAR: value

Note that you can specify the following when using a customer docker environment:

• (Required) A Docker image URI, for example <account-id>.dkr.ecr.<region>.amazonaws.com/image:tag. Anyscale can access any publicly available image, and private Amazon ECR repositories if permissions are set up.
• (Required) The version of Ray in your image. You can check this with docker run --entrypoint ray <your-image> --version
• (Optional) Environment variables that will be set when the cluster is launched.

Creating a cluster environment

You can create a cluster environment using the CLI, the Python SDK and the HTTP API:

CLI

anyscale cluster-env build my_cluster_env.yaml --name my-cluster-env

Python SDK

import yaml

from anyscale.sdk.anyscale_client.models import CreateClusterEnvironment
from anyscale import AnyscaleSDK

sdk = AnyscaleSDK()

with open('my_cluster_env.yaml') as f:
    cluster_env = yaml.safe_load(f)

sdk.build_cluster_environment(CreateClusterEnvironment(
    name="my-cluster-env",
    config_json=cluster_env
))

For more information, you can check the full reference of the CLI, Python SDK and the HTTP API.

You can also create a cluster environment in the Web UI by navigating to "Configurations > Cluster environments > Create a new config" to create a cluster environment. If you want to update the cluster environment, you must select "Create a new version" which will create a new build for your environment.

Referencing a cluster environment

When starting an Anyscale Job or an Anyscale Service, you can specify the version of Cluster Environment to use in the YAML using cluster_env_name:version, or just cluster_env_name to use the latest version. For Workspaces, you can specify it using the UI.