DOCA 文档 v2.10.0
NVIDIA 文档中心  NVIDIA 网络  BlueField DPU / SuperNIC 和 DOCA  DOCA 文档 v2.10.0  DOCA 容器部署指南

本页内容

DOCA 容器部署指南

本指南概述了 NVIDIA® BlueField® DPU 的 DOCA 容器的部署配置。

简介

DOCA 容器允许轻松地将现成的 DOCA 环境部署到 DPU，无论是捆绑在容器内并准备部署的 DOCA 服务，还是已经包含所需 DOCA 版本的开发环境。

容器化环境使用户能够将 DOCA 程序与底层 BlueField 软件分离。每个容器都预先构建了所有必要的库和配置，以匹配手头程序的特定 DOCA 版本。用户只需选择所需版本的服务，并从 NVIDIA 的容器目录中拉取该版本的现成容器。

containers-overview-version-1-modificationdate-1731512026317-api-v2.png

不同的 DOCA 容器在 NVIDIA 的容器目录 NGC 上列出，可以在 “DOCA” 和 “DPU” 标签下找到。

先决条件

  • 有关如何安装 BlueField 相关软件的详细信息，请参阅 DOCA Linux 安装指南

  • 所需的 BlueField 镜像版本为 3.9.0 及更高版本

注意

本指南中介绍的基于独立 Kubelet 的容器部署目前处于 alpha 版本，并且在未来版本中可能会发生更改。

容器部署

在 BlueField DPU 之上部署容器需要以下设置顺序

  1. 拉取容器 .yaml 配置文件。

  2. 修改容器的 .yaml 配置文件。

  3. 部署容器。镜像将自动从 NGC 拉取。

某些步骤只需执行一次，而另一些步骤则需要在每次部署容器之前执行。

以下是使用 DOCA Firefly 容器作为示例的总体设置顺序示例。

deployment-architecture-version-1-modificationdate-1731512025947-api-v2.png

拉取容器 YAML 配置

注意

此步骤从 NGC 拉取 .yaml 配置。如果您已为其他 DOCA 容器执行此步骤，则可以跳到下一节。

要拉取最新的资源版本

  1. 下载 NVIDIA NGC CLI。

  2. 拉取整个资源（最新版本）

    复制
    已复制！
                
    
            
    ngc registry resource download-version "nvidia/doca/doca_container_configs"

    信息

    有关其他版本的信息，请参阅 NGC 资源页面。

    信息

    有关 NGC CLI 的更多信息，请参阅NGC 目录用户指南。

特定于容器的说明

某些容器需要特定的配置步骤，用于容器内运行的应用程序使用的资源以及容器本身的 .yaml 配置文件的修改。

请参阅 NGC 上容器相关页面下列出的特定于容器的说明。

NGC 资源的结构

在 “拉取容器 YAML 配置” 节中下载的 DOCA NGC 资源包含一个 configs 目录，该目录下每个 DOCA 版本都有一个专用文件夹。例如，2.0.2 将包含所有当前可用的 DOCA 2.0.2 容器的 .yaml 配置文件。

复制
已复制！
            

            
doca_container_configs_2.0.2v1
├── configs
│   ├── 1.2.0
│   │   ...
│   └── 2.0.2
│       ├── doca_application_recognition.yaml
│       ├── doca_blueman.yaml
│       ├── doca_devel.yaml
│       ├── doca_devel_cuda.yaml
│       ├── doca_firefly.yaml
│       ├── doca_flow_inspector.yaml
│       ├── doca_hbn.yaml
│       ├── doca_ips.yaml
│       ├── doca_snap.yaml
│       ├── doca_telemetry.yaml
│       └── doca_url_filter.yaml

此外，该资源还包含一个 scripts 目录，服务可以选择在该目录下提供其他辅助脚本和配置文件，以便与其服务一起使用。

scripts 目录的文件夹结构如下

