doca-bf4-deployment

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• details.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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)

1. **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.
2. **Version alignment:** run the `doca-version` four-source chain on the
   host. Fixing any mismatch changes hardware state and follows
   `doca-hardware-safety`.
3. **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.
4. **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 by directive.** 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 carved into scope for this skill by
> directive** 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 three documented install
  methods — UEFI HTTP Boot (recommended), PXE Boot, or Redfish
  Virtual Media.
- Running the PLDM firmware-update flow across the BMC / NIC firmware
  / SBIOS / ERoT components: 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?"*.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills