/doca-bf4-deployment

license: Apache-2.0
name: doca-bf4-deployment
description: >
  WARNING: guides IRREVERSIBLE BlueField-4 hardware operations (PLDM
  firmware burns, ISO reflashes, power cycles, BMC factory resets); every
  mutating step is governed by doca-hardware-safety (window, rollback).
  BlueField-4 only: BlueField-3 bring-up is doca-bf3-deployment. Use this
  skill for BlueField-4 (BF4) day-1 platform
  bring-up from the BMC: installing the BlueField/DOCA bundle ISO onto
  the DPU (Grace, the Arm complex) over UEFI HTTP Boot, PXE, or Redfish
  Virtual Media; the PLDM platform-firmware update via the Redfish
  UpdateService and pldmtool; and a Grace
  Ubuntu image with optional cloud-init. Trigger on BlueField-4/BF4
  bring-up phrasings even without "BF4": {bring up my new BlueField-4},
  {the BlueField ISO will not boot over HTTP from the BMC}, {attach BF4
  virtual media via Redfish}, {BF4 firmware Task stuck at Running}, {prepare a BlueField-4 host: platform
  support, version alignment, safest first smoke test}. Route
  application launch and library APIs to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - bluefield-4
    - deployment
compatibility: >
  No DOCA install is required to read this skill; it teaches the
  documented BlueField-4 BMC-driven bring-up flows (UEFI HTTP Boot,
  PXE, Redfish Virtual Media, PLDM firmware update). Executing the
  steps requires a BlueField-4 with an out-of-band-reachable BMC, a
  host or HTTP/HTTPS server to host the bundle ISO, and the target
  versions from the public BlueField/DOCA release notes.
  The validation steps require a live DOCA install.

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.** 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-p