Image API Reference

Customer-hosted cloud features

note

Some features are only available on customer-hosted clouds. Reach out to support@anyscale.com for info.

Image CLI

anyscale image build

Usage

anyscale image build [OPTIONS]

Build an image from a Containerfile.

Options

• --containerfile/-f: Path to the Containerfile.
• --name/-n: Name for the image. If the image with the same name already exists, a new version will be built. Otherwise, a new image will be created.
• --ray-version/-r: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.

Examples

CLI

$ anyscale image build -f my.Dockerfile -n my-image --ray-version 2.21.0
(anyscale +2.8s) Building image. View it in the UI: https://console.anyscale.com/v2/...
(anyscale +1m53.0s) Waiting for image build to complete. Elapsed time: 102 seconds.
(anyscale +1m53.0s) Image build succeeded.
Image built successfully with URI: anyscale/image/my-image:1

$ cat my.Dockerfile
FROM anyscale/ray:2.21.0-py39
RUN pip install --no-cache-dir pandas

anyscale image get

Usage

anyscale image get [OPTIONS]

Get details of an image.

Options

• --name/-n: Get the details of an image.

The name can contain an optional version, e.g., 'name:version'. If no version is provided, the latest one will be used.

Examples

CLI

$ anyscale image get -n my-image
uri: anyscale/image/my-image:1
status: SUCCEEDED
ray_version: 2.21.0

anyscale image register

Usage

anyscale image register [OPTIONS]

Register a custom container image with a container image name.

Options

• --image-uri: The URI of the custom container image to register.
• --name/-n: Name for the container image. If the name already exists, a new version will be built. Otherwise, a new container image will be created.
• --ray-version/-r: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.
• --registry-login-secret: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image.

Examples

CLI

$ anyscale image register --image-uri docker.io/myrepo/image:v2 --name mycoolimage --ray-version 2.30.0
Image registered successfully with URI: anyscale/image/mycoolimage:1

Image SDK

anyscale.image.build

Build an image from a Containerfile.

Returns the URI of the image.

Arguments

• containerfile (str): The content of the Containerfile.
• name (str): The name of the image.
• ray_version (str | None) = None: The version of Ray to use in the image

Returns: str

Examples

Python

import anyscale

containerfile = '''
FROM anyscale/ray:2.21.0-py39
RUN pip install --no-cache-dir pandas
'''

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

anyscale.image.get

The name can contain an optional version tag, i.e., 'name:version'.

If no version is provided, the latest one will be returned.

Arguments

• name (str): Get the details of an image.

The name can contain an optional version, e.g., 'name:version'. If no version is provided, the latest one will be used.

Returns: ImageBuild

Examples

Python

import anyscale

image_status = anyscale.image.get(name="mycoolimage")

anyscale.image.register

Registers a BYOD image with a container image name.

Returns the URI of the image.

Arguments

• image_uri (str): The URI of the BYOD image to register.
• name (str): Name for the container image. If the name already exists, a new version will be built. Otherwise, a new container image will be created.
• ray_version (str | None) = None: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.
• registry_login_secret (str | None) = None: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image.

Returns: str

Examples

Python

import anyscale

image_uri: str = anyscale.image.register("docker.io/myuser/myimage:v2", name="mycoolimage")

Image Models

ImageBuild

ImageBuild(uri: str, status: Union[str, anyscale.image.models.ImageBuildStatus], ray_version: Optional[str])

Fields

• uri (str): The URI of the image for the build.
• status (str | ImageBuildStatus): The status of the image build.
• ray_version (str | None): The Ray version used for the image build.

Python Methods

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples

Python

import anyscale
from anyscale.models import ImageBuild, ImageBuildStatus

image_build: ImageBuild = anyscale.image.get("image-name")

CLI

$ anyscale image get -n my-image
uri: anyscale/image/my-image:2
status: SUCCEEDED

ImageBuildStatus

An enumeration.

Values

