Using Container Tools

A Rockface container tool allows a process running within a Linux container to interact with your device via USB.

In the rockface python library, power supply tools are represented using the rockface.tools.container.ContainerTool type:

from rockface import Rig
from rockface.tools.container import ContainerTool

rig = Rig.find_by_name("my-rig")
container = rig.tools["my-container"]

assert isinstance(container, ContainerTool)

Examples continue from the above

For brevity, the rest of the examples on this page will continue on from the above example, with the container variable set to a ContainerTool instance.

Running a Container

A container can be invoked using its run method. This takes a container registry location to pull the container image from, as well as the command to run in that container:

job = container.run("alpine:latest", ["echo", "Hello Rockface"])

Execution State

After a call to run, the returned Job instance represents the container. The is_running property of this object may be used to determine if the container job is still active:

import time

job = container.run("alpine:latest", ["sleep", "3"])

print(job.is_running)
time.sleep(5)
print(job.is_running)

Standard Output and Error

The stdout property of the Job instance provides access to the standard output of the container. This provides a file-like object:

print(job.stdout.read())

Similarly, the stderr property provides access ot the standard error output of the container:

print(job.stderr.read())

Standard Output and Standard Error are currently only available once a job has completed

Future versions of this tool will make this available during execution.

Return Code

Once the job is complete, the return_code property of the Job instance provides access to the return code of the container:

print(f"The container's return code was {job.return_code}")

Termination

A running container may be terminated by either sending it a SIGTERM or a SIGKILL signal:

job = container.run("alpine:latest", ["sleep", "infinity"])

# Send a SIGTERM signal to the container
job.terminate()

# Send a SIGKILL signal to the container
job.kill()

Registry Authentication

The username and password for a private container registry can be provided as arguments to the run method:

job = container.run("foo.com/baa:latest",
                    ["echo", "Hello Rockface"],
                    username="someone",
                    password="a secret")

Reset

A container tool can be reset using its reset method:

container.reset()

This causes the running container to be terminated. A container tool will always be reset at the end of a session (when the rig lock is dropped).