chi.container

The chi.container module exposes a functional interface for interacting with application containers.

Important

Currently, only the CHI@Edge site support container operations.

class chi.container.Container(name: str, image_ref: str, exposed_ports: List[str], reservation_id: str | None = None, start: bool = True, start_timeout: int = 0, runtime: str | None = None)[source]

Represents a container in the system.

Parameters:

  • name (str) – The name of the container.

  • image_ref (str) – The reference to the container image.

  • exposed_ports (List[str]) – A list of ports exposed by the container.

  • reservation_id (str, optional) – The reservation ID associated with the container. Defaults to None.

  • start (bool, optional) – Indicates whether to start the container. Defaults to True.

  • start_timeout (int, optional) – The timeout value for starting the container. Defaults to None.

  • runtime (str, optional) – The runtime environment for the container. Defaults to None.

name

The name of the container.

Type:

str

image_ref

The reference to the container image.

Type:

str

exposed_ports

A list of ports exposed by the container.

Type:

List[str]

reservation_id

The reservation ID associated with the container.

Type:

str

start

Indicates whether to start the container.

Type:

bool

start_timeout

The timeout value for starting the container.

Type:

int

runtime

The runtime environment for the container.

Type:

str

id

The ID of the container.

Type:

str

created_at

The timestamp when the container was created.

Type:

str

status

The current status of the container.

Type:

str

associate_floating_ip(fip: str | None = None)[source]

Associates a floating IP with the container.

Parameters:

fip (str, optional) – The floating IP to associate with the container. Defaults to None.

Returns:

The result of the association operation.

delete()[source]

Deletes the container.

If the container has an ID, it calls the destroy_container function to delete the container. After deletion, it sets the ID and status of the container to None.

Parameters:

None

Returns:

None

download(remote_source: str, dest: str) → None[source]

Downloads a file from a remote source to the specified destination.

Parameters:

  • remote_source (str) – The URL or path of the remote file to download.

  • dest (str) – The destination path where the file will be saved.

Returns:

None

execute(command: str) → Tuple[str, str][source]

Executes a command inside the container and returns the output and exit code.

Parameters:

command (str) – The command to be executed inside the container.

Returns:

A tuple containing the output of the command and the exit code.

Return type:

Tuple[str, str]

show(type: str = 'text', wait_for_active: bool = False)[source]

Display information about the container.

Parameters:

  • type (str, optional) – The type of display. Can be “text” or “widget”. Defaults to “text”.

  • wait_for_active (bool, optional) – Whether to wait for the container to be in the “Running” state before displaying information. Defaults to False.

submit(wait_for_active: bool = True, wait_timeout: int | None = None, show: str = 'widget', idempotent: bool = False)[source]

Submits the container for creation and performs additional actions based on the provided parameters.

Parameters:

  • wait_for_active (bool, optional) – Whether to wait for the container to become active. Defaults to True.

  • wait_timeout (int, optional) – The maximum time (in seconds) to wait for the container to become active. Defaults to None.

  • show (str, optional) – The type of output to display. Defaults to “widget”.

  • idempotent (bool, optional) – Whether to update the existing container if it already exists. Defaults to False.

Raises:

ResourceError – If the container creation fails.

Returns:

None

upload(source: str, remote_dest: str) → None[source]

Uploads a file from the local machine to the remote destination in the container.

Parameters:

  • source (str) – The path of the file on the local machine.

  • remote_dest (str) – The destination path in the container where the file will be uploaded.

Returns:

None

wait(status: str = 'Running', timeout: int | None = None)[source]

Waits for the container to reach the specified status.

Parameters:

  • status (str, optional) – The status to wait for. Defaults to “Running”.

  • timeout (int, optional) – The maximum time to wait in seconds. Defaults to None.

Returns:

None

chi.container.associate_floating_ip(container_ref: str, floating_ip_address=None) → str[source]

Deprecated since version 1.0.

Assign a Floating IP address to a container.

The container’s first address will be used for the assignment.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • floating_ip_address (str) – The Floating IP address, which must already be owned by the requesting project. If not defined, a Floating IP will be allocated, if there are any available.