• IN_PROGRESS: The image build is in progress.
• SUCCEEDED: The image build succeeded.
• FAILED: The image build failed.
• UNKNOWN: The CLI/SDK received an unexpected state from the API server. In most cases, this means you need to update the CLI.

Cluster environment CLI Legacy

anyscale image archive Legacy

Limited support

This command is not actively maintained. Use with caution.

Usage

anyscale image archive [OPTIONS]

Archive the specified cluster environment.

Options

• --name/-n: Name of the cluster environment to archive.
• --cluster-env-id/--id: Id of the cluster environment to archive. Must be provided if a cluster environment name is not given.

anyscale image build Legacy

warning

This command is deprecated. Upgrade to anyscale image build.

Usage

anyscale image build [OPTIONS] CLUSTER_ENV_FILE

Build a new cluster environment from config file.

Options

• --name/-n: Name to save built cluster environment as. Default will be used if not provided

anyscale image get Legacy

warning

This command is deprecated. Upgrade to anyscale image get.

Usage

anyscale image get [OPTIONS] [CLUSTER_ENV_NAME]

Get details about cluster environment build. The cluster-env-name argument is a cluster environment name optionally followed by a colon and a build version number. Eg: my_cluster_env:1

Options

• --cluster-env-build-id/--id: Get details about cluster environment build by this id.

anyscale image list Legacy

Limited support

This command is not actively maintained. Use with caution.

Usage

anyscale image list [OPTIONS]

List information about cluster environments on Anyscale. By default only list cluster environments you have created.

Options

• --name/-n: List information about all builds of the cluster environment with this name.
• --cluster-env-id/--id: List information about all builds of the cluster environment with this id.
• --include-shared: Include all cluster environments you have access to.
• --max-items: Max items to show in list.

Cluster environment SDK Legacy

The AnyscaleSDK class must be constructed in order to make calls to the SDK. This class allows you to create an authenticated client in which to use the SDK.

Param	Type	Description
auth_token	Optional String	Authentication token used to verify you have permissions to access Anyscale. If not provided, permissions default to the credentials set for your current user. Credentials can be set by following the instructions on this page: https://console.anyscale.com/credentials

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK()

create_byod_cluster_environment_build Legacy

warning

This command is deprecated. Upgrade to anyscale.image.build.

Creates and starts a BYOD Cluster Environment Build.

Parameters

Name	Type	Description	Notes
create_byod_cluster_environment_build	CreateBYODClusterEnvironmentBuild

Returns ClusterenvironmentbuildoperationResponse

create_cluster_environment_build Legacy

warning

This command is deprecated. Upgrade to anyscale.image.build.

Creates and starts a Cluster Environment Build. This is a long running operation.

Parameters

Name	Type	Description	Notes
create_cluster_environment_build	CreateClusterEnvironmentBuild

Returns ClusterenvironmentbuildoperationResponse

find_cluster_environment_build_by_identifier Legacy

Limited support

This command is not actively maintained. Use with caution.

Looks for a cluster environment build given a cluster environment identifier. Identifiers are in the format my-cluster-env:1

Parameters

Name	Type	Description	Notes
identifier	str	Identifier of the cluster env to look for. Identifiers are in the format my-cluster-env:1	Defaults to null

Returns ClusterenvironmentbuildResponse

get_cluster_environment_build Legacy

Limited support

This command is not actively maintained. Use with caution.

Retrieves a Cluster Environment Build.

Parameters

Name	Type	Description	Notes
cluster_environment_build_id	str	ID of the Cluster Environment Build to retrieve.	Defaults to null

Returns ClusterenvironmentbuildResponse

get_default_cluster_environment_build Legacy

Limited support

This command is not actively maintained. Use with caution.

Retrieves a default cluster environment with the preferred attributes.

Parameters

Name	Type	Description	Notes
python_version	PythonVersion	Python version for the cluster environment	Defaults to null
ray_version	str	Ray version to use for this cluster environment. Should match a version string found in the ray version history on pypi. See here for full list: https://pypi.org/project/ray/#history	Defaults to null

