Skip to main content

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:

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.


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

base_image: anyscale/ray-ml:2.7.0optimized-py39-gpu
MY_VAR: '123'
- vim
- pkutils
- pkutils
- 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.

Creating a cluster environment

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

anyscale cluster-env build my_cluster_env.yaml --name my-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.