/doca-upgrade

license: Apache-2.0
name: doca-upgrade
description: >
  Changing DOCA versions safely: upgrading or downgrading the host DOCA
  packages, refreshing the BlueField BFB, bumping the NGC DOCA container
  tag, or rolling back, with the discipline detect -> report -> ASK ->
  only then a guided upgrade. Trigger on "is there a newer DOCA", "I want the newest DOCA
  features, can I just apt upgrade in place", "should I move to the
  next release", "the upgrade stopped midway and dpkg is in a broken
  state", "my component is being deprecated, what now", or "roll me back",
  even without the word upgrade. Detect what is installed, find the newer
  release, report the gap, then STOP and ask for explicit confirmation;
  never upgrade automatically. Do not use it for a runtime error on an
  unchanged install (doca-debug). Version detection alone belongs to
  doca-version, first-time install to doca-setup, any hardware / firmware
  / reboot step to doca-hardware-safety, and public-docs or sunset routing
  to doca-public-knowledge-map.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - upgrade
    - version
compatibility: >
  No DOCA install required to read this skill (it is a cross-cutting
  overlay loaded against any DOCA artifact skill); the detection,
  gap-report, and guided-upgrade steps within DO require a live DOCA
  install at /opt/mellanox/doca, and the hardware / firmware / reboot
  steps require a BlueField DPU or ConnectX NIC plus out-of-band
  console reachability as gated by doca-hardware-safety.

DOCA upgrade

Examples

• **"Should I move to the next DOCA release?"** — detect what is

installed, report the gap, then STOP and ask. Never auto-upgrade.

• **"apt upgrade drifted my DOCA packages."** — this is recovery,

not a silent repair. Detect, report, ask, then guide.

Quick answers (answer from this file)

• **Not changing versions** (a runtime error on the current, pinned

install)? This skill does not apply: name `doca-debug` and stop.

These two answers are complete here; open `TASKS.md` only for a guided upgrade after the user confirms. Run only the read-only detection commands yourself. Package commands (`sudo dpkg`, `apt`, `apt-get`) need root and change the system: give them to the user to run and stop; in an agent shell `sudo` waits for a password and the session stalls.

• **"Can I just `apt upgrade` to the next DOCA?"** Never upgrade

automatically. Detect the installed release with the `doca-version` four-source chain (`pkg-config --modversion doca-common`, `cat /opt/mellanox/doca/applications/VERSION`, `doca_caps --version`, and the BFB version on BlueField), report the gap to the target release, then STOP and ask for explicit confirmation. BFB, firmware or reboot steps follow `doca-hardware-safety`.

• **"The upgrade aborted half-way and dpkg reports an interrupted

transaction."** Recover the package database first: after the user explicitly confirms (both commands change system package state), the user runs `sudo dpkg --configure -a`, then `sudo apt-get -f install` (Debian/Ubuntu). Do not re-run the upgrade as the first action; re-detect the release with `doca-version` before deciding the next step.

Instructions

Follow Loading order below. Open the tasks companion for detect → report → ASK → guided upgrade. Open the capabilities companion for the upgrade-mode taxonomy and refuse-auto-upgrade rule. Do not open every companion file.

**Where to start:** This skill is the bundle's single source of truth for the discipline that wraps a DOCA *upgrade or downgrade*. Open the tasks companion when the user wants to *do* something with an upgrade (detect the gap, ask for confirmation, walk the guided upgrade, verify it, or diagnose a failed one); open the capabilities companion when the question is *what does an upgrade even cover* (the host apt-upgrade vs BFB reflash vs container-tag bump vs downgrade/rollback modes, the never-auto rule, the confirmation gate, the sunset-awareness concern, the error taxonomy, and the upgrade-specific safety overlay).

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

**For a planned move, the single most important rule this skill exists to enforce is detect → report → ASK → only-then guided upgrade. Never upgrade automatically.** The skill detects the installed DOCA env and what newer release is available, reports the gap clearly, then STOPS and asks the user for explicit confirmation. Only on an explicit "yes" does it walk a guided upgrade. A failed or partial move instead enters the recovery ladder without presenting a new target move. In both paths every hardware / firmware / reboot step is delegated to `doca-hardware-safety/SKILL.md`, never redefined here. Version detection itself is owned by `doca-version/SKILL.md`; this skill routes there and does not restate the detection chain.

Example questions this skill answers well

The CLASSES of upgrade questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"Is there a newer DOCA than what I have, and how far behind am

I?"** — worked example: *"`pkg-config --modversion doca-common` says `<installed X.Y.Z>`; what's current and what does moving cost me?"*. Answered by the detect-and-report-the-gap workflow in

configure, which routes the

detection to `doca-version/SKILL.md` and the *what is current* lookup to `doca-public-knowledge-map/SKILL.md`.

• **"Should I just run `apt upgrade` to