Returns ClusterenvironmentbuildResponse

list_cluster_environment_builds Legacy

Limited support

This command is not actively maintained. Use with caution.

Lists all Cluster Environment Builds belonging to an Cluster Environment.

Parameters

Name	Type	Description	Notes
cluster_environment_id	str	ID of the Cluster Environment to list builds for.	Defaults to null
desc	optional bool	Orders the list of builds from latest to oldest.	Defaults to false
paging_token	optional str		Defaults to null
count	optional int		Defaults to 10

Returns ClusterenvironmentbuildListResponse

create_byod_cluster_environment Legacy

warning

This command is deprecated. Upgrade to anyscale.image.build.

Creates a BYOD Cluster Environment.

Parameters

Name	Type	Description	Notes
create_byod_cluster_environment	CreateBYODClusterEnvironment

Returns ClusterenvironmentResponse

create_cluster_environment Legacy

warning

This command is deprecated. Upgrade to anyscale.image.build.

Creates a Cluster Environment.

Parameters

Name	Type	Description	Notes
create_cluster_environment	CreateClusterEnvironment

Returns ClusterenvironmentResponse

get_cluster_environment Legacy

Limited support

This command is not actively maintained. Use with caution.

Retrieves a Cluster Environment.

Parameters

Name	Type	Description	Notes
cluster_environment_id	str	ID of the Cluster Environment to retrieve.	Defaults to null

Returns ClusterenvironmentResponse

search_cluster_environments Legacy

Limited support

This command is not actively maintained. Use with caution.

Lists all Cluster Environments that the logged in user has permissions to access.

Parameters

Name	Type	Description	Notes
cluster_environments_query	ClusterEnvironmentsQuery

Returns ClusterenvironmentListResponse

Cluster environment Models Legacy

ClusterEnvironment Legacy

Name	Type	Description	Notes
id	str	Server assigned unique identifier.	[default to null]
name	str	Name of the Cluster Environment.	[default to null]
project_id	str	ID of the Project this Cluster Environment is for.	[optional] [default to null]
organization_id	str	ID of the Organization this Cluster Environment was created in.	[default to null]
creator_id	str	ID of the User that created this record.	[default to null]
created_at	datetime	Timestamp of when this record was created.	[default to null]
last_modified_at	datetime	Timestamp of when this record was last updated.	[default to null]
deleted_at	datetime	Timestamp of when this record was deleted.	[optional] [default to null]
anonymous	bool	True if this is an anonymous Cluster Environment.	[optional] [default to false]
is_default	bool	True if this Cluster Environment is created and managed by anyscale	[optional] [default to false]

ClusterEnvironmentBuild Legacy

Usable Cluster Environment Build to start a Cluster.

Name	Type	Description	Notes
cluster_environment_id	str	ID of the Cluster Environment this Build belongs to.	[default to null]
config_json	AppConfigConfigSchema	Config JSON used to create this Cluster Environment Build.	[optional] [default to null]
containerfile	str	The containerfile used to build the image.	[optional] [default to null]
docker_image_name	str	The name of the docker image for this Build.	[optional] [default to null]
registry_login_secret	str	The name or identifier of a secret containing credentials to authenticate to the docker registry hosting the image.	[optional] [default to null]
ray_version	str	The Ray version to use for this build.	[optional] [default to null]
id	str	Server assigned unique identifier.	[default to null]
revision	int	Auto incrementing version number for this Build	[default to null]
creator_id	str	ID of the user who created this Build.	[default to null]
error_message	str	Detailed error message. This will only be populated if the Build operation failed.	[optional] [default to null]
status	ClusterEnvironmentBuildStatus	Status of the Build. `pending` - Build operation is queued and has not started yet. `in_progress` - Build operation is in progress. `succeeded` - Build operation completed successfully. `failed` - Build operation completed unsuccessfully. `pending_cancellation` - Build operation is marked for cancellation. `cancelled` - Build operation was cancelled before it completed.	[default to null]
created_at	datetime	Timestamp of when this Build was created.	[default to null]
last_modified_at	datetime	Timestamp of when this Build was last updated.	[default to null]
deleted_at	datetime	Timestamp of when this Build was deleted.	[optional] [default to null]
is_byod	bool	True if the image URI used in this build was user-specified.	[default to null]
cloud_id	str	The build cloud associated with this build. If None, the build is a v1 build.	[optional] [default to null]
digest	str	The digest of the image for this Build.	[optional] [default to null]