复制
已复制！
            

            
+ doca_container_configs_2.0.2v1
+-+ configs
| +--  ...
+-+ scripts
  +-+ doca_firefly               <== Name of DOCA Service
  +-+ doca_hbn                   <== Name of DOCA Service
  | +-+ 1.3.0
  | | +-- ...                    <== Files for the DOCA HBN version "1.3.0"
  | +-+ 1.4.0
  | | +-- ...                    <== Files for the DOCA HBN version "1.4.0"

希望部署旧版本 DOCA 服务的用户仍然可以访问合适的 YAML 文件（每个 DOCA 版本在 configs 下）和脚本（在特定于服务的版本文件夹下，该文件夹位于 scripts 下）。

启动容器

更新所需的 .yaml 文件后，只需将配置文件复制到 Kubelet 的输入文件夹即可。以下是使用 doca_firefly.yaml 的示例，该文件对应于 DOCA Firefly 服务。

复制
已复制！
            

            
cp doca_firefly.yaml /etc/kubelet.d

Kubelet 会自动从 NGC 拉取容器镜像并启动执行容器的 pod。在此示例中，DOCA Firelfy 服务立即开始执行，其打印输出将通过容器的日志看到。

查看容器部署

部署新容器时，建议遵循此过程以确保成功完成部署中的每个步骤

  1. 查看当前活动的 pod 及其 ID

    复制
    已复制！
                
    
            
    sudo crictl pods

    信息

    pod 可能需要长达 20 秒才能启动。

    部署新容器时，在命令的输出中搜索匹配的行

    复制
    已复制！
                
    
            
    POD ID              CREATED             STATE               NAME                                     NAMESPACE           ATTEMPT             RUNTIME
06bd84c07537e       4 seconds ago       Ready               doca-firefly-my-dpu                      default             0                   (default)

  2. 如果未出现匹配的行，建议查看 Kubelet 的日志以获取有关错误的更多信息

    复制
    已复制！
                
    
            
    sudo journalctl -u kubelet --since -5m

    解决问题后，继续执行下一步。

    信息

    有关更多故障排除信息和提示，请参阅我们的 故障排除指南中的匹配章节。

  3. 验证容器镜像是否已从 NGC 成功下载到 DPU 的容器注册表（下载时间可能因容器镜像的大小而异）

    复制
    已复制！
                
    
            
    sudo crictl images

    示例输出

    复制
    已复制！
                
    
            
    IMAGE                              TAG                 IMAGE ID            SIZE
k8s.gcr.io/pause                   3.9                 829e9de338bd5       268kB
nvcr.io/nvidia/doca/doca_firefly   1.1.0-doca2.0.2     134cb22f34611       87.4MB

  4. 查看当前活动的容器及其 ID

    复制
    已复制！
                
    
            
    sudo crictl ps

    再次，查找已部署容器的匹配行（启动时间可能因容器镜像大小而异）

    复制
    已复制！
                
    
            
    CONTAINER           IMAGE               CREATED             STATE               NAME                     ATTEMPT             POD ID              POD
b505a05b7dc23       134cb22f34611       4 minutes ago       Running             doca-firefly             0                   06bd84c07537e       doca-firefly-my-dpu

  5. 如果失败，要查看与容器匹配的行，请检查所有最近容器部署的列表

    复制
    已复制！
                
    
            
    sudo crictl ps -a

    容器可能在启动期间遇到错误并立即退出

    复制
    已复制！
                
    
            
    CONTAINER           IMAGE               CREATED             STATE               NAME                     ATTEMPT             POD ID              POD
de2361ec15b61       134cb22f34611       1 second ago        Exited              doca-firefly             1                   4aea5f5adc91d       doca-firefly-my-dpu

  6. 在容器的生命周期内，以及在容器退出后的短时间内，可以查看打印到标准输出的容器日志

    复制
    已复制！
                
    
            
    sudo crictl logs <container-id>

    在这种情况下，用户可以从日志中了解到传递给容器的配置错误

    复制
    已复制！
                
    
            
    $ sudo crictl logs de2361ec15b61
