Using Ascend Docker Runtime in the Containerd Client

Usage Instructions

Ascend Docker Runtime supports mounting physical chips and virtual chips. Before mounting virtual chips, refer to the Creating vNPU section to virtualize physical chips. Both static virtualization and dynamic virtualization of physical chips are supported.
You can query the currently available physical chip IDs using the ls /dev/davinci* command, and query the currently available virtual chip IDs using the ls /dev/vdavinci* command.
If you do not need to mount all content from the default Ascend Docker Runtime configuration file "/etc/ascend-docker-runtime.d/base.list", you can create a custom configuration file (for example, hostlog.list) to reduce the mounted content. For details, refer to the (Optional) Configuring Custom Mounted Content section.

Usage Examples

The image-name:tag in the examples represents the image name and tag, such as "ascend-pytorch:pytorch_TAG". containerID is the container ID. When using ctr to start a container, you must specify a container ID, such as "c1".

Example 1: Mount the physical chip with chip ID 0 when starting the container.

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.

ctr run --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 the physical chip with chip ID 0 when starting the container, and read the mount content from the custom configuration file hostlog.

ctr run --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: When starting a container, mount the virtual chip with chip ID 100.

ctr run --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: When starting a container, slice 4 AICores from the physical chip with chip ID 0 as virtual devices and mount them into the container.

ctr run --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: When starting a container, mount the physical chip with chip ID 0, and allow soft links in the mounted driver files (applicable only to Atlas 500 A2 Intelligent Station, Atlas 200I A2 Acceleration Module, and Atlas 200I DK A2 Developer Kit).
```
ctr run --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
```

The parameters related to the startup command are shown in Table 1.

After the container is started, you can run the following commands to check whether the corresponding devices and drivers are mounted successfully. For the specific mount directories of each model, refer to Content Mounted by Ascend Docker Runtime. The command example is as follows:

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

Possible output results are as follows:

davinci0
davinci_manager
devmm_svm
hisi_hdc
include lib64
dcmi
npu-smi

During use, do not redefine 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 the job does not require an NPU device, you can set the ASCEND_VISIBLE_DEVICES environment variable to void or leave it empty. If the job requires an NPU device, you must use ASCEND_VISIBLE_DEVICES to specify the NPU device to be mounted into the container; otherwise, the NPU device mount will fail. When specifying devices by device index, single and range specifications are supported and can be mixed. When specifying devices by chip name, multiple chip names of the same type can be specified simultaneously.	ASCEND_VISIBLE_DEVICES=void indicates that the mount function of Ascend Docker Runtime is not used, and no NPU devices, drivers, or file directories are mounted. Related mount parameters will also become invalid. Mount Physical chip (NPU) ASCEND_VISIBLE_DEVICES=0 indicates that NPU device 0 (/dev/davinci0) is mounted into the container. ASCEND_VISIBLE_DEVICES=1,3 indicates that NPU devices 1 and 3 are mounted into the container. ASCEND_VISIBLE_DEVICES=0-2 indicates that NPU devices 0 through 2 (including 0 and 2) are mounted into the container, with the same effect as -e ASCEND_VISIBLE_DEVICES=0,1,2. ASCEND_VISIBLE_DEVICES=0-2,4 indicates that NPU devices 0 through 2 and device 4 are mounted into the container, with the same effect as -e ASCEND_VISIBLE_DEVICES=0,1,2,4. ASCEND_VISIBLE_DEVICES=XXX-Y, where XXX represents the NPU device, with supported values being npu, Ascend910, Ascend310, Ascend310B, and Ascend310P; Y represents the physical NPU device ID. ASCEND_VISIBLE_DEVICES=npu-1 indicates that NPU device 1 is mounted into the container. ASCEND_VISIBLE_DEVICES=npu-1,npu-3 indicates that NPU 1 and NPU 3 are mounted into the container. [!NOTE] Note When specifying devices by chip name, it is recommended to uniformly use the value npu. Specifying both a device index and an NPU name in a single parameter is not supported, i.e., ASCEND_VISIBLE_DEVICES=0,npu-1 is not supported. Mount Virtual chip (vNPU) Static virtualization: The usage is the same as for physical chips; simply replace the physical chip ID with the virtual chip ID (vNPU ID). Dynamic virtualization: ASCEND_VISIBLE_DEVICES=0 indicates that a certain number of AICores are partitioned from NPU device 0. [!NOTE] Note A single dynamic virtualization command can only specify the ID of one physical NPU for dynamic virtualization. Must be used together with ASCEND_VNPU_SPECS, which indicates the number of AICores partitioned on the specified NPU. 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	Whether to allow soft links in the mounted files or directories. This parameter needs to be specified in scenarios involving the Atlas 500 A2 Intelligent Station, Atlas 200I A2 AI Acceleration Module, and Atlas 200I DK A2 Developer Kit. Other devices, such as Atlas training series products, Atlas A2 training series products, and Atlas 200I SoC A1 core board, can use this parameter. However, because their default mount content does not contain soft links, there is no need to specify this parameter additionally.	ASCEND_ALLOW_LINK=True indicates that mounting driver files with soft links is allowed in scenarios involving the Atlas 500 A2 Intelligent Station, Atlas 200I A2 AI Acceleration Module, and Atlas 200I DK A2 Developer Kit. If ASCEND_ALLOW_LINK=False or this parameter is not specified, the Atlas 500 A2 Intelligent Station, Atlas 200I A2 AI Acceleration Module, and Atlas 200I DK A2 Developer Kit will be unable to use Ascend Docker Runtime.
ASCEND_RUNTIME_OPTIONS	Restricts the chip ID specified in the ASCEND_VISIBLE_DEVICES parameter: NODRV: Indicates that driver-related directories are not mounted. VIRTUAL: Indicates that the mounted chip is a virtual chip. NODRV,VIRTUAL: Indicates that the mounted chip is a virtual chip, and driver-related directories are not mounted.	ASCEND_RUNTIME_OPTIONS=NODRV ASCEND_RUNTIME_OPTIONS=VIRTUAL ASCEND_RUNTIME_OPTIONS=NODRV,VIRTUAL Note: In static virtualization scenarios, ASCEND_RUNTIME_OPTIONS is a mandatory parameter, and its value must include VIRTUAL. In dynamic virtualization scenarios, if the ASCEND_RUNTIME_OPTIONS parameter is used, its value cannot include VIRTUAL.
ASCEND_RUNTIME_MOUNTS	The configuration file name for the content to be mounted. This file can configure the files and directories to be mounted into the container.	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. For hostlog.list, modify it according to the actual custom configuration file name. Reading multiple custom configuration files is supported. File names must be lowercase and cannot contain uppercase letters.
ASCEND_VNPU_SPECS	Partitions a certain number of AICores from a physical NPU device and specifies them as a virtual device. For supported values, see the "Virtualization Instance Template" column in Table 1 of Virtualization Templates. This parameter can only be used for product forms that support dynamic virtualization. Must be used together with the "ASCEND_VISIBLE_DEVICES" parameter, which specifies the physical NPU device used for virtualization.	ASCEND_VNPU_SPECS=vir04 indicates that 4 AICores are partitioned as a virtual device and mounted into the container.