ClusterEnvironmentBuildOperation Legacy

Describes a long running operation that will eventually complete. Consider this an abstract class. Specific kinds of operations should subclass this.

Name	Type	Description	Notes
id	str	ID of this operation.	[default to null]
completed	bool	Boolean indicating if this operation is completed.	[default to null]
progress	OperationProgress	Details about the progress of this operation at the time of the request. This will be absent for completed operations.	[optional] [default to null]
result	OperationResult	The result of this operation after it has completed. This is always provided when the operation is complete.	[optional] [default to null]
cluster_environment_build_id	str	ID of the Cluster Environment Build this operation is for.	[default to null]

ClusterEnvironmentBuildStatus Legacy

An enumeration.

Possible Values: ['pending', 'in_progress', 'succeeded', 'failed', 'pending_cancellation', 'canceled']

ClusterEnvironmentsQuery Legacy

Name	Type	Description	Notes
project_id	str	Filters Cluster Environments by project id. If absent, no filtering is done.	[optional] [default to null]
creator_id	str	Filters Cluster Environments by creator id. If absent, no filtering is done.	[optional] [default to null]
name	TextQuery	Filters Cluster Environments by name. Currently only contains is supported.If absent, no filtering is done.	[optional] [default to null]
image_name	TextQuery	Filters Cluster Environments by image name. Image name is a virtual concept. It starts with 'anyscale/image' (for customer-built images) or 'anyscale/ray' (default images).Currently only contains is supported. If absent, no filtering is done.	[optional] [default to null]
paging	PageQuery	Pagination information.	[optional] [default to null]
include_archived	bool	Whether to include archived Cluster Environments in the results.	[optional] [default to false]
include_anonymous	bool	Whether to include anonymous Cluster Environments in the results.	[optional] [default to false]

ClusterenvironmentListResponse Legacy

A list response form the API. Contains a field "results" which has the contents of the response.

Name	Type	Description	Notes
results	List[ClusterEnvironment]		[default to null]
metadata	ListResponseMetadata		[optional] [default to null]

ClusterenvironmentResponse Legacy

A response from the API. Contains a field "result" which has the contents of the response.

Name	Type	Description	Notes
result	ClusterEnvironment		[default to null]

ClusterenvironmentbuildListResponse Legacy

A list response form the API. Contains a field "results" which has the contents of the response.

Name	Type	Description	Notes
results	List[ClusterEnvironmentBuild]		[default to null]
metadata	ListResponseMetadata		[optional] [default to null]

ClusterenvironmentbuildoperationResponse Legacy

A response from the API. Contains a field "result" which has the contents of the response.

Name	Type	Description	Notes
result	ClusterEnvironmentBuildOperation		[default to null]

CreateBYODClusterEnvironment Legacy

Model used to create a BYOD Cluster Environment.

Name	Type	Description	Notes
name	str	Name of the Cluster Environment.	[default to null]
config_json	CreateBYODClusterEnvironmentConfigurationSchema	Config JSON to use to create a new BYOD Cluster Environment.	[default to null]
anonymous	bool	True if this is an anonymous Cluster Environment.	[optional] [default to false]

CreateBYODClusterEnvironmentBuild Legacy

Model used to create a BYOD Cluster Environment Build.

