Usage on the Containerd Client

Usage Instruction

Before using Ascend Docker Runtime on the Containerd client, you need to check the current cgroup version. Run the stat -fc %T /sys/fs/cgroup/ command. If tmpfs is displayed, cgroup v1 is used. If cgroup2fs is displayed, cgroup v2 is used.
Ascend Docker Runtime supports both physical and virtual processors. Before mounting a virtual processor, virtualize the corresponding physical processor statically or dynamically by referring to Creating vNPUs.
You can run the ls /dev/davinci* and ls /dev/vdavinci* commands to query the IDs of available physical and virtual processors, respectively.
If you do not need to mount all content in the default configuration file /etc/ascend-docker-runtime.d/base.list of Ascend Docker Runtime, you can create a custom configuration file (for example, hostlog.list) to reduce the content to be mounted. For details, see (Optional) Configuring Custom Mounted Content.

Usage Examples

In the following examples, image-name:tag indicates the image name and tag, for example, ascend-tensorflow:tensorflow_TAG. containerID indicates the container ID. If you use the ctr command to start a container, you need to specify the container ID, for example, c1.

Example 1: Mount a processor whose physical processor ID is 0 when starting a container.

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=0 image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=0 image-name:tag containerID bash

Example 2: Mount only NPU and management devices when starting a container. Do not mount driver-related directories.

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_RUNTIME_OPTIONS=NODRV image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_RUNTIME_OPTIONS=NODRV image-name:tag containerID bash

Example 3: Mount a processor whose physical processor ID is 0 and read the mounted content of the custom configuration file hostlog when starting a container.

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_RUNTIME_MOUNTS=hostlog image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_RUNTIME_MOUNTS=hostlog image-name:tag containerID bash

Example 4: Mount a processor whose virtual processor ID is 100 when starting a container.

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=100 --env ASCEND_RUNTIME_OPTIONS=VIRTUAL image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=100 --env ASCEND_RUNTIME_OPTIONS=VIRTUAL image-name:tag containerID bash

Example 5: Split four AI Cores from a processor whose physical processor ID is 0 as virtual devices and mount them to a container when starting the container.

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_VNPU_SPECS=vir04 image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=0 --env ASCEND_VNPU_SPECS=vir04 image-name:tag containerID bash

Example 6: Mount a processor whose physical processor ID is 0 and allow for soft links in the mounted driver file when starting a container (applicable only to the Atlas 500 A2 edge station, Atlas 200I A2 accelerator module, and Atlas 200I DK A2 developer kit).

cgroup v1

ctr run --runtime io.containerd.runtime.v1.linux -t --env ASCEND_VISIBLE_DEVICES=0 -e ASCEND_ALLOW_LINK=True image-name:tag containerID bash

cgroup v2

ctr run --runtime io.containerd.runc.v2 --runc-binary /usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime -t --env ASCEND_VISIBLE_DEVICES=0 -e ASCEND_ALLOW_LINK=True image-name:tag containerID bash

For details about the parameters in the startup command, see Table 1.

After a container is started, check whether related devices and drivers are successfully mounted. For details about the mounted directory of each model, see Default Content Mounted by Ascend Docker Runtime. Example command:

ls /dev | grep davinci* && ls /dev | grep devmm_svm && ls /dev | grep hisi_hdc && ls /usr/local/Ascend/driver && ls /usr/local/ |grep dcmi && ls /usr/local/bin

Do not repeatedly define or fix environment variables such as ASCEND_VISIBLE_DEVICES, ASCEND_RUNTIME_OPTIONS, ASCEND_RUNTIME_MOUNTS, and ASCEND_VNPU_SPECS in the container image.