Starting DOCA Firefly - Version 1.1.0
...
Requested the following PTP interface: p10
Failed to find interface "p10". Aborting

信息

有关使用 crictl 的其他信息和指南，请参阅 Kubernetes 文档。


停止容器

停止 pod 及其容器的推荐方法如下

  1. 删除 Kubelet 的 .yaml 配置文件以停止 pod

    复制
    已复制！
                
    
            
    rm /etc/kubelet.d/<file name>.yaml

  2. 直接停止 pod（仅当它仍然显示 “Ready” 时）

    复制
    已复制！
                
    
            
    sudo crictl stopp <pod-id>

  3. pod 停止后，可能还需要停止容器本身

    复制
    已复制！
                
    
            
    sudo crictl stop <container-id>

常见错误故障排除

本节提供了一个常见错误列表，这些错误可能在启动容器时遇到。这些错误占了绝大多数部署错误，并且很容易首先验证，然后再尝试解析 Kubelet 日志。

信息

如果需要更多故障排除，请参阅 故障排除指南中的匹配章节。

Yaml 语法

.yaml 文件的语法非常敏感，细微的缩进更改可能会导致它停止工作。该文件使用空格 (' ') 进行缩进（每个缩进两个空格）。使用任何其他数量的空格都会导致未定义的行为。

巨页

只有在 DPU 上分配了所有必需的系统资源并且可以为容器保留这些资源后，容器才会启动。最值得注意的资源是巨页。

  1. 在部署容器之前，请确保

    1. 已根据每个容器的要求分配了巨页。

    2. 页面的数量和大小都与要求精确匹配。

  2. 分配巨页后，建议重新启动容器服务以应用更改

    复制
    已复制！
                
    
            
    sudo systemctl restart kubelet.service 
sudo systemctl restart containerd.service

  3. 完成上述操作后，可以部署容器（可以将 YAML 复制到 /etc/kubelet.d）。

高级故障排除

从容器内手动执行 - 调试

注意

本节中描述的部署需要深入了解容器的结构。由于此结构可能会因版本而异，因此仅建议将此部署用于调试，并且仅在尝试其他调试步骤之后使用。

尽管大多数容器将 entrypoint.sh 脚本定义为容器的 ENTRYPOINT，但此选项仅对无交互会话有效。在某些调试场景中，更好地控制容器内执行的程序（通过交互式 shell 会话）很有用。因此，.yaml 文件支持其他执行选项。

取消注释（即，从 .yaml 文件中的以下 2 行中删除 #）会导致容器在不启动容器的 entrypoint 脚本的情况下启动。

复制
已复制！
            

            
# command: ["sleep"]
# args: ["infinity"]

在此执行模式下，用户可以将 shell 附加到启动的容器

复制
已复制！
            

            
crictl exec -it <container-id> /bin/bash

附加后，用户将获得完整的 shell 会话，使他们能够在容器范围内直接执行内部程序。

воздушный 容器部署

BlueField DPU 上的容器部署可以在 воздушный 网络中完成，并且不需要 Internet 连接。如前所述，对于每个 DOCA 服务容器，成功部署需要 2 个组件

  • 容器镜像 – 托管在 NVIDIA 的 NGC 目录中

  • 容器的 YAML 文件

从基础设施的角度来看，还需要一个额外的模块

  • k8s.gcr.io/pause 容器镜像

拉取容器以进行离线部署

在准备 воздушный 环境时，用户必须提前拉取所需的容器镜像，以便可以将它们本地导入到目标机器

复制
已复制！
            

            
docker pull <container-image:tag>
docker save <container-image:tag> > <name>.tar

以下示例拉取 DOCA Firefly 1.1.0-doca2.0.2

复制
已复制！
            

            
docker pull nvcr.io/nvidia/doca/doca_firefly:1.1.0-doca2.0.2
docker save nvcr.io/nvidia/doca/doca_firefly:1.1.0-doca2.0.2 > firefly_v1.1.0.tar

