Manage runtime images

This page describes how to create, view, update, and manage runtime images and runtime image versions using the H2O MLOps Python client.

To learn more about the runtime hierarchy, see Understand runtime management.

Prerequisites

Before you begin:

1. Import the necessary Python packages. For instructions, see Step 1: Import the required packages.
2. Connect to H2O MLOps. For instructions, see Connect to H2O MLOps.
3. Retrieve a workspace. For instructions, see Retrieve a workspace. If you do not have a workspace, see Create a workspace.

Create a runtime image

Create a runtime image within the workspace using the create() method. Specify the name and Docker image URI:

image = workspace.runtimes.images.create(
   name="My Custom Scorer",
   docker_image="docker.io/myorg/scorer:2.0.0",
   description="Custom scoring runtime for XGBoost models"
)

The version is automatically extracted from the Docker tag. The SDK prepends v to the tag, so in this example, the version is set to v2.0.0.

To specify an explicit version (for non-semver tags like latest or nightly):

image = workspace.runtimes.images.create(
   name="My Custom Scorer",
   docker_image="docker.io/myorg/scorer:latest",
   version="v1.0.0",
   description="Custom scoring runtime"
)

View runtime images

Count runtime images

Get the total number of runtime images in a workspace:

Input:

workspace.runtimes.images.count()

Output:

3

List runtime images

List all runtime images in a workspace (includes both bootstrap-managed and API-managed images):

Input:

images = workspace.runtimes.images.list()
images

Output:

   | name               | uid
---+--------------------+--------------------------------------
 0 | My Custom Scorer   | a1b2c3d4-e5f6-7890-abcd-ef1234567890

note

• The list() method returns a formatted table. By default, the table shows the first 50 rows.

• Calling len(images) returns the total number of rows, not just the number currently displayed.

• To customize the number of rows displayed, call the show() method with the n argument. For example:

  images.show(n=100)

  This displays up to 100 runtime images.

• The images object supports iteration.

Filter runtime images

Use the list() method with key-value arguments to filter runtime images.

Filter by state:

Input:

workspace.runtimes.images.list(state="ACTIVE")

Output:

   | name               | uid
---+--------------------+--------------------------------------
 0 | My Custom Scorer   | a1b2c3d4-e5f6-7890-abcd-ef1234567890

Filter by name:

Input:

workspace.runtimes.images.list(name="My Custom Scorer")

Output:

   | name               | uid
---+--------------------+--------------------------------------
 0 | My Custom Scorer   | a1b2c3d4-e5f6-7890-abcd-ef1234567890

Retrieve a runtime image

Retrieve a runtime image by UID:

image = workspace.runtimes.images.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

List runtime images across all workspaces

Administrators can list runtime images across all workspaces:

client.runtimes.images.list()

Runtime image properties

A runtime image has the following main properties:

• uid: The unique identifier for the runtime image.
• name: The display name.
• docker_image: The current Docker image URI.
• state: The current state (ACTIVE, DEPRECATED, or DISABLED).
• managed_by_bootstrap: Whether this image is managed through Helm bootstrap configuration.
• current_version: The latest active version object.

Update a runtime image

Make sure to retrieve the runtime image instance before updating it. See Retrieve a runtime image.

caution

Bootstrap-managed runtime images cannot be updated through the SDK. If image.managed_by_bootstrap is True, the update call returns an error. To modify a bootstrap-managed runtime image, edit the Helm values.yaml file and redeploy the Helm chart. For details, see Helm configuration for runtimes.

Update metadata:

image.update(
   name="Updated Name",
   description="Updated description"
)

Add a new version by updating the Docker image:

image.update(docker_image="docker.io/myorg/scorer:3.0.0")

This automatically creates a new version v3.0.0.

note

Both image.update(docker_image=...) and image.versions.create(docker_image=...) create a new version. Use image.update() as a shorthand that adds the version in a single call. Use image.versions.create() when you need the returned version object or want to manage versions independently from image metadata.

To add a new version with an explicit version string:

image.update(
   docker_image="docker.io/myorg/scorer:rc-build-42",
   version="v3.1.0-rc1"
)

Runtime image state management

Change the state of a runtime image:

image = workspace.runtimes.images.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

# Deprecate (still usable, with warning)
image.deprecate(reason="Use v3.x instead")

# Disable (blocks new deployments using this image)
image.disable(reason="Security vulnerability CVE-2024-12345")

# Re-enable
image.enable()

caution

For bootstrap-managed runtime images, state changes follow a ceiling rule: the SDK cannot re-enable an image beyond the state set by the platform, and vice versa. For example, if the platform disabled an image, calling image.enable() returns an error. For details, see State constraints between management modes.

Delete a runtime image

warning

Only API-managed runtime images can be deleted. Bootstrap-managed runtime images cannot be deleted through the SDK. A runtime image can only be deleted if no runtimes reference it.

image.delete()

Manage runtime image versions

Each runtime image can have multiple versions. Versions are individual container images with semantic version identifiers.

List versions

Input:

image = workspace.runtimes.images.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
image.versions.list()

Output:

   | version   | docker_image                          | state
---+-----------+---------------------------------------+--------
 0 | v2.1.0    | docker.io/myorg/scorer:2.1.0          | ACTIVE
 1 | v2.0.0    | docker.io/myorg/scorer:2.0.0          | ACTIVE

Filter by state:

image.versions.list(state="ACTIVE")

Count versions

Input:

image.versions.count()

Output:

2

Create a new version

Create a version with automatic version extraction from the Docker tag:

new_version = image.versions.create(
   docker_image="docker.io/myorg/scorer:2.1.0"
)

This creates version v2.1.0 (the SDK prepends v to the Docker tag automatically).

Create a version with an explicit version string:

new_version = image.versions.create(
   docker_image="docker.io/myorg/scorer:nightly-20250601",
   version="v2.2.0-nightly"
)

Inspect a version

Input:

version = image.versions.get("v2.1.0")
print(version.version)
print(version.docker_image)
print(version.state)
print(version.created_time)

Output:

v2.1.0
docker.io/myorg/scorer:2.1.0
ACTIVE
2025-06-03 15:33:10+00:00

Version state management

version = image.versions.get("v1.0.0")

# Deprecate old version
version.deprecate(reason="Use v2.x instead")

# Disable version entirely
version.disable(reason="Known bug in scoring pipeline")

# Re-activate
version.activate()

caution

For bootstrap-managed runtime image versions, state changes follow the same ceiling rule as runtime images: the SDK cannot re-enable a version beyond the state set by the platform, and vice versa. For details, see State constraints between management modes.

note

Runtime image versions use activate() to re-enable, while runtime images and runtimes use enable().

Get the current version

The current version is the highest semantic version that is not DISABLED. Both ACTIVE and DEPRECATED versions are eligible. If all versions are DISABLED, the value is None.

Input:

current = image.current_version
print(current.version)
print(current.docker_image)

Output:

v2.1.0
docker.io/myorg/scorer:2.1.0

For details on how H2O MLOps resolves versions when no specific version is requested, see Understand runtime management.

---

Feedback

• Submit and view feedback for this page
• Send feedback about H2O MLOps to cloud-feedback@h2o.ai