**Table 1** Ascend Docker Runtime parameters
Parameter	Description	Example
ASCEND_VISIBLE_DEVICES	If a task does not need to use NPU devices, set ASCEND_VISIBLE_DEVICES to void or leave it empty. If a task requires an NPU device, use ASCEND_VISIBLE_DEVICES to specify the NPU device to be mounted to the container. Otherwise, the NPU device fails to be mounted. If the device ID is used to specify a device, you can specify only one device or multiple devices at a time. If the processor ID is used to specify a device, you can specify multiple processors of the same type at a time.	ASCEND_VISIBLE_DEVICES=void indicates that the mounting function of Ascend Docker Runtime is not used and the NPU device, driver, and file directory are not mounted. Related mounting parameters also become invalid. Physical processors (NPUs) ASCEND_VISIBLE_DEVICES=0 indicates that NPU device 0 (/dev/davinci0) is mounted to the container. ASCEND_VISIBLE_DEVICES=1,3 indicates that NPU devices 1 and 3 are mounted to the container. ASCEND_VISIBLE_DEVICES=0-2 indicates that NPU devices 0 to 2 (including devices 0 and 2) are mounted to the container. The effect is the same as that of -e ASCEND_VISIBLE_DEVICES=0,1,2. ASCEND_VISIBLE_DEVICES=0-2,4 indicates that NPU devices 0 to 2 and device 4 are mounted to the container. The effect is the same as that of -e ASCEND_VISIBLE_DEVICES=0,1,2,4. ASCEND_VISIBLE_DEVICES=AscendXXX-Y: XXX indicates the NPU model. The value can be 910, 310, 310B, or 310P. Y indicates the NPU device ID. ASCEND_VISIBLE_DEVICES=Ascend910-1 indicates that NPU device 1 is mounted to the container. ASCEND_VISIBLE_DEVICES=Ascend910-1,Ascend910-3 indicates that NPU devices 1 and 3 are mounted to the container. NOTE: The NPU type must be the same as that used in the actual environment. Otherwise, the mounting fails. You cannot specify both the device ID and NPU in a parameter. That is, ASCEND_VISIBLE_DEVICES=0, Ascend910-1 is not supported. Virtual processors (vNPUs) Static virtualization: The mounting method is the same as that of physical processors. You only need to replace physical processor IDs with virtual processor IDs (vNPU IDs). Dynamic virtualization: ASCEND_VISIBLE_DEVICES=0 indicates that a certain number of AI Cores are allocated from NPU device 0. NOTE: A dynamic virtualization command can specify only one physical NPU ID for dynamic virtualization. It must be used together with ASCEND_VNPU_SPECS, to specify the number of AI Cores split on a specified NPU. It can be used together with ASCEND_RUNTIME_OPTIONS, but the value can only be NODRV, indicating that driver-related directories are not mounted.
ASCEND_ALLOW_LINK	Specifies whether soft links are allowed in the mounted file or directory. This parameter needs to be specified in for the Atlas 500 A2 edge station, Atlas 200I A2 AI accelerator module, and Atlas 200I DK A2. NOTE: Other devices such as Atlas training product, Atlas A2 training product, and Atlas 200I SoC A1 core boards can use this parameter. However, this parameter does not need to be specified because their default mounted content does not contain soft links.	If ASCEND_ALLOW_LINK is set to True, driver files with soft links can be mounted in the Atlas 500 A2 edge station, Atlas 200I A2 AI accelerator module, and Atlas 200I DK A2. If ASCEND_ALLOW_LINK is set to False or this parameter is not specified, the Atlas 500 A2 edge station, Atlas 200I A2 AI accelerator module, and Atlas 200I DK A2 cannot use Ascend Docker Runtime.
ASCEND_RUNTIME_OPTIONS	Restricts the processor ID specified by ASCEND_VISIBLE_DEVICES. NODRV indicates that driver-related directories are not mounted. VIRTUAL indicates that the virtual processor is mounted. NODRV,VIRTUAL indicates that the virtual processor is mounted while driver-related directories are not mounted.	ASCEND_RUNTIME_OPTIONS=NODRV ASCEND_RUNTIME_OPTIONS=VIRTUAL ASCEND_RUNTIME_OPTIONS=NODRV,VIRTUAL
ASCEND_RUNTIME_MOUNTS	Name of the configuration file with content to be mounted. You can configure the files and directories to be mounted to the container in this file.	ASCEND_RUNTIME_MOUNTS=base ASCEND_RUNTIME_MOUNTS=hostlog ASCEND_RUNTIME_MOUNTS=hostlog,hostlog1,hostlog2 NOTE: By default, the /etc/ascend-docker-runtime.d/base.list configuration file is read. Change hostlog.list to the actual configuration file name. Multiple custom configuration files can be read. The file name must be in lowercase. Uppercase letters are not allowed.
ASCEND_VNPU_SPECS	Splits a certain number of AI Cores from a physical NPU device and specifies them as virtual devices. The following values are supported: vir01, vir02, vir02_1c, vir04, vir04_3c, vir04_4c_dvpp, and vir04_3c_ndvpp for Atlas inference product vir02, vir04, vir08, and vir16 for Atlas training product This parameter must be used together with ASCEND_VISIBLE_DEVICES that specifies the physical NPU device to be split.	ASCEND_VNPU_SPECS=vir04 indicates that four AI Cores are used as virtual devices and mounted to the container. NOTE: The number following vir indicates the number of AI Cores. The number before c indicates the number of AI CPUs. dvpp indicates that all digital vision pre-processing (DVPP) modules (VPC, VDEC, JPEGD, PNGD, VENC and JPEGE) are included during virtualization. ndvpp indicates that DVPP hardware resources are excluded during virtualization.

Parent topic: Containerization Feature Guide