注意

某些 DOCA 的容器镜像支持多种架构，导致 docker pull 命令根据调用它的机器的架构拉取镜像。用户可以通过传递 --platform 标志来强制操作拉取 Arm 镜像

复制
已复制！
            

            
docker pull --platform=linux/arm64 <container-image:tag>


导入容器镜像

从容器目录导出镜像后，用户必须将创建的 *.tar 文件放在要部署它们的目标机器上。导入命令如下

复制
已复制！
            

            
ctr --namespace k8s.io image import <name>.tar

例如，导入上一节中拉取的 firefly .tar 文件

复制
已复制！
            

            
ctr --namespace k8s.io image import firefly_v1.1.0.tar

可以使用镜像检查命令完成对操作状态的检查

复制
已复制！
            

            
crictl images


内置基础设施支持

DOCA 镜像预先附带了 k8s.gcr.io/pause 镜像

复制
已复制！
            

            
/opt/mellanox/doca/services/infrastructure/
├── docker_pause_3_9.tar
└── enable_offline_containers.sh

默认情况下，此镜像在启动期间作为 DOCA 遥测服务 (DTS) 自动激活的一部分导入。

注意

可以使用 enable_offline_container.sh 脚本独立于 DTS 导入镜像，该脚本与镜像的 *.tar 文件位于同一目录下。

也可以使用以下说明手动拉取和导入此镜像

  • 导出镜像

    复制
    已复制！
                
    
            
    docker pull k8s.gcr.io/pause:3.9
docker save k8s.gcr.io/pause:3.9 > docker_pause_3_9.tar

  • 导入镜像

    复制
    已复制！
                
    
            
    ctr --namespace k8s.io image import docker_pause_3_9.tar
crictl images
IMAGE                              TAG                 IMAGE ID            SIZE
k8s.gcr.io/pause                   3.9                 829e9de338bd5       268kB

用于主机的 DOCA 服务

DOCA 服务的子集也可用于基于主机的部署。这在这些服务的部署中已指明，也可以通过在 NGC 上带有 *-host 后缀的容器标签来识别。

与托管的 DPU 环境相比，主机上 DOCA 服务的部署基于 docker。此部署可以根据用户自己的容器运行时解决方案进一步扩展。

Docker 部署

用于主机的 DOCA 服务直接使用 Docker 部署。

  1. 确保您的主机上已安装 Docker。运行

    复制
    已复制！
                
    
            
    docker version

    如果未安装，请访问官方 安装 Docker Engine 网页以获取安装说明。

  2. 确保 Docker 服务已启动。运行

    复制
    已复制！
                
    
            
    sudo systemctl daemon-reload 
sudo systemctl start docker

  3. 直接从 NGC 拉取容器镜像（也可以使用 docker run 命令完成）

    1. 访问所需容器的 NGC 页面。

    2. 在 “Tags” 菜单下，选择所需的标签，然后单击粘贴图标，以便将其复制到剪贴板。

    3. docker pull 命令如下所示

      复制
      已复制！
                  
      
            
      sudo docker pull <NGC container tag here>

      例如

      复制
      已复制！
                  
      
            
      sudo docker pull nvcr.io/nvidia/doca/doca_firefly:1.1.0-doca2.0.2-host

      注意

      对于在 DPU 和主机上都有部署的 DOCA 服务，请确保选择以 -host 结尾的标签。

  4. 使用 Docker 部署 DOCA 服务

    1. 部署使用以下命令执行

      复制
      已复制！
                  
      
            
      sudo docker run --privileged --net=host -v <host directory>:<container directory> -e <env variables> -it <container tag> /entrypoint.sh

      信息

      有关更多信息，请参阅 Docker 官方文档。

    2. 每个 DOCA 服务的特定部署命令在其各自的部署指南中列出。
© 版权所有 2025 NVIDIA。 上次更新时间：2025 年 2 月 12 日。
此处内容