Image SDK reference

View Markdown

Image SDK reference

Customer-hosted cloud features

note

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

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
• cloud_id (str | None) = None: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

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.

• cloud_id (str | None) = None: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

Returns: ImageBuild

Examples

Python

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).
• cloud_id (str | None) = None: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

Returns: ResultIterator[ImageBuild]

Examples

Python

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.
• cloud_id (str | None) = None: The ID of the Anyscale Cloud to associate this image with. Required for Azure Control Plane only.

Returns: str

Examples

Python

import anyscale

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

anyscale.image.archive

Archive an image and all of its versions.

Once archived, the image name will no longer be usable in the organization. Archived images can still be viewed using include_archived=True in list().

Arguments

• name (str): Name of the image to archive. Can include an optional version tag (e.g., 'name:version').
• cloud_id (str | None) = None: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

Returns: None

Examples

Python

import anyscale

anyscale.image.archive(name="my-old-image")

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

Python

import anyscale
from anyscale.image.models import ImageBuild

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