Returns:

The Floating IP address, if it was bound successfully, else None.

chi.container.create_container(name: str, image: str | None = None, exposed_ports: list[str] | None = None, reservation_id: str | None = None, start: bool = True, start_timeout: int | None = None, platform_version: int = 2, **kwargs)[source]

Deprecated since version 1.0.

Create a container instance.

Parameters:

  • name (str) – The name to give the container.

  • image (str) – The Docker image, with or without tag information. If no tag is provided, “latest” is assumed.

  • device_profiles (list[str]) – An optional list of device profiles to request be configured on the container when it is created. Edge devices may have differing sets of supported device profiles, so it is important to understand which profiles are supported by the target device for your container.

  • environment (dict) – A set of environment variables to pass to the container.

  • exposed_ports (list[str]) – A list of ports to expose on the container. TCP or UDP can be provided with a slash prefix, e.g., “80/tcp” vs. “53/udp”. If no protocol is provided, TCP is assumed.

  • host (str) – The Zun host to launch a container on. If not specified, the host is chosen by Zun.

  • runtime (str) – The container runtime to use. This should only be overridden when explicitly launching containers onto a host/platform requiring a separate runtime to, e.g., pass-through GPU devices, such as the “nvidia” runtime provided by NVIDIA Jetson Nano/TX2.

  • start (bool) – Whether to automatically start the container after it is created. Default True.

  • **kwargs – Additional keyword arguments to send to the Zun client’s container create call.

chi.container.destroy_container(container_ref: str)[source]

Deprecated since version 1.0.

Delete the container.

This will automatically stop the container if it is currently running.

Parameters:

container_ref (str) – The name or ID of the container.

chi.container.download(container_ref: str, source: str, dest: str)[source]

Deprecated since version 1.0.

Download a file or directory from a running container.

This method requires your running container to include both the POSIX sh and GNU tar utilities.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • source (str) – The (container) path of the file or directory.

  • dest (str) – The (local) path to download to.

chi.container.execute(container_ref: str, command: str) → dict[source]

Deprecated since version 1.0.

Execute a one-off process inside a running container.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • command (str) – The command to run.

Returns:

A summary of the output of the command, with “output” and “exit_code”.

chi.container.get_container(name: str) → Container | None[source]

Retrieve a container by name.

Parameters:

name (str) – The name of the container to retrieve.

Returns:

The retrieved container object, or None if the container does not exist.

Return type:

Optional[Container]

chi.container.get_logs(container_ref: str, stdout=True, stderr=True)[source]

Deprecated since version 1.0.

Print all logs outputted by the container.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • stdout (bool) – Whether to include stdout logs. Default True.

  • stderr (bool) – Whether to include stderr logs. Default True.

Returns:

A string containing all log output. Log lines will be delimited by

newline characters.

chi.container.list_containers() → List[Container][source]

Retrieve a list of containers.

Returns:

A list of Container objects representing the containers.

chi.container.snapshot_container(container_ref: str, repository: str, tag: str = 'latest') → str[source]

Deprecated since version 1.0.

Create a snapshot of a running container.

This will store the container’s file system in Glance as a new Image. You can then specify the Image ID in container create requests.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • repository (str) – The name to give the snapshot.

  • tag (str) – An optional version tag to give the snapshot. Defaults to “latest”.

chi.container.upload(container_ref: str, source: str, dest: str) → dict[source]

Deprecated since version 1.0.

Upload a file or directory to a running container.

This method requires your running container to include the GNU tar utility.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • source (str) – The (local) path to the file or directory to upload.

  • dest (str) – The (container) path to upload the file or directory to.

chi.container.wait_for_active(container_ref: str, timeout: int = 120) → Container[source]

Deprecated since version 1.0.

Wait for a container to transition to the running state.

Parameters:

  • container_ref (str) – The name or ID of the container.

  • timeout (int) – How long to wait before issuing a TimeoutError.

Raises:

TimeoutError – if the timeout was reached before the container started.

Returns:

The container representation.