DOCA container deployment
Examples
- "How do I run a DOCA service container on BlueField?" —
this is in scope after the setup recognize front door. Drop
a documented pod spec; do not invent YAML or image tags.
- "The pod spec is in the directory but the pod never
starts." — walk the eight-layer taxonomy before letting
kubelet restart-loop the pod.
Instructions
Follow Loading order below. Open the tasks companion for
configure / run / debug. Open the capabilities companion for
the kubelet-standalone contract. Do not open every companion
file.
Where to start: This skill is for operating the cross-cutting
DOCA container-deployment runtime — the shared pattern every DOCA
service on the BlueField uses to come up (kubelet standalone agent
on the BlueField Arm watching a static-pod manifests directory; the
operator drops a YAML pod spec into that directory; kubelet schedules
the pod and runs the container).
If the developer has NOT yet decided container vs. bare-metal
("I just got a BlueField, what now?", "my code is built, how do I
run it?", "how do I deploy this?"), route them BACK to
doca-setup/SKILL.md first.
That is the front-door routing decision. The wrong failure mode is
to silently push every developer onto the container path because the
agent loaded this skill first. ## recognize detects the system
shape, asks the minimum residual question, and lands the developer on
either this skill (when the workload is a packaged DOCA service to
drop on a BlueField) or the bare-metal-path sibling
doca-bare-metal-deployment/SKILL.md
(when the workload is a DOCA-linked application binary the developer
launches directly).
If the developer is already on the container path, open
the tasks companion and start at
## configure. If the question is what shape
of runtime is this and what does the deployment contract look like,
start at the capabilities companion. For per-service
overlays, follow the per-service skill under skills/services/ that
layers on top of this one — the supported overlays are Argus, DMS,
Firefly, and UROM service. Flow-Inspector and OS-Inspector are
outside this bundle's scope; route them through
doca-public-knowledge-map/SKILL.md
instead of applying this runtime overlay. Externally-productized
NVIDIA services (BlueMan, HBN, SNAP, Virtio-net, DOCA Telemetry
Service as productized, …) are also out of scope and route through
that map. If DOCA is
not installed on the BlueField target yet, route to
doca-setup/SKILL.md first.
Audience
This skill serves external operators and platform teams who deploy
DOCA service containers on BlueField — i.e., people who have a
BlueField with DOCA installed on the Arm side, a container runtime
plus the kubelet standalone agent already present per the BlueField
OS image, and the host-OS permissions the public DOCA Container
Deployment Guide names for the chosen service. The skill is the
shared deployment runtime; each per-service skill in the bundle
(see the list in ## Related skills) supplies
the service-specific config schema, paired-workload contract, and
"healthy" definition.
It is not for NVIDIA developers contributing to the BlueField
container runtime or to kubelet itself, and it is not a generic
Kubernetes tutorial. Kubelet runs on the BlueField in standalone
mode here — no full Kubernetes control plane, no kubectl against
a cluster API server — and the substantive answer to most
container-deployment questions on the BlueField is the public DOCA
Container Deployment Guide. This skill teaches the agent which
guide to quote, in what order to walk it, and how to map a symptom
to a layer; it does NOT re-invent kubelet flags, pod-spec field
names, or static-pod path strings. The shared deployment runtime
described here is the cross-cutting layer; the per-service skill
(doca-argus, doca-dms, doca-firefly,
doca-urom-svc) supplies the per-service
config schema, paired-workload contract, and "healthy" definition.
When to load this skill
Load this skill when the user is doing hands-on container
deployment of any DOCA service on a BlueField target, or asking a
cross-service deployment question that is not specific to one
service's config schema. Concretely:
- Dropping a YAML pod spec into the documented static-pod manifests
directory on the BlueField Arm so kubelet standalone schedules the
pod and runs the DOCA service container.
- Inspecting pod status, container logs, and the documented
liveness signal for any supported in-bundle DOCA service container
— Argus, DMS, Firefly, or UROM service — so the
agent answers "did the container come up, and is the service
inside actually ready" the same way for every service.
- Walking the smoke-before-bulk loop (pod reaches
Running;
ENTRYPOINT logs are clean; service answers a trivial liveness
probe) BEFORE the BlueField is put under workload.
- Diagnosing a deployment that is misbehaving — pod-spec YAML is in
the directory but the pod never schedules; pod schedules but
image-pull fails; image pulls but container ENTRYPOINT
immediately exits; container runs but the service inside never
answers; container is in a restart loop after a config edit; a
volume mount the pod spec names is missing on the host; a network
policy or host-firewall rule is blocking the service.
- Cross-service questions: "can I have DMS and Firefly on the
same BlueField", "how do I list every DOCA service pod that is
currently running", "what is the documented stop / restart
semantics if I edit a pod-spec file in place".
Do not load this skill for per-service config schema questions
(those belong to the matching per-service skill); for installing
DOCA itself or preparing the BlueField env (use
doca-setup/SKILL.md); for library-API
questions (use the matching libs/<library> skill); or for general
Kubernetes-cluster operations (this skill covers kubelet standalone
mode on the BlueField, not a full Kubernetes control plane).
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — the cross-cutting DOCA container-deployment
runtime contract on the BlueField (kubelet standalone agent on
BlueField Arm watching a documented static-pod manifests
directory; YAML pod-spec drop is the unit of operator input; the
same pattern applies across every DOCA service), the BlueField
preconditions (DOCA install, container runtime, BFB version,
per-service firmware slot when the service emulates a device,
image-pull reachability to NGC, host-OS permissions), the
observability surface (kubelet status, container logs, service-
side liveness signal — three layers, each with its own owner),
the cross-cutting error taxonomy (pod-spec syntax → pod
scheduling → image pull → runtime → volume mount → network policy
→ version → cross-cutting host) covering exactly eight layers, and the
safety policy (smoke before bulk; failed pod is high-stakes —
clear the root cause before letting kubelet restart-loop the
pod; do NOT invent pod-spec field names / kubelet flags / image
tags from memory).
- the tasks companion — step-by-step workflows for the in-scope deployment
verbs:
configure, build, modify, run, test, debug,
plus a Deferred task verbs block routing per-service config
questions, host-firmware-slot work, paired-workload work, and
full-Kubernetes-cluster work out to their owning skills.
The skill assumes a BlueField target where DOCA is already installed
on the Arm side, the BlueField OS image ships kubelet standalone +
the container runtime per the public DOCA Container Deployment
Guide, and the operator has the host-OS permissions that guide
names. It does not cover installing DOCA — that path goes through
doca-setup/SKILL.md — and it does not
re-document the per-service config schema, which is the canonical
concern of each DOCA service's public guide reached through
doca-public-knowledge-map/SKILL.md.
Loading order
- Read this skill first to confirm the user's question is in
scope (cross-cutting deployment runtime, NOT a per-service
config-schema question).
- For the kubelet-standalone-mode runtime shape, the static-pod
manifests directory rule, the host-OS / BFB / firmware-slot /
image-pull preconditions, the eight-layer error taxonomy, the
observability surface, and the safety / smoke-before-bulk
policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Related skills
doca-public-knowledge-map/SKILL.md
— public Container Deployment Guide, per-service guides, and
NGC. Quote documented paths and tags from there; do not invent
them.
doca-setup/SKILL.md — env and install on the
BlueField target, including the recognize front door that
chooses this skill vs bare-metal.
doca-bare-metal-deployment/SKILL.md
— the sibling binary-launch path.
doca-debug/SKILL.md — cross-cutting debug
ladder this runtime's pod / image / ENTRYPOINT layers sit on.
doca-version/SKILL.md — four-way match and
container-tag overlay.
doca-structured-tools-contract/SKILL.md
— prefer structured status when present.
- Per-service overlays:
doca-argus/SKILL.md,
doca-dms/SKILL.md,
doca-firefly/SKILL.md,
doca-urom-svc/SKILL.md.
doca-programming-guide/SKILL.md
— program-side discipline when a service surfaces a library
error.
1---2license: Apache-2.03name: doca-container-deployment4description: >5 Running an in-bundle DOCA service as a container on a BlueField (Argus,6 DMS, Firefly, or UROM service): kubelet standalone watching a static-pod7 manifests directory, YAML pod-spec drop, kubelet status / ENTRYPOINT8 logs / per-service liveness. Trigger on "how do I run my built service9 on the BlueField?", "where do I drop the pod-spec YAML?", "pod stuck in10 Pending / ImagePullBackOff / CrashLoopBackOff", "container Running but11 service isn't ready", "pod restart-loops after edit", or "DMS and12 Firefly together", even without naming container deployment. A13 DOCA-linked binary launched directly on the host or Arm belongs to14 doca-bare-metal-deployment. Covers smoke-before-bulk and the layered15 error taxonomy (pod-spec, scheduling, image pull, runtime, mount,16 network, version, host). Refuse and route elsewhere for per-service17 config schemas, DOCA install, library-API questions, external NVIDIA18 services (BlueMan, HBN, SNAP, Virtio-net), or full Kubernetes-cluster19 ops.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-container-deployment22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - container28 - deployment29compatibility: >30 No DOCA install required to read this skill (it is an overlay loaded31 against any DOCA artifact skill); the validation steps within DO32 require a live DOCA install at /opt/mellanox/doca.33---3435# DOCA container deployment3637## Examples3839- **"How do I run a DOCA service container on BlueField?"** —40 this is in scope after the setup recognize front door. Drop41 a documented pod spec; do not invent YAML or image tags.42- **"The pod spec is in the directory but the pod never43 starts."** — walk the eight-layer taxonomy before letting44 kubelet restart-loop the pod.4546## Instructions4748Follow Loading order below. Open the tasks companion for49configure / run / debug. Open the capabilities companion for50the kubelet-standalone contract. Do not open every companion51file.5253**Where to start:** This skill is for *operating* the cross-cutting54DOCA container-deployment runtime — the shared pattern every DOCA55service on the BlueField uses to come up (kubelet standalone agent56on the BlueField Arm watching a static-pod manifests directory; the57operator drops a YAML pod spec into that directory; kubelet schedules58the pod and runs the container).5960**If the developer has NOT yet decided container vs. bare-metal**61(*"I just got a BlueField, what now?"*, *"my code is built, how do I62run it?"*, *"how do I deploy this?"*), route them BACK to63`doca-setup/SKILL.md` first.64That is the front-door routing decision. The wrong failure mode is65to silently push every developer onto the container path because the66agent loaded this skill first. `## recognize` detects the system67shape, asks the minimum residual question, and lands the developer on68either this skill (when the workload is a packaged DOCA service to69drop on a BlueField) or the bare-metal-path sibling70`doca-bare-metal-deployment/SKILL.md`71(when the workload is a DOCA-linked application binary the developer72launches directly).7374**If the developer is already on the container path**, open75the tasks companion and start at76`## configure`. If the question is *what shape77of runtime is this and what does the deployment contract look like*,78start at the capabilities companion. For per-service79overlays, follow the per-service skill under `skills/services/` that80layers on top of this one — the supported overlays are Argus, DMS,81Firefly, and UROM service. Flow-Inspector and OS-Inspector are82outside this bundle's scope; route them through83`doca-public-knowledge-map/SKILL.md`84instead of applying this runtime overlay. Externally-productized85NVIDIA services (BlueMan, HBN, SNAP, Virtio-net, DOCA Telemetry86Service as productized, …) are also out of scope and route through87that map. If DOCA is88not installed on the BlueField target yet, route to89`doca-setup/SKILL.md` first.9091## Audience9293This skill serves **external operators and platform teams who deploy94DOCA service containers on BlueField** — i.e., people who have a95BlueField with DOCA installed on the Arm side, a container runtime96plus the kubelet standalone agent already present per the BlueField97OS image, and the host-OS permissions the public DOCA Container98Deployment Guide names for the chosen service. The skill is the99shared deployment runtime; each per-service skill in the bundle100(see the list in [`## Related skills`](#related-skills)) supplies101the service-specific config schema, paired-workload contract, and102"healthy" definition.103104It is **not** for NVIDIA developers contributing to the BlueField105container runtime or to kubelet itself, and it is **not** a generic106Kubernetes tutorial. Kubelet runs on the BlueField in *standalone*107mode here — no full Kubernetes control plane, no `kubectl` against108a cluster API server — and the substantive answer to most109container-deployment questions on the BlueField is the public DOCA110Container Deployment Guide. This skill teaches the agent which111guide to quote, in what order to walk it, and how to map a symptom112to a layer; it does NOT re-invent kubelet flags, pod-spec field113names, or static-pod path strings. The shared deployment runtime114described here is the cross-cutting layer; the per-service skill115(`doca-argus`, `doca-dms`, `doca-firefly`,116`doca-urom-svc`) supplies the per-service117config schema, paired-workload contract, and "healthy" definition.118119## When to load this skill120121Load this skill when the user is doing **hands-on container122deployment of any DOCA service** on a BlueField target, or asking a123cross-service deployment question that is not specific to one124service's config schema. Concretely:125126- Dropping a YAML pod spec into the documented static-pod manifests127 directory on the BlueField Arm so kubelet standalone schedules the128 pod and runs the DOCA service container.129- Inspecting pod status, container logs, and the documented130 liveness signal for any supported in-bundle DOCA service container131 — Argus, DMS, Firefly, or UROM service — so the132 agent answers "did the container come up, and is the service133 inside actually ready" the same way for every service.134- Walking the smoke-before-bulk loop (pod reaches `Running`;135 ENTRYPOINT logs are clean; service answers a trivial liveness136 probe) BEFORE the BlueField is put under workload.137- Diagnosing a deployment that is misbehaving — pod-spec YAML is in138 the directory but the pod never schedules; pod schedules but139 image-pull fails; image pulls but container ENTRYPOINT140 immediately exits; container runs but the service inside never141 answers; container is in a restart loop after a config edit; a142 volume mount the pod spec names is missing on the host; a network143 policy or host-firewall rule is blocking the service.144- Cross-service questions: *"can I have DMS and Firefly on the145 same BlueField"*, *"how do I list every DOCA service pod that is146 currently running"*, *"what is the documented stop / restart147 semantics if I edit a pod-spec file in place"*.148149Do **not** load this skill for per-service config schema questions150(those belong to the matching per-service skill); for installing151DOCA itself or preparing the BlueField env (use152`doca-setup/SKILL.md`); for library-API153questions (use the matching `libs/<library>` skill); or for general154Kubernetes-cluster operations (this skill covers kubelet *standalone*155mode on the BlueField, not a full Kubernetes control plane).156157## What this skill provides158159This is a **thin loader**. Substantive material lives in two160companion files:161162- the capabilities companion — the cross-cutting DOCA container-deployment163 runtime contract on the BlueField (kubelet standalone agent on164 BlueField Arm watching a documented static-pod manifests165 directory; YAML pod-spec drop is the unit of operator input; the166 same pattern applies across every DOCA service), the BlueField167 preconditions (DOCA install, container runtime, BFB version,168 per-service firmware slot when the service emulates a device,169 image-pull reachability to NGC, host-OS permissions), the170 observability surface (kubelet status, container logs, service-171 side liveness signal — three layers, each with its own owner),172 the cross-cutting error taxonomy (pod-spec syntax → pod173 scheduling → image pull → runtime → volume mount → network policy174 → version → cross-cutting host) covering exactly eight layers, and the175 safety policy (smoke before bulk; failed pod is high-stakes —176 clear the root cause before letting kubelet restart-loop the177 pod; do NOT invent pod-spec field names / kubelet flags / image178 tags from memory).179- the tasks companion — step-by-step workflows for the in-scope deployment180 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`,181 plus a `Deferred task verbs` block routing per-service config182 questions, host-firmware-slot work, paired-workload work, and183 full-Kubernetes-cluster work out to their owning skills.184185The skill assumes a BlueField target where DOCA is already installed186on the Arm side, the BlueField OS image ships kubelet standalone +187the container runtime per the public DOCA Container Deployment188Guide, and the operator has the host-OS permissions that guide189names. It does not cover installing DOCA — that path goes through190`doca-setup/SKILL.md` — and it does not191re-document the per-service config schema, which is the canonical192concern of each DOCA service's public guide reached through193`doca-public-knowledge-map/SKILL.md`.194195## Loading order1961971. Read this skill first to confirm the user's question is in198 scope (cross-cutting deployment runtime, NOT a per-service199 config-schema question).2002. **For the kubelet-standalone-mode runtime shape, the static-pod201 manifests directory rule, the host-OS / BFB / firmware-slot /202 image-pull preconditions, the eight-layer error taxonomy, the203 observability surface, and the safety / smoke-before-bulk204 policy, see the capabilities companion.**2053. **For step-by-step workflows — configure, build, modify, run,206 test, debug — see the tasks companion.**207208## Related skills209210- `doca-public-knowledge-map/SKILL.md`211 — public Container Deployment Guide, per-service guides, and212 NGC. Quote documented paths and tags from there; do not invent213 them.214- `doca-setup/SKILL.md` — env and install on the215 BlueField target, including the recognize front door that216 chooses this skill vs bare-metal.217- `doca-bare-metal-deployment/SKILL.md`218 — the sibling binary-launch path.219- `doca-debug/SKILL.md` — cross-cutting debug220 ladder this runtime's pod / image / ENTRYPOINT layers sit on.221- `doca-version/SKILL.md` — four-way match and222 container-tag overlay.223- `doca-structured-tools-contract/SKILL.md`224 — prefer structured status when present.225- Per-service overlays:226 `doca-argus/SKILL.md`,227 `doca-dms/SKILL.md`,228 `doca-firefly/SKILL.md`,229 `doca-urom-svc/SKILL.md`.230- `doca-programming-guide/SKILL.md`231 — program-side discipline when a service surfaces a library232 error.