Name	Type	Description	Notes
cluster_environment_id	str	ID of the Cluster Environment this Build belongs to.	[default to null]
config_json	CreateBYODAppConfigConfigurationSchema	Config JSON to use to create a new BYOD Build.	[default to null]

CreateBYODClusterEnvironmentConfigurationSchema Legacy

Name	Type	Description	Notes
docker_image	str	The custom container base image used in the Cluster Environment.	[default to null]
ray_version	str	The version of Ray used in the customer docker image.	[default to null]
env_vars	object	Environment variables in the docker image that will be used at runtime.	[optional] [default to null]
registry_login_secret	str	The name or identifier of a secret containing credentials to authenticate to the docker registry hosting the image.	[optional] [default to null]

CreateClusterEnvironment Legacy

Model used to create an Cluster Environment.

Name	Type	Description	Notes
name	str	Name of the Cluster Environment.	[default to null]
project_id	str	ID of the Project this Cluster Environment is for.	[optional] [default to null]
config_json	CreateClusterEnvironmentConfigurationSchema	Config JSON to use to create a new Cluster Environment.	[optional] [default to null]
containerfile	str	Containerfile to use to create a new Cluster Environment.	[optional] [default to null]
anonymous	bool	True if this is an anonymous Cluster Environment.	[optional] [default to false]

CreateClusterEnvironmentBuild Legacy

Model used to create a Cluster Environment Build.

Name	Type	Description	Notes
cluster_environment_id	str	ID of the Cluster Environment this Build belongs to.	[default to null]
config_json	CreateAppConfigConfigurationSchema	Config JSON to use to create a new Build.	[optional] [default to null]
containerfile	str	The containerfile used to build the image.	[optional] [default to null]
docker_image_name	str	The name of the docker image for this Build.	[optional] [default to null]
registry_login_secret	str	The name or identifier of a secret containing credentials to authenticate to the docker registry hosting the image.	[optional] [default to null]
ray_version	str	The Ray version to use for this build.	[optional] [default to null]

CreateClusterEnvironmentConfigurationSchema Legacy

Name	Type	Description	Notes
base_image	SUPPORTEDBASEIMAGESENUM	The base image to use to create a new Cluster Environment. It needs to be one of the images that we currently support (SupportedBaseImages).	[default to null]
env_vars	object	Environment varibles in the docker image that'll be used at runtime.	[optional] [default to null]
debian_packages	List[str]	List of debian packages that'll be included in the image.	[optional] [default to null]
python	PythonModules	Python related dependencies.	[optional] [default to null]
post_build_cmds	List[str]	List of post build commands that'll be included in the image.	[optional] [default to null]

RayRuntimeEnvConfig Legacy

A runtime env config. Can be used to start a production job.

Name	Type	Description	Notes
working_dir	str	The working directory that your code will run in. Must be a remote URI like an s3 or git path.	[optional] [default to null]
py_modules	List[str]	Python modules that will be installed along with your runtime env. These must be remote URIs.	[optional] [default to null]
relative_working_dir	str	Relative path to the working directory that your code will run in. The appropriate cloud deployment object storage will be prepended to this path.	[optional] [default to null]
relative_py_modules	List[str]	Relative paths to python modules that will be installed along with your runtime env. The appropriate cloud deployment object storage will be prepended to these paths. If `py_modules` are specified, they will be also be installed.	[optional] [default to null]
py_executable	str	Specifies the executable used for running the Ray workers. It can include arguments as well.	[optional] [default to null]
pip	List[str]	A list of pip packages to install.	[optional] [default to null]
conda	object	[Union[Dict[str, Any], str]: Either the conda YAML config or the name of a local conda env (e.g., "pytorch_p36"),	[optional] [default to null]
env_vars	Dict(str, str)	Environment variables to set.	[optional] [default to null]
config	object	Config for runtime environment. Can be used to setup setup_timeout_seconds, the timeout of runtime environment creation.	[optional] [default to null]
image_uri	str	Specifies the image URI of the container in which the job will run.	[optional] [default to null]