Skip to main content

Image API Reference

View Markdown

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​

$ 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.

  • -j/--json: Output as JSON.
  • --yaml: Output as YAML.
  • -v/--verbose: Show all fields including IDs and metadata.

Examples​

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

anyscale image list​

Usage

anyscale image list [OPTIONS]

List images.

Options

  • --image-id/--id: ID of the image to display.
  • --name/-n: Substring to match against the image name.
  • --image-name: Substring to match against the resolved image URI (BYOD images only).
  • --project: Filter images by project name.
  • --created-by-me: List images created by me only.
  • --include-archived: Include archived images in the results.
  • --include-anonymous: Include anonymous (workspace-scoped) images.
  • --max-items: Max total items (only with --no-interactive).
  • --page-size: Items per page (max 50).
  • --interactive/--no-interactive: Use interactive paging.
  • -j/--json: Emit structured JSON to stdout.
  • -v/--verbose: Show all fields including IDs and metadata.

Examples​

$ anyscale image list --no-interactive --max-items 2
NAME         LATEST VERSION  LATEST URI                    CREATED BY           CREATED AT
my-image     3               anyscale/image/my-image:3     dhyey@anyscale.com   2024-12-01 18:42
workspace    1               anyscale/image/workspace:1    joshlee@anyscale.com 2024-11-09 09:15

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​

$ 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​

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​

import anyscale

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

anyscale.image.list​

List images or fetch a single image by ID.

Arguments

  • image_id (str | None) = None: If provided, returns just the image with this ID wrapped in a one-page iterator.
  • name (str | None) = None: Substring to match against the image name.
  • image_name (str | None) = None: Substring to match against the resolved image URI (BYOD images only).
  • project (str | None) = None: Name of the project that owns the image.
  • creator_id (str | None) = None: Filter images by the creator user ID.
  • include_archived (bool) = False: Include archived images (default: False).
  • include_anonymous (bool) = False: Include anonymous (workspace-scoped) images (default: False).
  • max_items (int | None) = None: Maximum total number of items to yield (default: iterate all).
  • page_size (int | None) = None: Number of items to fetch per API request (default: API default).

Returns: ResultIterator[ImageBuild]

Examples​

import anyscale

for image in anyscale.image.list(max_items=5):
    print(image.name, image.latest_build_revision)

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​

import anyscale

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

Image Models​

ImageBuildStatus​

Status of an image build operation.

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.

ImageBuild​

ImageBuild(id: str, name: str, project_id: Optional[str] = None, creator_id: Optional[str] = None, creator_email: Optional[str] = None, is_anonymous: bool = False, created_at: Optional[datetime.datetime] = None, last_modified_at: Optional[datetime.datetime] = None, latest_build_id: Optional[str] = None, latest_build_revision: Optional[int] = None, latest_build_status: Union[str, anyscale.image.models.ImageBuildStatus, NoneType] = None, latest_image_uri: Optional[str] = None)

Fields​

  • id (str): Unique identifier of the image.
  • name (str): Human-readable name assigned to the image (cluster environment).
  • project_id (str | None): Project identifier that owns this image, if available.
  • creator_id (str | None): Identifier of the user who created the image.
  • creator_email (str | None): Email address of the user who created the image, if available.
  • is_anonymous (bool): Whether the image was created as an anonymous (workspace-scoped) resource.
  • created_at (datetime | None): Timestamp when the image was created.
  • last_modified_at (datetime | None): Timestamp when the image was last updated.
  • latest_build_id (str | None): Identifier of the most recent build for this image.
  • latest_build_revision (int | None): Revision number of the most recent image build (treated as the latest version).
  • latest_build_status (str | ImageBuildStatus | None): Status of the most recent image build.
  • latest_image_uri (str | None): URI for the latest published image version, if available.

Python Methods​

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

Examples​

import anyscale
from anyscale.image.models import ImageBuild

first_image: ImageBuild = next(anyscale.image.list(max_items=1), None)