Container Support¶
To use LPUs on a Linux host that already has a running container runtime, prepare these three parts:
| Location | What to add or change |
|---|---|
| LPU host | Install the driver and container toolkit (ha-ctk) through the hyperaccel-lpu package |
| Existing runtime | Enable CDI and configure it to read specifications from /etc/cdi |
| Container invocation | Request the LPUs to use by CDI name |
The Container Device Interface (CDI) passes LPU device files and user-mode driver libraries into containers.
ha-ctk records this information in /etc/cdi/lpu.yaml, so you specify an LPU name at launch rather than listing device paths individually.
Preparing the host¶
Install hyperaccel-lpu on the LPU host by following Quick install.
If it is already installed, start by checking device discovery and the CDI specification. With a remote Docker daemon, perform these steps on the daemon host as well.
1 2 3 | |
If the specification is missing or the card configuration has changed, regenerate it with sudo ha-ctk cdi generate.
cdi list shows the host's cards, while cdi validate checks name resolution in the saved specification.
Use the SDK example below to verify that the cards are actually available inside a container.
Docker setup and execution¶
The changes needed in an existing Docker environment are enabling CDI and configuring its specification search paths.
CDI is available in Docker Engine 25 or later on Linux and is enabled by default starting with 28.3.0.
If CDI is already enabled and Docker reads /etc/cdi, skip configuration changes and the restart.
If CDI configuration is needed, save a copy of the existing /etc/docker/daemon.json, then run:
1 2 3 4 | |
ha-ctk sets features.cdi=true and cdi-spec-dirs=["/etc/cdi","/var/run/cdi"].
--dry-run only prints the changes. The toolkit does not restart Docker after writing the configuration, so you must restart it to apply the changes.
Restarting can affect running containers; do it during a maintenance window.
Then add --device hyperaccel.ai/lpu=0 to your existing docker run command to request one LPU.
This example verifies the connection using the SDK image:
1 2 3 | |
The connection check passes when the command prints a card count of 1 and exits with code 0. You do not need to install the Python SDK separately on the host.
Selecting cards¶
Change the name passed to --device to select the cards to use.
| CDI name | Requested cards |
|---|---|
hyperaccel.ai/lpu=0 |
Card 0 |
hyperaccel.ai/lpu=0000_35_00.0 |
The card at this PCI address |
hyperaccel.ai/lpu=all |
All cards |
Indices follow the order in which the driver discovers cards at boot, so they can change when cards are replaced or faulty cards are excluded.
To select the same card consistently, find its PCI address with lspci -d 20fb: and replace colons (:) with underscores (_).
When checking with =all, the card count inside the container must match the total number of available cards confirmed on the host.
Containerd setup and execution¶
Standalone execution: nerdctl¶
If a CDI-capable nerdctl is already available, add --device just as you would with Docker.
nerdctl reads the CDI specification directly, so this path requires neither changes to containerd's CRI configuration nor a restart.
1 2 3 | |
As in the Docker example, check that the command prints 1 and exits with code 0.
CRI configuration for orchestrators¶
If CDI is disabled in containerd 1.7's CRI, apply the following. This assumes the existing configuration file uses version = 2.
ha-ctk sets enable_cdi=true and the specification search paths under
[plugins."io.containerd.grpc.v1.cri"] in the existing /etc/containerd/config.toml.
1 2 3 | |
If the configuration is not at the default path, set --config to the actual file. Restart during a node maintenance window.
containerd 2.x enables CDI by default and uses different plugin keys, so do not apply the 1.x configuration commands above unchanged.
Verify LPU access through CRI with the Kubernetes Pod example.
CRI-O setup and use¶
If the existing CRI-O runtime already reads specifications from /etc/cdi, no additional configuration is needed.
Apply the following only when you need to add the search paths.
ha-ctk writes cdi_spec_dirs to /etc/crio/crio.conf.d/99-ha-cdi.conf.
1 2 3 | |
Save a copy of the configuration file, then apply the changes during a node maintenance window. CRI-O is a CRI server, not a direct execution CLI like Docker, so use the Kubernetes Pod example to request and verify LPUs.
ha-ctk commands¶
| Command | What it does |
|---|---|
ha-ctk precheck |
Checks the host and reports what is missing without installing anything |
ha-ctk cdi generate |
Regenerates the CDI specification |
ha-ctk cdi list |
Shows information about cards discovered on the host |
ha-ctk cdi validate |
Parses the saved specification and resolves CDI names. Does not test hardware execution |
ha-ctk cdi remove |
Removes the specification |
ha-ctk runtime configure |
Writes runtime configuration files. Does not restart services |
ha-ctk daemon |
Runs on Kubernetes nodes and regenerates the specification. Started by the operator |
Troubleshooting¶
If /dev/ha* is missing inside the container or you see unresolvable CDI devices hyperaccel.ai/lpu=0, check in this order:
1 2 3 4 | |
If step 1 fails, the problem is with the driver, not the toolkit. See the table in Quick install.
If the specification is missing or the card configuration has changed, run sudo ha-ctk cdi generate and check again.
Then check the configuration, client version, and specification search paths for the selected runtime path, and rerun the SDK verification.