DOCA BlueField-4 (BF4) deployment
Examples
- "I have a BlueField-4 and a BMC — how do I bring Grace up?" —
BMC-driven day-1, not the BF3 RShim/BFB path. Do not invent
credentials or skip media detach.
- "PLDM update finished but the NIC firmware did not move." —
treat it as a firmware-Task / activation failure, not a second
burn by default.
BlueField-3 or any other generation is not this skill. Name
doca-bf3-deployment and stop; do not read further or run commands.
Preparing a BlueField-4 host (answer from here)
- Platform: confirm it is BlueField-4 and that the BMC is reachable
out of band; compare
the Redfish firmware inventory with the release notes' targets.
- Version alignment: run the
doca-version four-source chain on the
host. Fixing any mismatch changes hardware state and follows
doca-hardware-safety.
- Safest first smoke test: read-only
doca_caps --list-devs, then one
shipped sample per doca-bare-metal-deployment. No firmware, mode or
reset change before that is green.
- Say it in the answer: every mutating step (PLDM firmware burn, ISO
reflash, power cycle, BMC reset) is routed through
doca-hardware-safety: pre-flight inventory, out-of-band access,
maintenance window, rollback, then apply and verify.
Instructions
Follow Loading order below. Open the tasks companion for BMC bring-up
and recover. Open the capabilities companion for the three install
methods and the BF4 safety overlay. Do not open every companion file.
⚠️ WARNING — irreversible hardware operations. This skill guides
operators through potentially destructive, irreversible BlueField-4
hardware operations: PLDM firmware burns, ISO reflashes, power
cycles, and BMC factory resets. These can brick firmware, corrupt
boot media, or cause production outages. Do not proceed without a
maintenance window and a tested rollback plan. Every mutating step is
governed by
doca-hardware-safety/SKILL.md, which
MUST be loaded alongside this skill before any destructive action.
Before executing any mutating step — PLDM firmware burn, ISO reflash,
power cycle, or BMC factory reset — the agent MUST show the exact
command and its blast radius (which device, what becomes unavailable,
whether it is reversible) and obtain the user's explicit confirmation
for that specific action. Never chain destructive steps or run them
speculatively as a side effect of another task.
Where to start: This skill is the bundle's deliberate in-bundle
home for day-1 platform bring-up of a BlueField-4 DPU via the
BMC — getting a powered-but-bare BF4 to "Grace OS installed,
firmware at the target level, ready to deploy a workload." It is the
upstream of the two application-deployment skills
(doca-container-deployment/SKILL.md
and
doca-bare-metal-deployment/SKILL.md):
those skills assume a working BlueField; this skill is how the
BlueField-4 GETS to working. If the user has a fresh BF4 and wants to
install the OS or update firmware, open the tasks companion and
start at ## configure. If the question is
what bring-up methods even exist and what is the contract for each,
start at the capabilities companion.
How to use this skill. Read this file, then search the companion file
for the ## <name> heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in doca-public-knowledge-map. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.
Scope note — BF4 day-1 is in scope. The bundle's
AGENTS.md ## Non-goals (bundle AGENTS.md#non-goals-questions-the-agent-should-recognize-and-refuse-politely)
item 7 lists the BlueField BSP / BFB / RShim / TMFIFO layer and the
BlueField BMC software as externally-productized. BlueField-4
day-1 bring-up via the BMC is in scope for this skill because day-1 has no other home in the bundle. The
carve-out is narrow: this skill teaches the documented BMC-driven
install and firmware-update FLOWS (the CLASS), routing every
mutating step through
doca-hardware-safety/SKILL.md for the
change-application meta-policy. It does NOT redefine that
meta-policy, and it does NOT cover BF3 (route to
doca-bf3-deployment), application launch, or library APIs.
When to load this skill
Load this skill when the user is doing hands-on day-1 bring-up of a
BlueField-4 via the BMC, or asking a cross-cutting BF4-bring-up
question that is not specific to a later application-deployment step.
Concretely:
- Installing the BlueField/DOCA bundle ISO onto the DPU (Grace) for
the first time, and choosing between the install methods — UEFI
HTTP Boot, PXE Boot, Redfish Virtual Media, or the DOCA Management
Service install path.
- Running the PLDM firmware-update flow across the BMC, NIC firmware
and the other platform components the PLDM package lists: pushing the
.fwpkg bundle through the
Redfish UpdateService multipart endpoint, monitoring the returned
Task, verifying pending images with pldmtool, and activating with
a power cycle.
- Installing a Grace Ubuntu image (with optional cloud-init via a
CIDATA-labelled config ISO) through Redfish Virtual Media, with
either local hosting on the BMC eMMC or remote hosting on an
HTTPS server.
- Reaching the DPU's OOB serial console (BMC SSH plus
obmc-console-client) to watch the installer or UEFI menus.
- Diagnosing a bring-up that is misbehaving — the ISO will not boot,
virtual media will not attach, a firmware Task hangs or reports an
Exception, a pending image never activates, cloud-init is ignored,
or the DPU is stuck in a boot loop because media was never detached.
- Cross-cutting questions: "HTTP Boot or Redfish Virtual Media — which
do I use, and when do I actually need PXE?", "how do I know the
firmware update actually took effect?", "the ISO landed but the
NIC firmware update sub-step seems to have failed — what now?".
Do not load this skill for BF3 bring-up (route to
doca-bf3-deployment); for running an application on an
already-working BlueField (route to
doca-container-deployment/SKILL.md
or
doca-bare-metal-deployment/SKILL.md);
for env preparation on the installed Grace OS such as hugepages /
pkg-config / devlink (use doca-setup/SKILL.md); for
the cross-cutting hardware-change meta-policy (route to
doca-hardware-safety/SKILL.md); or for
fleet-scale orchestrated provisioning (route via
doca-public-knowledge-map/SKILL.md).
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — the BF4 day-1 bring-up contract: the three OS
install methods (UEFI HTTP Boot, PXE Boot, Redfish Virtual Media)
and the Grace-Ubuntu-plus-cloud-init Virtual Media path; the PLDM
firmware-update surface across the platform firmware components;
the version-compatibility overlay on
doca-version/SKILL.md (the install and firmware
targets come from the public release notes, never from memory); the
bring-up error taxonomy (boot-source -> virtual-media-attach ->
firmware-Task -> activation -> cloud-init -> boot-loop); the
observability surface (the OOB console, the Redfish Task resource,
the Redfish FirmwareInventory, pldmtool GetFwParams, and the
installed-build check cat /etc/mlnx-release); and the safety
policy (an overlay on
doca-hardware-safety/SKILL.md: every
PLDM burn / ISO reflash / power cycle / BMC factory reset is a
MUTATING hardware op; never print a real password; always detach
virtual media to avoid boot loops; only public hosts for any
NVIDIA URL).
- the tasks companion — step-by-step workflows for the in-scope bring-up verbs:
configure, build (routing stub), modify (routing stub), run
(the three install methods plus the PLDM firmware-update flow plus
the Grace-Ubuntu cloud-init path, as ### sub-anchors), test
(the post-install / post-update verification sweep), debug (the
layered bring-up diagnosis), and the Deferred task verbs block
routing BF3 / application-launch / library-API / env-prep /
hardware-meta-policy / fleet questions out to their owning skills.
The skill assumes a BlueField-4 target where:
- the BMC is reachable out-of-band and the operator has BMC
credentials ({bmc-user} / {bmc-password}) they supply — never
invented here,
- the bundle ISO (and any Grace Ubuntu image / cloud-init config ISO)
is downloaded from the public NVIDIA download surface and hosted at
{iso-uri},
- the operator has read the target firmware and OS versions from the
public BlueField/DOCA release notes.
It does not cover installing DOCA tooling on the host — that path goes
through doca-setup/SKILL.md — and it does not cover
running a workload once Grace is up — those paths go through the two
application-deployment skills.
Loading order
- Read this skill first to confirm the user's question is in
scope (BF4 day-1 bring-up via the BMC; NOT BF3, NOT application
launch, NOT a library-API question, NOT the hardware-change
meta-policy itself).
- For the bring-up contract (the three install methods, the
Grace-Ubuntu cloud-init path, the PLDM firmware-update surface, the
version overlay, the bring-up error taxonomy, the observability
surface, and the BF4 safety overlay), see
the capabilities companion.
- For step-by-step workflows —
configure, build (routing
stub), modify (routing stub), run (with the three install
methods, the PLDM flow, and the Grace-Ubuntu cloud-init path as
### sub-anchors), test, debug, plus the Deferred task verbs
block — see the tasks companion.
- Load
doca-hardware-safety/SKILL.md
ALONGSIDE whenever the question reaches a mutating step (PLDM
firmware burn, ISO reflash, power cycle, BMC factory reset).
Related skills
doca-bf3-deployment/SKILL.md — BF3 RShim/BFB day-1.
doca-hardware-safety/SKILL.md — PLDM, reflash, power cycle.
doca-bare-metal-deployment/SKILL.md — launch after Grace is up.
doca-container-deployment/SKILL.md — service container after Grace is up.
doca-setup/SKILL.md — env prep on the installed Grace OS.
doca-version/SKILL.md — four-way version match.
doca-public-knowledge-map/SKILL.md — public docs and release notes.
1---2license: Apache-2.03name: doca-bf4-deployment4description: >5 WARNING: guides IRREVERSIBLE BlueField-4 hardware operations (PLDM6 firmware burns, ISO reflashes, power cycles, BMC factory resets); every7 mutating step is governed by doca-hardware-safety (window, rollback).8 BlueField-4 only: BlueField-3 bring-up is doca-bf3-deployment. Use this9 skill for BlueField-4 (BF4) day-1 platform10 bring-up from the BMC: installing the BlueField/DOCA bundle ISO onto11 the DPU (Grace, the Arm complex) over UEFI HTTP Boot, PXE, or Redfish12 Virtual Media; the PLDM platform-firmware update via the Redfish13 UpdateService and pldmtool; and a Grace14 Ubuntu image with optional cloud-init. Trigger on BlueField-4/BF415 bring-up phrasings even without "BF4": {bring up my new BlueField-4},16 {the BlueField ISO will not boot over HTTP from the BMC}, {attach BF417 virtual media via Redfish}, {BF4 firmware Task stuck at Running}, {prepare a BlueField-4 host: platform18 support, version alignment, safest first smoke test}. Route19 application launch and library APIs to other skills.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-bf4-deployment22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - bluefield-428 - deployment29compatibility: >30 No DOCA install is required to read this skill; it teaches the31 documented BlueField-4 BMC-driven bring-up flows (UEFI HTTP Boot,32 PXE, Redfish Virtual Media, PLDM firmware update). Executing the33 steps requires a BlueField-4 with an out-of-band-reachable BMC, a34 host or HTTP/HTTPS server to host the bundle ISO, and the target35 versions from the public BlueField/DOCA release notes.36 The validation steps require a live DOCA install.37---3839# DOCA BlueField-4 (BF4) deployment4041## Examples4243- **"I have a BlueField-4 and a BMC — how do I bring Grace up?"** —44 BMC-driven day-1, not the BF3 RShim/BFB path. Do not invent45 credentials or skip media detach.46- **"PLDM update finished but the NIC firmware did not move."** —47 treat it as a firmware-Task / activation failure, not a second48 burn by default.4950**BlueField-3 or any other generation is not this skill.** Name51`doca-bf3-deployment` and stop; do not read further or run commands.5253## Preparing a BlueField-4 host (answer from here)54551. **Platform:** confirm it is BlueField-4 and that the BMC is reachable56 out of band; compare57 the Redfish firmware inventory with the release notes' targets.582. **Version alignment:** run the `doca-version` four-source chain on the59 host. Fixing any mismatch changes hardware state and follows60 `doca-hardware-safety`.613. **Safest first smoke test:** read-only `doca_caps --list-devs`, then one62 shipped sample per `doca-bare-metal-deployment`. No firmware, mode or63 reset change before that is green.644. **Say it in the answer:** every mutating step (PLDM firmware burn, ISO65 reflash, power cycle, BMC reset) is routed through66 `doca-hardware-safety`: pre-flight inventory, out-of-band access,67 maintenance window, rollback, then apply and verify.6869## Instructions7071Follow Loading order below. Open the tasks companion for BMC bring-up72and recover. Open the capabilities companion for the three install73methods and the BF4 safety overlay. Do not open every companion file.7475> ⚠️ **WARNING — irreversible hardware operations.** This skill guides76> operators through potentially destructive, irreversible BlueField-477> hardware operations: PLDM firmware burns, ISO reflashes, power78> cycles, and BMC factory resets. These can brick firmware, corrupt79> boot media, or cause production outages. Do **not** proceed without a80> maintenance window and a tested rollback plan. Every mutating step is81> governed by82> `doca-hardware-safety/SKILL.md`, which83> MUST be loaded alongside this skill before any destructive action.84>85> Before executing any mutating step — PLDM firmware burn, ISO reflash,86> power cycle, or BMC factory reset — the agent MUST show the exact87> command and its blast radius (which device, what becomes unavailable,88> whether it is reversible) and obtain the user's explicit confirmation89> for that specific action. Never chain destructive steps or run them90> speculatively as a side effect of another task.9192**Where to start:** This skill is the bundle's deliberate in-bundle93home for **day-1 platform bring-up of a BlueField-4 DPU via the94BMC** — getting a powered-but-bare BF4 to "Grace OS installed,95firmware at the target level, ready to deploy a workload." It is the96upstream of the two application-deployment skills97(`doca-container-deployment/SKILL.md`98and99`doca-bare-metal-deployment/SKILL.md`):100those skills assume a working BlueField; this skill is how the101BlueField-4 GETS to working. If the user has a fresh BF4 and wants to102install the OS or update firmware, open the tasks companion and103start at `## configure`. If the question is104*what bring-up methods even exist and what is the contract for each*,105start at the capabilities companion.106107**How to use this skill.** Read this file, then search the companion file108for the `## <name>` heading the question needs and read that whole section.109Answer completely from it, quoting only its symbols and commands. Do not110browse docs; use the entry points in `doca-public-knowledge-map`. Give111environment checks as commands for the user's DOCA host. For out-of-scope112requests, name the skill that owns them and stop.113114> **Scope note — BF4 day-1 is in scope.** The bundle's115> `AGENTS.md ## Non-goals` (bundle `AGENTS.md#non-goals-questions-the-agent-should-recognize-and-refuse-politely`)116> item 7 lists the BlueField BSP / BFB / RShim / TMFIFO layer and the117> BlueField BMC software as externally-productized. **BlueField-4118> day-1 bring-up via the BMC is in scope for this skill** because day-1 has no other home in the bundle. The119> carve-out is narrow: this skill teaches the documented BMC-driven120> install and firmware-update FLOWS (the CLASS), routing every121> *mutating* step through122> `doca-hardware-safety/SKILL.md` for the123> change-application meta-policy. It does NOT redefine that124> meta-policy, and it does NOT cover BF3 (route to125> `doca-bf3-deployment`), application launch, or library APIs.126127## When to load this skill128129Load this skill when the user is doing **hands-on day-1 bring-up of a130BlueField-4 via the BMC**, or asking a cross-cutting BF4-bring-up131question that is not specific to a later application-deployment step.132Concretely:133134- Installing the BlueField/DOCA bundle ISO onto the DPU (Grace) for135 the first time, and choosing between the install methods — UEFI136 HTTP Boot, PXE Boot, Redfish Virtual Media, or the DOCA Management137 Service install path.138- Running the PLDM firmware-update flow across the BMC, NIC firmware139 and the other platform components the PLDM package lists: pushing the `.fwpkg` bundle through the140 Redfish UpdateService multipart endpoint, monitoring the returned141 Task, verifying pending images with `pldmtool`, and activating with142 a power cycle.143- Installing a Grace Ubuntu image (with optional cloud-init via a144 CIDATA-labelled config ISO) through Redfish Virtual Media, with145 either local hosting on the BMC eMMC or remote hosting on an146 HTTPS server.147- Reaching the DPU's OOB serial console (BMC SSH plus148 `obmc-console-client`) to watch the installer or UEFI menus.149- Diagnosing a bring-up that is misbehaving — the ISO will not boot,150 virtual media will not attach, a firmware Task hangs or reports an151 Exception, a pending image never activates, cloud-init is ignored,152 or the DPU is stuck in a boot loop because media was never detached.153- Cross-cutting questions: *"HTTP Boot or Redfish Virtual Media — which154 do I use, and when do I actually need PXE?"*, *"how do I know the155 firmware update actually took effect?"*, *"the ISO landed but the156 NIC firmware update sub-step seems to have failed — what now?"*.157158Do **not** load this skill for BF3 bring-up (route to159`doca-bf3-deployment`); for running an application on an160already-working BlueField (route to161`doca-container-deployment/SKILL.md`162or163`doca-bare-metal-deployment/SKILL.md`);164for env preparation on the installed Grace OS such as hugepages /165pkg-config / devlink (use `doca-setup/SKILL.md`); for166the cross-cutting hardware-change meta-policy (route to167`doca-hardware-safety/SKILL.md`); or for168fleet-scale orchestrated provisioning (route via169`doca-public-knowledge-map/SKILL.md`).170171## What this skill provides172173This is a **thin loader**. Substantive material lives in two174companion files:175176- the capabilities companion — the BF4 day-1 bring-up contract: the three OS177 install methods (UEFI HTTP Boot, PXE Boot, Redfish Virtual Media)178 and the Grace-Ubuntu-plus-cloud-init Virtual Media path; the PLDM179 firmware-update surface across the platform firmware components;180 the version-compatibility overlay on181 `doca-version/SKILL.md` (the install and firmware182 targets come from the public release notes, never from memory); the183 bring-up error taxonomy (boot-source -> virtual-media-attach ->184 firmware-Task -> activation -> cloud-init -> boot-loop); the185 observability surface (the OOB console, the Redfish Task resource,186 the Redfish FirmwareInventory, `pldmtool` GetFwParams, and the187 installed-build check `cat /etc/mlnx-release`); and the safety188 policy (an overlay on189 `doca-hardware-safety/SKILL.md`: every190 PLDM burn / ISO reflash / power cycle / BMC factory reset is a191 MUTATING hardware op; never print a real password; always detach192 virtual media to avoid boot loops; only public hosts for any193 NVIDIA URL).194- the tasks companion — step-by-step workflows for the in-scope bring-up verbs:195 `configure`, `build` (routing stub), `modify` (routing stub), `run`196 (the three install methods plus the PLDM firmware-update flow plus197 the Grace-Ubuntu cloud-init path, as `###` sub-anchors), `test`198 (the post-install / post-update verification sweep), `debug` (the199 layered bring-up diagnosis), and the `Deferred task verbs` block200 routing BF3 / application-launch / library-API / env-prep /201 hardware-meta-policy / fleet questions out to their owning skills.202203The skill assumes a BlueField-4 target where:204205- the BMC is reachable out-of-band and the operator has BMC206 credentials ({bmc-user} / {bmc-password}) they supply — never207 invented here,208- the bundle ISO (and any Grace Ubuntu image / cloud-init config ISO)209 is downloaded from the public NVIDIA download surface and hosted at210 {iso-uri},211- the operator has read the target firmware and OS versions from the212 public BlueField/DOCA release notes.213214It does not cover installing DOCA tooling on the host — that path goes215through `doca-setup/SKILL.md` — and it does not cover216running a workload once Grace is up — those paths go through the two217application-deployment skills.218219## Loading order2202211. Read this skill first to confirm the user's question is in222 scope (BF4 day-1 bring-up via the BMC; NOT BF3, NOT application223 launch, NOT a library-API question, NOT the hardware-change224 meta-policy itself).2252. **For the bring-up contract (the three install methods, the226 Grace-Ubuntu cloud-init path, the PLDM firmware-update surface, the227 version overlay, the bring-up error taxonomy, the observability228 surface, and the BF4 safety overlay), see229 the capabilities companion.**2303. **For step-by-step workflows — `configure`, `build` (routing231 stub), `modify` (routing stub), `run` (with the three install232 methods, the PLDM flow, and the Grace-Ubuntu cloud-init path as233 `###` sub-anchors), `test`, `debug`, plus the `Deferred task verbs`234 block — see the tasks companion.**2354. **Load236 `doca-hardware-safety/SKILL.md`237 ALONGSIDE** whenever the question reaches a mutating step (PLDM238 firmware burn, ISO reflash, power cycle, BMC factory reset).239240## Related skills241242- `doca-bf3-deployment/SKILL.md` — BF3 RShim/BFB day-1.243- `doca-hardware-safety/SKILL.md` — PLDM, reflash, power cycle.244- `doca-bare-metal-deployment/SKILL.md` — launch after Grace is up.245- `doca-container-deployment/SKILL.md` — service container after Grace is up.246- `doca-setup/SKILL.md` — env prep on the installed Grace OS.247- `doca-version/SKILL.md` — four-way version match.248- `doca-public-knowledge-map/SKILL.md` — public docs and release notes.