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 inconfigure, 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 move to the next DOCA
release?" — worked example: "I want the newest Flow features;
can I upgrade in place right now?". Answered by the never-auto
rule and the confirmation gate inSafety policy
plus the ask-before-acting step inrun — the agent reports the gap and
STOPS for explicit confirmation before any upgrade command runs.
- "My upgrade left the host on a different release than the
BlueField — what happened?" — worked example: "after the
upgrade
pkg-config reports the new release but bfver still reports the old one".
Answered by the host/BFB-skew row inError taxonomy
and the failed-upgrade diagnosis indebug, which re-routes the
detection to doca-version ## test.
- "The upgrade aborted half-way and now
dpkg is wedged — how do
I recover?" — worked example: "apt upgrade was interrupted;
dpkg reports an interrupted transaction". Answered by the
partial-upgrade and aborted-transaction rows inError taxonomy
plus the recovery ladder in ## debug.
- "The upgrade needs me to reflash the BFB / flip BlueField mode /
reboot — is that safe?" — worked example: "the target release
requires a new BFB; can I reflash now?". Answered by routing
every hardware / firmware / reboot step to
doca-hardware-safety/SKILL.md viarun; this skill never redefines the
reflash, mode-flip, or cold-power-cycle discipline.
- "My installed component is being sunset — should I keep building
on it or move?" — worked example: "I rely on DOCA App Shield /
the DOCA Flow Inspector service; are they on a
deprecation track?". Answered by the sunset / deprecation
awareness concern in
Capabilities and modes,
which routes the user to the public release notes via
doca-public-knowledge-map/SKILL.md
to confirm lifecycle status rather than recommending continued
investment in a component that may be sunsetting.
When to load this skill
Load this skill whenever an upgrade or downgrade of DOCA is the
load-bearing concern — the user is asking whether a newer release
exists, whether to move to it, how to move safely, or how to recover
a move that went wrong. The decision must be made before the
agent composes its first sentence; the activation checklist below is
mirrored here so the activation rule is at hand whenever this skill
is consulted. For a planned upgrade or downgrade, it reports the gap
and then STOPS for explicit user confirmation. For a failed or partial
upgrade, it enters ## debug first to
capture and stabilize the current state; it never uses another
upgrade command as the first recovery action, retries the move, or
issues a new upgrade command without explicit confirmation.
Agent activation checklist — load this skill at the START of the answer when any cell below is true
| Trigger class |
Concrete prompt-side signals (any one fires the overlay) |
| Upgrade / downgrade intent |
"is there a newer DOCA", "should I move to the next release", "upgrade me to the latest", "roll me back to the previous DOCA", "downgrade to 3.1 for a bug repro" |
| Accidental / drifted upgrade |
"apt upgrade pulled a newer DOCA point release and broke my build", "my host and BlueField are on different releases now", *"the source channel is latest and I didn't mean to move" * |
| Failed / partial upgrade |
"the upgrade aborted half-way", "dpkg is wedged after an interrupted transaction", "upgrade finished but the four-way match no longer holds" |
| Container tag bump |
the user wants to move an NGC DOCA container deployment from one tag to a newer one, or asks whether bumping the tag is an upgrade |
| Sunset / deprecation awareness |
the user asks whether the component they depend on is deprecated, being sunset, or worth continued investment |
First classify the request. A planned move (including a requested
rollback) follows detect → report → ASK. A failed, partial, or
accidentally drifted move is already a diagnosis/recovery request:
load this skill, capture the current four-source state, and enter
TASKS.md ## debug; do not ask for permission to perform an upgrade
that has already failed, and do not issue another upgrade command as
the first recovery action.
For a planned move, the agent MUST:
- Route planned-upgrade version detection to
doca-version ## configure.
For failed or partial upgrades, start with
doca-version ## debug anddebug. Do NOT restate the
four-source detection chain here; this skill consumes the detected
state and four-way match status.
- Report the gap and STOP for explicit confirmation. Present
the installed release, the available target release, and what
moving costs (per
Version compatibility),
then ask the user to confirm. Do NOT proceed to any upgrade
command until the user explicitly says yes.
- Route every hardware / firmware / reboot step to
doca-hardware-safety/SKILL.md. This
skill names when such a step is part of the upgrade; that skill
names how it is applied safely.
For a failed/partial move, the agent MUST instead classify the
captured state against
CAPABILITIES.md ## Error taxonomy,
delegate the single documented corrective action, and re-enter the
recovery ladder. Any unsupported installed → target jump fails
closed: do not improvise intermediate releases or commands; require
an upgrade path explicitly documented by the Compatibility Policy or
release notes.
Do not load this skill for first-time install (use
doca-setup/SKILL.md), for the version-detection
chain in isolation (use doca-version/SKILL.md),
or for general orientation (use
doca-public-knowledge-map/SKILL.md).
What this skill provides
This is a thin loader. The body keeps only the orientation
needed to pick the right next file. The substantive upgrade material
lives in two companion files:
- the capabilities companion — the upgrade surface: the upgrade-mode taxonomy
(host apt upgrade vs BFB reflash vs container-tag bump vs
downgrade/rollback), the never-auto rule and the confirmation
gate, the sunset / deprecation-awareness concern, the
version-compatibility overlay that redirects to
doca-version,
the error taxonomy (partial upgrade, apt-source drift, host/BFB
skew, aborted transaction / dpkg interrupted), the observability
surface (which commands prove the upgrade did or did not happen),
and the upgrade-specific safety overlay on top of
doca-hardware-safety.
- the tasks companion — step-by-step workflows for the in-scope verbs:
configure (detect + discover target + apt-source precheck),
build and modify (routing stubs — the version-pin change is
owned elsewhere), run (the confirmation-gated guided upgrade),
test (post-upgrade four-way verification), debug (diagnose a
failed / partial upgrade), plus a Deferred task verbs block.
Loading order
- Read this skill first to confirm the user's question is in
scope (an upgrade / downgrade is being contemplated or recovered).
- For the upgrade-mode taxonomy, the never-auto rule, the
sunset-awareness concern, the error taxonomy, observability, and
the safety overlay, see the capabilities companion.
- For step-by-step workflows — detect-and-report, the
confirmation-gated guided upgrade, post-upgrade verification, and
failed-upgrade diagnosis — see the tasks companion.
Related skills
doca-version/SKILL.md — owns the four-source
detection chain and the four-way match rule. This skill's detect
step routes there and does not redefine version detection; the
gap report consumes the detected version.
doca-setup/SKILL.md — owns first-time install,
install verification, and the apt-source path. This skill's
apt-source consistency precheck cross-links there before any
apt-shaped upgrade is contemplated.
doca-hardware-safety/SKILL.md — owns
every hardware / firmware / reboot step (mlxconfig, BFB reflash,
BlueField mode flip, cold power cycle). This skill's ## Safety policy overlays that meta-policy and adds only the
upgrade-specific surface (confirmation gate, rollback-first,
maintenance window).
doca-public-knowledge-map/SKILL.md —
the routing table to public DOCA docs, including the release notes
and the Compatibility Policy. This skill routes what is the
current release and is this component sunsetting there; it does
not duplicate the routing.
doca-debug/SKILL.md — the cross-cutting debug
ladder. A failed upgrade whose residual symptom lives at a
software layer hands off there once the upgrade state is known.
doca-programming-guide/SKILL.md —
the build pattern a consumer rebuilds against after an upgrade.
This skill surfaces that a rebuild may be needed; the build
mechanics live there.
doca-structured-tools-contract/SKILL.md —
the JSON schemas the agent prefers when present; the upgrade
detect step reuses the same doca-env one-shot the version skill
uses, when the host has it.
1---2license: Apache-2.03name: doca-upgrade4description: >5 Changing DOCA versions safely: upgrading or downgrading the host DOCA6 packages, refreshing the BlueField BFB, bumping the NGC DOCA container7 tag, or rolling back, with the discipline detect -> report -> ASK ->8 only then a guided upgrade. Trigger on "is there a newer DOCA", "I want the newest DOCA9 features, can I just apt upgrade in place", "should I move to the10 next release", "the upgrade stopped midway and dpkg is in a broken11 state", "my component is being deprecated, what now", or "roll me back",12 even without the word upgrade. Detect what is installed, find the newer13 release, report the gap, then STOP and ask for explicit confirmation;14 never upgrade automatically. Do not use it for a runtime error on an15 unchanged install (doca-debug). Version detection alone belongs to16 doca-version, first-time install to doca-setup, any hardware / firmware17 / reboot step to doca-hardware-safety, and public-docs or sunset routing18 to doca-public-knowledge-map.19metadata:20 source: https://skillmd.com/skills/nvidia/doca-upgrade21 author: NVIDIA <doca-feedback@nvidia.com>22 kind: library23 doca_version: "3.5"24 tags:25 - doca26 - upgrade27 - version28compatibility: >29 No DOCA install required to read this skill (it is a cross-cutting30 overlay loaded against any DOCA artifact skill); the detection,31 gap-report, and guided-upgrade steps within DO require a live DOCA32 install at /opt/mellanox/doca, and the hardware / firmware / reboot33 steps require a BlueField DPU or ConnectX NIC plus out-of-band34 console reachability as gated by doca-hardware-safety.35---3637# DOCA upgrade3839## Examples4041- **"Should I move to the next DOCA release?"** — detect what is42 installed, report the gap, then STOP and ask. Never auto-upgrade.43- **"apt upgrade drifted my DOCA packages."** — this is recovery,44 not a silent repair. Detect, report, ask, then guide.4546## Quick answers (answer from this file)4748- **Not changing versions** (a runtime error on the current, pinned49 install)? This skill does not apply: name `doca-debug` and stop.5051These two answers are complete here; open `TASKS.md` only for a guided52upgrade after the user confirms. Run only the read-only detection53commands yourself. Package commands (`sudo dpkg`, `apt`, `apt-get`) need54root and change the system: give them to the user to run and stop; in an55agent shell `sudo` waits for a password and the session stalls.5657- **"Can I just `apt upgrade` to the next DOCA?"** Never upgrade58 automatically. Detect the installed release with the `doca-version`59 four-source chain (`pkg-config --modversion doca-common`,60 `cat /opt/mellanox/doca/applications/VERSION`, `doca_caps --version`, and61 the BFB version on BlueField), report the gap to the target release, then62 STOP and ask for explicit confirmation. BFB, firmware or reboot steps follow63 `doca-hardware-safety`.64- **"The upgrade aborted half-way and dpkg reports an interrupted65 transaction."** Recover the package database first:66 after the user explicitly confirms (both commands change system package67 state), the user runs `sudo dpkg --configure -a`, then68 `sudo apt-get -f install` (Debian/Ubuntu). Do not re-run the upgrade as the first action; re-detect69 the release with `doca-version` before deciding the next step.7071## Instructions7273Follow Loading order below. Open the tasks companion for detect →74report → ASK → guided upgrade. Open the capabilities companion for75the upgrade-mode taxonomy and refuse-auto-upgrade rule. Do not open76every companion file.7778**Where to start:** This skill is the bundle's single source of79truth for the discipline that wraps a DOCA *upgrade or downgrade*.80Open the tasks companion when the user wants to *do* something81with an upgrade (detect the gap, ask for confirmation, walk the82guided upgrade, verify it, or diagnose a failed one); open83the capabilities companion when the question is *what does84an upgrade even cover* (the host apt-upgrade vs BFB reflash vs85container-tag bump vs downgrade/rollback modes, the never-auto rule,86the confirmation gate, the sunset-awareness concern, the error87taxonomy, and the upgrade-specific safety overlay).8889**How to use this skill.** Read this file, then search the companion file90for the `## <name>` heading the question needs and read that whole section.91Answer completely from it, quoting only its symbols and commands. Do not92browse docs; use the entry points in `doca-public-knowledge-map`. Give93environment checks as commands for the user's DOCA host. For out-of-scope94requests, name the skill that owns them and stop.9596**For a planned move, the single most important rule this skill97exists to enforce is detect → report → ASK → only-then guided98upgrade. Never upgrade automatically.** The skill detects the99installed DOCA env and what newer release is available, reports the100gap clearly, then STOPS and asks the user for explicit confirmation.101Only on an explicit "yes" does it walk a guided upgrade. A failed or102partial move instead enters the recovery ladder without presenting a103new target move. In both paths every hardware / firmware / reboot104step is delegated to105`doca-hardware-safety/SKILL.md`, never106redefined here. Version detection itself is owned by107`doca-version/SKILL.md`; this skill routes there108and does not restate the detection chain.109110## Example questions this skill answers well111112The CLASSES of upgrade questions this skill is built to answer, each113with one worked example. The agent should treat the *class* as the114load-bearing piece — the worked example is a single instance.115116- **"Is there a newer DOCA than what I have, and how far behind am117 I?"** — worked example: *"`pkg-config --modversion doca-common`118 says `<installed X.Y.Z>`; what's current and what does moving cost me?"*.119 Answered by the detect-and-report-the-gap workflow in120 ## configure, which routes the121 detection to `doca-version/SKILL.md` and the122 *what is current* lookup to123 `doca-public-knowledge-map/SKILL.md`.124- **"Should I just run `apt upgrade` to move to the next DOCA125 release?"** — worked example: *"I want the newest Flow features;126 can I upgrade in place right now?"*. Answered by the never-auto127 rule and the confirmation gate in128 ## Safety policy129 plus the ask-before-acting step in130 ## run — the agent reports the gap and131 STOPS for explicit confirmation before any upgrade command runs.132- **"My upgrade left the host on a different release than the133 BlueField — what happened?"** — worked example: *"after the134 upgrade `pkg-config` reports the new release but `bfver` still reports the old one"*.135 Answered by the host/BFB-skew row in136 ## Error taxonomy137 and the failed-upgrade diagnosis in138 ## debug, which re-routes the139 detection to `doca-version ## test`.140- **"The upgrade aborted half-way and now `dpkg` is wedged — how do141 I recover?"** — worked example: *"`apt upgrade` was interrupted;142 `dpkg` reports an interrupted transaction"*. Answered by the143 partial-upgrade and aborted-transaction rows in144 ## Error taxonomy145 plus the recovery ladder in ## debug.146- **"The upgrade needs me to reflash the BFB / flip BlueField mode /147 reboot — is that safe?"** — worked example: *"the target release148 requires a new BFB; can I reflash now?"*. Answered by routing149 every hardware / firmware / reboot step to150 `doca-hardware-safety/SKILL.md` via151 ## run; this skill never redefines the152 reflash, mode-flip, or cold-power-cycle discipline.153- **"My installed component is being sunset — should I keep building154 on it or move?"** — worked example: *"I rely on DOCA App Shield /155 the DOCA Flow Inspector service; are they on a156 deprecation track?"*. Answered by the sunset / deprecation157 awareness concern in158 ## Capabilities and modes,159 which routes the user to the public release notes via160 `doca-public-knowledge-map/SKILL.md`161 to confirm lifecycle status rather than recommending continued162 investment in a component that may be sunsetting.163164## When to load this skill165166Load this skill whenever an upgrade or downgrade of DOCA is the167load-bearing concern — the user is asking whether a newer release168exists, whether to move to it, how to move safely, or how to recover169a move that went wrong. The decision must be made **before** the170agent composes its first sentence; the activation checklist below is171mirrored here so the activation rule is at hand whenever this skill172is consulted. For a planned upgrade or downgrade, it reports the gap173and then STOPS for explicit user confirmation. For a failed or partial174upgrade, it enters ## debug first to175capture and stabilize the current state; it never uses another176upgrade command as the first recovery action, retries the move, or177issues a new upgrade command without explicit confirmation.178179## Agent activation checklist — load this skill at the START of the answer when any cell below is true180181| Trigger class | Concrete prompt-side signals (any one fires the overlay) |182| --- | --- |183| Upgrade / downgrade intent | *"is there a newer DOCA"*, *"should I move to the next release"*, *"upgrade me to the latest"*, *"roll me back to the previous DOCA"*, *"downgrade to 3.1 for a bug repro"* |184| Accidental / drifted upgrade | *"`apt upgrade` pulled a newer DOCA point release and broke my build"*, *"my host and BlueField are on different releases now"*, *"the source channel is `latest` and I didn't mean to move" * |185| Failed / partial upgrade | *"the upgrade aborted half-way"*, *"`dpkg` is wedged after an interrupted transaction"*, *"upgrade finished but the four-way match no longer holds"* |186| Container tag bump | the user wants to move an NGC DOCA container deployment from one tag to a newer one, or asks whether bumping the tag is an upgrade |187| Sunset / deprecation awareness | the user asks whether the component they depend on is deprecated, being sunset, or worth continued investment |188189First classify the request. A **planned move** (including a requested190rollback) follows detect → report → ASK. A **failed, partial, or191accidentally drifted move** is already a diagnosis/recovery request:192load this skill, capture the current four-source state, and enter193TASKS.md `## debug`; do not ask for permission to perform an upgrade194that has already failed, and do not issue another upgrade command as195the first recovery action.196197For a planned move, the agent MUST:1981991. Route planned-upgrade version detection to200 `doca-version ## configure`.201 For failed or partial upgrades, start with202 `doca-version ## debug` and203 ## debug. Do NOT restate the204 four-source detection chain here; this skill consumes the detected205 state and four-way match status.2062. **Report the gap and STOP for explicit confirmation.** Present207 the installed release, the available target release, and what208 moving costs (per209 ## Version compatibility),210 then ask the user to confirm. Do NOT proceed to any upgrade211 command until the user explicitly says yes.2123. Route every hardware / firmware / reboot step to213 `doca-hardware-safety/SKILL.md`. This214 skill names *when* such a step is part of the upgrade; that skill215 names *how* it is applied safely.216217For a failed/partial move, the agent MUST instead classify the218captured state against219CAPABILITIES.md `## Error taxonomy`,220delegate the single documented corrective action, and re-enter the221recovery ladder. Any unsupported `installed → target` jump fails222closed: do not improvise intermediate releases or commands; require223an upgrade path explicitly documented by the Compatibility Policy or224release notes.225226Do **not** load this skill for first-time install (use227`doca-setup/SKILL.md`), for the version-detection228chain in isolation (use `doca-version/SKILL.md`),229or for general orientation (use230`doca-public-knowledge-map/SKILL.md`).231232## What this skill provides233234This is a **thin loader**. The body keeps only the orientation235needed to pick the right next file. The substantive upgrade material236lives in two companion files:237238- the capabilities companion — the upgrade surface: the upgrade-mode taxonomy239 (host apt upgrade vs BFB reflash vs container-tag bump vs240 downgrade/rollback), the never-auto rule and the confirmation241 gate, the sunset / deprecation-awareness concern, the242 version-compatibility overlay that redirects to `doca-version`,243 the error taxonomy (partial upgrade, apt-source drift, host/BFB244 skew, aborted transaction / `dpkg` interrupted), the observability245 surface (which commands prove the upgrade did or did not happen),246 and the upgrade-specific safety overlay on top of247 `doca-hardware-safety`.248- the tasks companion — step-by-step workflows for the in-scope verbs:249 `configure` (detect + discover target + apt-source precheck),250 `build` and `modify` (routing stubs — the version-pin change is251 owned elsewhere), `run` (the confirmation-gated guided upgrade),252 `test` (post-upgrade four-way verification), `debug` (diagnose a253 failed / partial upgrade), plus a `Deferred task verbs` block.254255## Loading order2562571. Read this skill first to confirm the user's question is in258 scope (an upgrade / downgrade is being contemplated or recovered).2592. **For the upgrade-mode taxonomy, the never-auto rule, the260 sunset-awareness concern, the error taxonomy, observability, and261 the safety overlay, see the capabilities companion.**2623. **For step-by-step workflows — detect-and-report, the263 confirmation-gated guided upgrade, post-upgrade verification, and264 failed-upgrade diagnosis — see the tasks companion.**265266## Related skills267268- `doca-version/SKILL.md` — owns the four-source269 detection chain and the four-way match rule. This skill's detect270 step routes there and does not redefine version detection; the271 gap report consumes the detected version.272- `doca-setup/SKILL.md` — owns first-time install,273 install verification, and the apt-source path. This skill's274 apt-source consistency precheck cross-links there before any275 `apt`-shaped upgrade is contemplated.276- `doca-hardware-safety/SKILL.md` — owns277 every hardware / firmware / reboot step (mlxconfig, BFB reflash,278 BlueField mode flip, cold power cycle). This skill's `## Safety279 policy` overlays that meta-policy and adds only the280 upgrade-specific surface (confirmation gate, rollback-first,281 maintenance window).282- `doca-public-knowledge-map/SKILL.md` —283 the routing table to public DOCA docs, including the release notes284 and the Compatibility Policy. This skill routes *what is the285 current release* and *is this component sunsetting* there; it does286 not duplicate the routing.287- `doca-debug/SKILL.md` — the cross-cutting debug288 ladder. A failed upgrade whose residual symptom lives at a289 software layer hands off there once the upgrade state is known.290- `doca-programming-guide/SKILL.md` —291 the build pattern a consumer rebuilds against after an upgrade.292 This skill surfaces *that* a rebuild may be needed; the build293 mechanics live there.294- `doca-structured-tools-contract/SKILL.md` —295 the JSON schemas the agent prefers when present; the upgrade296 detect step reuses the same `doca-env` one-shot the version skill297 uses, when the host has it.