doca-bare-metal-deployment — скилл для Claude Code
Скилл doca-bare-metal-deployment для Claude Code помогает запускать DOCA-приложения на x86-хосте с BlueField NIC или на BlueField Arm без контейнеров и диагностировать сбои старта.
Apache-2.0 158 установок ★ 4 106 обновлён 2026-10-23
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a claude-codeЧто делает doca-bare-metal-deployment
Когда DOCA-приложение падает с кодом 1 сразу после запуска, не находит устройство на BlueField или systemd его зацикливает перезагрузками — это в области действия скилла. Он охватывает привязку к PCI-функциям, NUMA-узлам и CPU-наборам, настройку изоляции между процессами через cgroup-v2 и пространства имён, семиуровневую таксономию ошибок на железе и полный цикл жизни BlueField от установки BFB до восстановления после сбоя.
Скилл работает с двумя путями: хост x86 с DOCA-установкой, разговаривающий с BlueField NIC через PCIe, или BlueField Arm с DOCA на самом процессоре. Для прямого запуска, tmux-сессий, systemd-юнитов и надзора за рестартами — это дорога сюда. Деструктивные операции вроде прошивки или mlxconfig set требуют явного подтверждения через отдельный скилл doca-hardware-safety; сборку, подготовку окружения и API-библиотеки покрывают другие скиллы.
Если вы новичок в DOCA без железа — ищите doca-setup. Если нужен контейнерный путь под kubelet — там отдельный скилл. Масштабное развёртывание на флот серверов выходит за границы этого скилла.
Какие задачи решает
- Запустить DOCA-приложение на хосте с BlueField NIC через PCIe
- Привязать процесс к нужной PCI-функции, NUMA-узлу и CPU-набору без ошибок
- Диагностировать падение приложения сразу после старта или постоянные рестарты
- Изолировать несколько DOCA-процессов на одном BlueField через cgroup и netns
- Восстановить BlueField после сбоя установки BFB или проблем с RShim
Примеры запросов агенту
- Запусти DOCA-приложение в foreground на хосте, привязав его к первой PCI-функции BlueField
- Настрой systemd-юнит для DOCA-сервиса с автоперезагрузкой и привязкой к NUMA-узлу 1
- Диагностируй, почему приложение падает с ошибкой «no matching device on the BF» на Arm-ядрах BlueField
Как установить doca-bare-metal-deployment
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a claude-code2Вручную: положить файлы
~/.claude/skills/doca-bare-metal-deployment/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/doca-bare-metal-deployment/
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a codex2Вручную: положить файлы
.agents/skills/doca-bare-metal-deployment/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a cursor2Вручную: положить файлы
.cursor/skills/doca-bare-metal-deployment/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-bare-metal-deployment2Вручную: положить файлы
.github/skills/doca-bare-metal-deployment/SKILL.md1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a gemini-cli2Командой платформы
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-bare-metal-deploymentВручную: положить файлы
.devin/skills/doca-bare-metal-deployment/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о doca-bare-metal-deployment
Как установить doca-bare-metal-deployment в Claude Code?
Запусти npx skills add NVIDIA/skills --skill doca-bare-metal-deployment -a claude-code, затем открой ~/.claude/skills/doca-bare-metal-deployment/SKILL.md.
Что делает doca-bare-metal-deployment?
Учит запускать DOCA-приложения прямо на железе без контейнеров: правильно привязывать процессы к устройствам, диагностировать сбои при старте, настраивать изоляцию между процессами и восстанавливать BlueField после сбоев.
Какая разница между запуском DOCA в контейнере и на bare-metal?
Bare-metal — это прямой запуск на Arm-ядрах BlueField или на хосте x86 без kubelet и статик-подов. Требует ручной привязки к устройствам, NUMA-узлам и CPU, но даёт больше контроля над ресурсами и изоляцией.
Исходный текст
SKILL.md · Apache-2.0
--- license: Apache-2.0 name: doca-bare-metal-deployment description: > Running a DOCA-linked binary directly on the hardware, with no container or kubelet: on host x86 with a BlueField NIC over PCIe, or bare-metal on BlueField Arm. Use this skill for launching and supervising it (direct, tmux, systemd), and when it "exits 1 right after launch", "systemd keeps restarting it", reports "no matching device on the BF", or the BlueField itself is unhealthy: "bfb-install exited 0 but DPU is dead", "ping 192.168.100.2 works but ssh fails", "host PFs aren't showing netdevs". Refuse service containers under kubelet (doca-container-deployment). Covers PCI/NUMA/CPU/IRQ binding, co-tenant isolation (cgroup-v2/netns/numactl), a seven-layer error taxonomy, platform lifecycle (BFB install, RShim/TMFIFO, host PF rebind, post-BFB recovery) and a six-state BlueField lifecycle classifier. Destructive firmware burn / mlxconfig set requires explicit confirmation via doca-hardware-safety; library APIs, env prep, and build use other skills. metadata: author: NVIDIA <[email protected]> kind: library doca_version: "3.5" tags: - doca - deployment - bare-metal compatibility: > No DOCA install required to read this skill (it is an overlay loaded against any DOCA artifact skill); the validation steps within this skill require a live DOCA install at /opt/mellanox/doca on a host or BlueField with a built DOCA-linked binary. --- # DOCA bare-metal deployment ## Examples - **"The binary exits 1 right after launch."** — this is in scope. Treat it as a launch / device-bind / isolation failure before rewriting application code. - **"systemd keeps restarting my DOCA app."** — a restart loop on hardware is high-stakes. Debug the first exit before enabling Restart=always. ## Instructions Follow Loading order below. Open the tasks companion for launch / supervise / recover, and the capabilities companion for the runtime contract. Do not open every companion file. **Where to start:** This skill is the bundle's home for *operating* a DOCA-linked application binary **directly on hardware** — no container, no kubelet, no static-pod manifest. It is the parallel of `doca-container-deployment/SKILL.md` for the non-container path. If the user has a DOCA-linked binary they built (per the canonical workflow in `doca-programming-guide/SKILL.md`) and they want to know *how to actually run it on the host or on the BlueField Arm cores correctly*, open the tasks companion and start at `## configure`. If the question is *what shape does the bare-metal runtime even have and what is the deployment contract*, start at the capabilities companion. If the user is not yet sure whether their target system shape is the container path or the bare-metal path, route the recognition step to `doca-setup/SKILL.md` first; only return here once *bare-metal* is the confirmed shape. ## Audience This skill serves **external DOCA developers and operators who have a DOCA-linked application binary they built and want to run it directly on hardware** — i.e., people who already have: - a DOCA-linked application binary they built per `doca-programming-guide ## build`, - a real BlueField NIC and a host that talks to it (the **host x86** path — DOCA host install on the host talks to the BlueField NIC over PCIe), OR a BlueField with a console or SSH to the Arm side (the **BlueField Arm bare-metal** path — DOCA installed on the DPU Arm cores; the binary runs there directly), and - a desire to RUN that binary directly on the hardware, not inside a kubelet-standalone-managed container. It is **not** for: - kernel-driver developers contributing to `mlx5_*` or the BlueField OS, - DOCA library contributors (library changes are outside the scope of a bare-metal deployment), - full-Kubernetes-cluster operators managing a fleet of BlueFields (the bundle covers `doca-container-deployment/SKILL.md` for the single-host kubelet-standalone shape; **fleet/production-scale deployment is fleet-orchestration scope** — route to the orchestration entry-point in `doca-public-knowledge-map ## Deploying DOCA services at scale` (DPF / Network Operator / Launch Kit), not hand-rolled static-pod loops), - fresh-laptop-no-hardware users with no DOCA install yet — those belong on `doca-setup ## no-install`. The skill teaches the agent the bare-metal-deployment *procedure* and the rules for quoting documented commands from the public DOCA Programming Guide and the public BlueField / DPU User Manual via `doca-public-knowledge-map/SKILL.md`; it does not invent flag names, PCI BDFs, NUMA numbers, devlink paths, representor strings, or systemd `Restart=` mode names from memory. ## When to load this skill Load this skill when the user is doing **hands-on bare-metal deployment of a DOCA-linked application binary** on either of the two supported host modes (host x86 or BlueField Arm), or asking a cross-cutting bare-metal question that is not specific to one library's API. Concretely: - Launching a DOCA-linked binary for the first time on a host with a BlueField NIC in a PCIe slot, with DOCA installed on the host. - Launching a DOCA-linked binary on the BlueField Arm cores directly (BlueField Arm bare-metal mode), with DOCA installed on the Arm side per the BlueField OS image. - Deciding which launch mode to use (direct foreground for interactive debug; tmux/screen for long-running with manual reattach; systemd-supervised for restart-after-reboot, journald-integrated logs, and Restart= policy). - Binding the DOCA process to the right PCIe function, the right representor, the right NUMA node, and the right CPU set — and pinning IRQs to match — without inventing the addresses or the flag names. - Setting up per-tenant isolation (cgroup-v2 cpu / memory / io controllers, network namespaces for multi-tenant deployments, `numactl` / `taskset` for CPU + NUMA binding) so multiple DOCA processes co-tenant on the same BlueField without crushing each other. - Diagnosing a bare-metal launch that is misbehaving — won't start, starts and exits immediately, runs but can't find the device, attaches to the device but the workload errors, OOMs or is signal-killed, is in a restart loop under a supervisor, or is being interfered with by a co-tenant. - Cross-cutting questions: *"should I run this in tmux or as a systemd unit"*, *"what is the smoke-before-bulk loop for a binary on bare metal"*, *"my binary works in a container on the BlueField but not when I run it directly on the Arm — what changed"*. Do **not** load this skill for the container-path equivalent (those questions go to `doca-container-deployment/SKILL.md`); for full-Kubernetes-cluster operations (out of scope per the bundle's non-goals); for library-API questions (route to the matching `libs/<library>` skill); for env-preparation questions including hugepages, IOMMU, pkg-config, and devlink mode flips (use `doca-setup/SKILL.md`); for any hardware-state-changing operation including `mlxconfig` writes and BFB reflashes (route to `doca-hardware-safety/SKILL.md` for the cross-cutting meta-policy); or for cross-library programming questions (use `doca-programming-guide/SKILL.md`). ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - the capabilities companion — the bare-metal deployment runtime contract for a DOCA-linked binary: the two host modes (host x86 vs BlueField Arm bare-metal), the three launch modes (direct, tmux/screen, systemd-supervised), the hardware-resource-binding surface (PF / VF / representor enumeration; NUMA topology discovery; CPU pinning rationale; IRQ affinity rules), the per-tenant isolation surface (cgroup-v2 cpu / memory / io, network namespaces, `numactl` / `taskset`), the restart and recovery semantics (documented `systemd` `Restart=` modes vs crash-and-investigate vs supervisor-driven restart), the bare-metal-specific version overlay on the four-way version match owned by `doca-version/SKILL.md`, the cross-cutting error taxonomy (seven layers, walked in order), the observability surface (stdout/stderr discipline by launch mode; device-state introspection via `devlink` / `sysfs` / `mlxconfig` *query*; per-tenant resource visibility), and the safety policy (overlay on `doca-hardware-safety/SKILL.md`: smoke-before-bulk for binaries; failed bare-metal process is HIGH-STAKES; do not invent PCI addresses, NUMA numbers, representor names, devlink paths, or systemd `Restart=` mode names; confirm tenant-isolation primitives BEFORE the workload starts). - the tasks companion — step-by-step workflows for the in-scope bare-metal verbs: `configure`, `build`, `modify`, `run` (with an explicit `### isolation` sub-anchor covering cgroup-v2 / namespaces / numactl per-tenant primitives), `test`, `debug`, `bluefield-lifecycle` (the BFB-install → RShim/TMFIFO → post-BFB-recovery operational sequencing ladder, with the six-state `bluefield-state-classifier` sub-anchor), the `Command appendix` (documented commands the agent may quote, each cross-linked to its public-doc source — no invented commands), and the `Deferred task verbs` block routing container-path / cluster / library-API / env-prep / hardware-state-change / cross-library questions out to their owning skills. (The change-application discipline for any mutating burn invoked from `## bluefield-lifecycle` is still meta-policy owned by `doca-hardware-safety/SKILL.md`, loaded alongside.) The skill assumes a host or BlueField target where: - DOCA is already installed and healthy (per `doca-setup ## test`), - the user has a DOCA-linked application binary they built (per `doca-programming-guide ## build`), - the user has the host-OS permissions to enumerate devices, reserve hugepages, write systemd units (if they choose that launch mode), and bind processes to NUMA nodes. It does not cover installing DOCA — that path goes through `doca-setup/SKILL.md` — and it does not cover building the binary — that path goes through `doca-programming-guide/SKILL.md`. ## Loading order 1. Read this skill first to confirm the user's question is in scope (bare-metal launch of a DOCA-linked binary on host x86 or BlueField Arm; NOT the container path, NOT a full cluster, NOT a library-API question). 2. **For the runtime contract (two host modes, three launch modes, hardware-binding surface, per-tenant isolation, version overlay, seven-layer error taxonomy, observability surface, bare-metal safety overlay), see the capabilities companion.** 3. **For step-by-step workflows — `configure`, `build` (routing stub), `modify` (routing stub), `run` (with `### isolation` sub-anchor), `test`, `debug`, `bluefield-lifecycle` (BFB install + RShim/TMFIFO + post-BFB recovery + the six-state `bluefield-state-classifier`), plus the `Command appendix` and the `Deferred task verbs` block — see the tasks companion.** ## Example questions this skill answers well ## What this skill deliberately does not ship ## Related skills
© NVIDIA · Apache-2.0 · NVIDIA/skills