Skip to content

DPF discovery reference

Start with the step-by-step CLI workflows for first inventory, address-candidate lookup and refresh. This page provides the access and output reference.

l8k discover --target dpf collects hardware inventory from explicitly selected host/DPU Redfish or SSH endpoints. The DPF estate is independent of Host networking. Inventory mode is the default and can run before Kubernetes exists. An explicitly supplied management kubeconfig adds management observations and must work if supplied.

The standalone DPF workflow supports inventory discovery, HBN-BGP readiness, artifact generation and deployment. The current BF4/HBN-BGP cohort remains beta; command availability does not qualify every hardware and release combination. Inventory success means selected sources were read and the requested inventory was saved; it does not mean provisioning readiness or hardware qualification. Missing optional card metadata remains visible. Hardware support and deployment readiness checks do not block inventory collection.

Discovery defaults to inventory mode, including with HBN-BGP. Supply a kubeconfig to add management topology observations. Explicitly select discovery.probes.mode: management to test per-node network paths. Management probes currently support Linux/amd64 nodes. DPF HBN-BGP artifact generation and standalone deployment are available. DPF standalone validation and the composite DPF pipeline are not available.

Inventory establishes physical identities, host associations and BMC access. It does not certify hardware support for every deployment. A selected use case checks its own required hardware, firmware and controller capabilities.

Management-network probes

Set discovery.probes.mode: management and supply an explicit management kubeconfig. Hosts may use SSH or Redfish; every selected DPU must have an explicit Redfish BMC endpoint for the network checks. Select an existing namespace with discovery.probes.namespace; otherwise the kubeconfig namespace, then default, is used. The account must be able to read Nodes and the namespace and create, inspect, read logs from, and delete the temporary Pods and ConfigMap there. Namespace admission policy must allow host-network Pods. Launch Kit does not change admission policy.

All nodes reported by the management cluster must be Ready, schedulable Linux/amd64 nodes and able to pull the published, digest-pinned nicolaka/netshoot image. An optional discovery.probes.imageRepository mirror must contain the same pinned manifests. Unsupported node scope is rejected before probe resources are created. Node count alone does not establish control-plane HA or qualify a production topology.

From the CLI, Launch Kit creates one immutable ConfigMap with public request and CA data. It then runs two temporary non-root Pods on each management node:

Probe Where it runs Operations
Pod network That node's ordinary Pod network namespace Resolve the management API and each selected DPU BMC address, connect over TCP, and check HTTPS using each endpoint’s explicit trust policy.
Node network That node's host network namespace Repeat the same connection checks; read interfaces, link state and routes. For HBN-BGP with a configured tenant VIP, ask the kernel which route it would use for that VIP.

These Pods receive no BMC credentials or Kubernetes service-account token, mount no host filesystem, and do not change networking. They make unauthenticated requests to the API version endpoint and each BMC's Redfish root. An HTTP 401/403 can still prove that the HTTPS transport path works; it does not prove DPF controller authentication.

BMC probes reuse the endpoint's TLS policy. With explicit insecureSkipVerify: true, a successful handshake is reported as tls: unverified; the connectivity check can pass, but it does not verify server identity. This supports the initial BMC bootstrap path. Later DPF controller authentication remains a separate check. Management API probes always verify TLS. For trusted BMC connections, supply the endpoint's public caFile and a certificate valid for its name or address. A failed DNS, TCP or TLS check remains a blocker while other independent paths are collected. Admission, identity, image or malformed-response failures stop probe execution. Live progress names each node and network namespace.

The CLI removes only the temporary Pods and ConfigMap it created. Inspect cleanup failures and the saved resource report before retrying; do not delete resources belonging to another run.

For a new HBN tenant, interface/route checks require every node selected by the tenant selector to have the configured interface up, a suitable IPv4 prefix, and an on-link route with a source address on that interface. A VIP already assigned on a selected node is a conflict for new-tenant creation. These checks do not reserve the VIP, prove VRID uniqueness, or test failover. Missing allocation information continues to block readiness even when every network probe passes. A matching registered tenant confirms its identity and configured endpoint only. It does not prove that its control plane, virtual IP or API is currently healthy; those require separate live checks before reuse.

Use the build that produced the inventory, or a newer compatible build, for subsequent commands. Older builds can reject newly added fields.

Inputs and invocation

For HBN-BGP, also see Check HBN-BGP prerequisites.

Supply explicit host endpoints and DPU BMC endpoints for a complete inventory. Each endpoint selects exactly one source: Redfish (bmcEndpoint) or SSH (ssh). A host may contain several selected or unselected cards. With no explicit DPU endpoints, BlueField cards are derived from host observations; their BMC/ARM endpoints remain unknown and discovery is partial with a nonzero exit status. ARM-only DPU sources also leave the required BMC administrator check failed. With explicit DPU endpoints, every selected source must succeed and its card identity must match exactly one host adapter. Sources are not silently substituted after access failures. The CLI does not scan subnets.

credentials:
  dpu-reader:
    username: bmc-maintainer
    passwordRef:
      env: DPU_BMC_PASSWORD
  host-reader:
    username: bmc-reader
    passwordRef:
      env: HOST_BMC_PASSWORD
discovery:
  dpus:
    - bmcEndpoint: https://192.0.2.11
      credentialRef: dpu-reader
  hosts:
    - bmcEndpoint: https://192.0.2.21
      credentialRef: host-reader
l8k discover --target dpf --user-config dpf-site.yaml \
  --save-cluster-config dpf-discovered.yaml --output json

The YAML is ordinary CLI configuration; collected facts live under inventory. Unknown fields, duplicate keys, wrong scalar types, ambiguous contexts and duplicate endpoints fail before remote access. Lists and credentials stay in YAML; no password CLI flag exists.

Source Values
Required site inputs Nonempty host list and explicit DPU BMC endpoints with administrator credentials for completion; each selected endpoint and credential alias; username and password reference or SSH private-key reference
Defaultable dpf.release: 26.4.0; context from a supplied kubeconfig; system certificate trust; SSH port 22; SSH sudo false; collection timeout 10m; request timeout 15s; up to four endpoints queried at once (maxConcurrentBMCs)
Conditional Kubeconfig for optional management observations; SSH known-hosts file; approved noninteractive sudo for protected reads; private Redfish CA; systemURI when a BMC exposes multiple systems
Observed Physical-card/system identities, linked host adapters, named DPU firmware versions, administrator verification, runtime hardware/network facts and management nodes/version
Release defaults Software bill of materials (BOM), artifact coordinates and documented minima for supported models; omitted minima remain unknown and do not establish deployment readiness
Optional lookup inputs Explicit ARM/BMC MAC selectors; optional local dnsmasq-leases files. Lookup returns address hints, never identity or permission to connect
Later phases Deployment profile, DPU API allocation, DHCP/service networks and controller authentication

The management kubeconfig must use verified HTTPS and certificate/key or bearer credentials. File and embedded representations of the same credential/trust field are mutually exclusive; choose token or tokenFile. Exec/auth-provider plugins, basic and anonymous access are rejected in this version. Only the supplied kubeconfig is used. The BMC must support standard Redfish session login with the supplied username/password and allow the account to read inventory. Basic authentication and vendor-specific session paths are unsupported. Discovery deletes its login session when finished; a cleanup failure is reported. It does not guess passwords or repair credentials.

DPU BMC administrator authorization is required during discovery. The CLI reads its own session, the advertised standard AccountService account collection and the matching local account's linked role. An advertised account URI whose final component matches the session username is read first and its returned username is verified; unrelated account records need not be readable. For numeric/opaque account URIs, the bounded complete collection must identify one matching account. The account username must match the session, and the account must expose Enabled: true, Locked: false and PasswordChangeRequired: false. Its role must grant all five standard privileges: Login, ConfigureManager, ConfigureUsers, ConfigureComponents and ConfigureSelf. A custom role granting this set is accepted. A username of admin, a role name alone or OEM-only privileges do not establish authorization. Missing, denied, malformed or conflicting account/role evidence fails closed.

The owned session's Roles must match the account's assigned role. If Roles is absent, the CLI requires the session's UserAuthenticationSource to identify the trusted local AccountService. A current LocalAccountAuth: Enabled setting does not prove how an existing session authenticated and cannot replace this proof. LocalAccountAuth: Disabled and explicitly external session sources are unsupported. Fallback and LocalFirst require that explicit local session source, because those modes can authenticate through external providers. When mode/source information is absent, a matching effective session role is required; a username collision or an absent LDAP setting is insufficient. Malformed or inconsistent exposed fields remain unverified even when another field could otherwise establish the binding. This proves observed Redfish privileges and matching local-account state, not future write success or DPF controller authentication. External-provider role mappings are not evaluated.

Review bmcAdministratorVerified on each DPU, any issues entry for that field, and the required dpf.management.bmc-administrator check. BMC_ADMIN_REQUIRED means the role lacks administrator privileges; BMC_ADMIN_ACCESS_DENIED means required account/role reads were denied; BMC_ADMIN_UNVERIFIABLE means evidence was missing, malformed, untrusted or inconsistent; BMC_ADMIN_ACCOUNT_RESTRICTED means disabled or locked; BMC_PASSWORD_CHANGE_REQUIRED means an administrator must handle the password change separately. Discovery never rotates passwords, changes roles, or tests privileges with a write. Physical identity evidence remains in partial output. Host BMC accounts need inventory read access; the administrator gate applies to DPU BMC accounts. BF4 B4240 identity requires the exact advertised NVIDIA service product and board model plus trusted System/chassis links. Newer firmware exposes matching system/card serials. Older firmware can expose the card serial on its B4240 BMC component, reciprocally contained by the physical Card linked to the same System. Absent System metadata stays absent; exposed conflicting identities fail. These graph and identity properties are reread before success. Free-text descriptions and similar model names cannot qualify other hardware. This identity support does not establish release qualification.

Passwords resolve only from {env: NAME} or {file: path}. Environment values are verbatim. UTF-8 files lose at most one final LF/CRLF. File, SSH known-hosts and CA references are relative to the input YAML and are rebased when saved elsewhere. Private files are not copied. BMC endpoints require HTTPS; redirected connections are not supported.

Environment references are convenient for an automation system that injects secrets for one invocation. They are not required: environment values are inherited by child processes and can be exposed by process inspection or diagnostic dumps, depending on the operating system and permissions. Avoid typing literal passwords in shell commands or saving them in shell startup files.

For a local secret file or a file supplied by a secret manager, use:

credentials:
  dpu-reader:
    username: admin
    passwordRef:
      file: ./credentials/dpu-bmc-password

The file contains the password only, not YAML. Restrict the directory to its owner (0700) and the file to its owner (0600), keep it outside version control, and manage its lifecycle separately. A file reference avoids exporting the secret to the process environment; it does not encrypt the file. Choose one env or file reference per password. Discovery does not save resolved passwords in the inventory or logs.

For BMCs with untrusted certificates, explicitly opt in per endpoint:

discovery:
  dpus:
    - bmcEndpoint: https://192.0.2.11
      credentialRef: dpu-reader
      tls:
        insecureSkipVerify: true

This fragment extends the complete input above. insecureSkipVerify is a YAML boolean, defaults to false, and skips certificate-chain and hostname verification for CLI-to-BMC Redfish connections only. HTTPS remains required, but the server is not authenticated and BMC credentials can be exposed to impersonation. Prefer a verified certificate/CA through caFile when available.

The same field is accepted under discovery.tls as a shared BMC policy. An endpoint tls block replaces the entire shared policy; {insecureSkipVerify: false} restores system-trust verification for that endpoint. Omitted/null values use the policy's default. caFile and insecureSkipVerify: true cannot be combined in the effective policy. TLS policies are independent even when endpoints share credentials.

The CLI reports warnings on stderr. The saved input records the selected TLS policy so a refresh can identify changed scope or trust settings. A selected policy does not establish successful TLS or hardware verification. Use a fresh input and new output when changing the verification policy or custom CA contents. This BMC option does not relax management kubeconfig TLS verification.

Optional SSH inventory in Zero Trust

SSH collects observations without using host RShim or DPU Redfish. Run the CLI from a management node that can reach the configured endpoints. This version uses direct SSH; it does not read ambient SSH configuration, agents or ProxyJump rules. Existing jump connectivity must be provided through the chosen execution location.

credentials:
  host-os:
    username: inventory
    passwordRef: {env: HOST_SSH_PASSWORD}
  arm-os:
    username: ubuntu
    privateKeyRef: {file: ./credentials/arm-key}
discovery:
  hosts:
    - credentialRef: host-os
      ssh:
        address: 192.0.2.21:22
        knownHostsFile: ./credentials/known_hosts
        sudo: true
  dpus:
    - credentialRef: arm-os
      ssh:
        address: 192.0.2.11:22
        knownHostsFile: ./credentials/known_hosts
        sudo: true
  probes: {mode: inventory}

This example collects partial evidence without a management kubeconfig or Redfish credential; it exits nonzero because DPU BMC administrator proof is missing. For a complete inventory, select the DPU BMC through Redfish instead of ARM SSH. Each SSH credential uses exactly one password reference or unencrypted private-key file reference. SSH host keys must match the explicitly supplied known-hosts file; unknown/changed keys fail. Establish that trust through your site's trusted inventory/onboarding process. tls.insecureSkipVerify never applies to SSH.

Host collection reports the host identity and NVIDIA network cards, with PCI, driver and NUMA information where available. DPU identity must be consistent across the available system and card records; conflicting serials prevent a complete inventory. Interfaces, routes, DNS and local BMC LAN address are additional observations. Required tools must already exist; see the tool prerequisites. Discovery runs read commands, optionally with sudo -n. It installs nothing, prompts for no sudo password and changes no privileges.

ARM discovery needs a booted, reachable OS with sufficient permissions. Local ipmitool lan print can report the BMC endpoint without Redfish. The endpoint is saved as bmcEndpoint alongside method: ssh; discovery does not connect or send credentials to that newly observed address. Missing optional tools/data are reported in issues with the affected field, a stable code, safe message and tool where applicable; required-source failures retain their cause too. It never infers a BMC address from an ARM IP or a serial from a hostname.

If an optional SSH command times out, its result remains unavailable. Before the next read, Launch Kit reconnects to the same configured endpoint using the same credentials and verified host keys; it does not retry the timed-out command. Reconnection failures, failed final identity reads, changed identity, and the overall discovery deadline still prevent a complete inventory.

Host and ARM PCI addresses belong to different domains; correlation uses physical serial identity, not matching PCI addresses. If a same-serial host adapter exposes a PCI vendor other than NVIDIA (15b3), the required association fails with HOST_ADAPTER_VENDOR_CONFLICT. Inspect the endpoint, serial and PCI evidence and rerun with corrected sources; a matching serial cannot override contradictory vendor identity. A missing vendor stays unknown and does not establish hardware qualification. Other vendors remain in host inventory, and a contradictory candidate is never discarded to make another same-serial candidate appear unique. Host-reported identity alone does not attest trusted DPU state. Sources and any conflicts stay in the output. SSH observations do not satisfy the required DPU BMC administrator check. Controller mTLS enrollment and provisioning readiness remain separate later-phase checks.

Software BOM and optional address lookup

dpf.release selects the release's software BOM independently of live measurements. Omitted/null selects 26.4.0 for general inventory or the release catalog's HBN-BGP default, 26.8.0 today, when that use case is selected. Explicit empty or unknown releases are rejected. The resolved BOM is saved under inventory.software, with operator and component coordinates, exact hardware models and BFB version/URL plus a digest when known. Documented minima use named fields such as minimumNICFirmware and minimumHostMFT. Omitted minima remain unknown in software checks; they are not inherited from a newer catalog. Catalog source references, revision lists and generic requirement objects are not saved. The current catalog has exact BlueField-3 models B3210, B3220 and B3240; generic family names and BlueField-4 do not establish applicability. Desired BFB/component coordinates are not measured versions. Only documented minimum versions are compatibility checks; unsupported firmware requirements remain unknown. Model applicability and software checks do not qualify hardware or enable DPF deployment profiles.

On the supported BF4/B4240 Redfish reader, inventory.dpus[].psid records a successfully verified PSID from the selected System's AssetTag. The identity-selected chassis is used only when the System field is absent or null, following DPF's source selection. The selected value must start with uppercase MT_ and contain at most 32 ASCII letters, digits, underscores, dots or hyphens. An empty, N/A or malformed selected value remains invalid rather than falling back to another source. An absent value remains unknown. The selected source and value are reread before the PSID becomes observed; unselected chassis metadata does not replace or invalidate that selection. This is a Redfish fact obtained from authenticated AssetTag reads; it does not create an SSH/runtime observation or infer a PSID from a model.

Failures and missing PSIDs are recorded in issues with field: psid. PSID_NOT_EXPOSED and PSID_READER_UNSUPPORTED mean this source supplies no PSID. PSID_INVALID, PSID_CONFLICT, PSID_CHANGED and PSID_RECHECK_FAILED leave no eligible psid value. An invalid optional AssetTag is retained as an issue and does not prevent saving the inventory or its JSON report. These optional gaps preserve physical inventory and discovery's existing acceptance policy. A downstream consumer requiring PSID must require a single observed value associated with the selected device and reject contradictory or invalid readings across its sources; an absent or unsupported Redfish PSID may be supplied by an independently verified SSH measurement, but a rejected or conflicting Redfish PSID must not be bypassed. Refresh results also compare the observed PSID and eligibility. Release qualification and administrator authorization remain separate checks.

SSH can report NIC firmware/PSID, MFT version, NVConfig and privilege observations when the existing tools and permissions permit the read. On hosts, if MFT cannot read a card's firmware or PSID, Launch Kit also reads devlink -j dev info and matches the same host PCI function. It retains the MFT failure reason. Running and stored firmware remain distinct; stored firmware cannot prove the running version. Contradictory readings remain failures. Current and next-boot configuration remain distinct. DPU Redfish firmware is grouped by named component under firmware, such as bmc, nic, cec and uefi. Each version retains activation when known; an absent activation does not mean running. Raw vendor names, firmware resource dumps and source-reference bookkeeping are omitted. A failed source, partial firmware collection, identity change or explicit version/activation conflict cannot satisfy a minimum through that source. An independent valid SSH observation can still satisfy a minimum unless explicit component conflicts remain.

discovery.addressLookup optionally combines named ARM/BMC MAC selectors with local dnsmasq-leases snapshots and eligible neighbors already read through selected SSH sources. Results and source/device reasons are saved under inventory.addressLookup. An address candidate is unverified and never receives credentials automatically. Follow the candidate procedure to prepare lookup inputs, interpret ambiguity and explicitly add a verified endpoint.

Observations, reports and refresh

Normal output shows live status on stderr as work happens, followed by a final summary on stdout. Each status line identifies the selected source and the operation: session connection, administrator verification, inventory reads, identity rechecks, cleanup, host/card matching or output publication. RUNNING precedes the operation; PASS follows a successful check or completed read; FAIL identifies a failed operation. UNAVAILABLE identifies an optional fact that could not be measured. Optional-read summaries count unavailable facts; the saved detailed report retains actionable fact failures and required check reasons. Completing a read does not mean all optional facts were available. Concurrent endpoints can interleave whole status lines. --quiet suppresses progress; it does not change acceptance.

The final text report uses configured endpoint names, falling back to addresses, and shows DPU model/serial, host association and BMC administrator status. It separates problems that prevent discovery from prerequisites for provisioning and checks not requested in this run. Identical later-stage findings are grouped with their affected sources. An unsupported BOM model means software compatibility is unknown; it does not mean a hardware failure was detected. Inventory does not claim release or hardware qualification.

For operation timing and source/check diagnostics, add --log-level debug. Use --log-level trace for Redfish request categories/statuses and SSH stage/tool metadata. Logging does not include credentials, session tokens, request/response bodies or raw remote command output. Debug/trace logs go to stderr unless --log-file selects a file; normal live progress remains on stderr.

l8k discover --target dpf --user-config dpf-site.yaml \
  --save-cluster-config dpf-discovered.yaml --log-level debug

To watch progress while saving a machine-readable result, redirect only stdout:

l8k discover --target dpf --user-config dpf-site.yaml \
  --save-cluster-config dpf-discovered.yaml --output json \
  --log-level debug > discover.json

Redirecting 2>discover.log saves progress and logs to that file instead of displaying them. --output json still emits one final JSON document on stdout.

Read the device results

Both host and DPU records use named fields for available facts and issues for failures, mismatches and unavailable facts. Each issue identifies its field and code, with a safe message and tool when available. Successful reads do not create issue entries or repeat state: observed beside every value. The report's checks still record required successes and later-phase gaps.

Review id, serialNumber, model, psid and bmcAdministratorVerified where present. id is published only after the required physical identity rechecks succeed; a retained serial or endpoint on a failed record is diagnostic context. A missing fact stays unknown. firmwareInventoryComplete: true means DPU firmware enumeration completed, not that every version is known or compatible. firmware contains named component version lists; activation remains separate from version. ERoT components stay separate from BMC firmware.

For SSH sources, runtime.mftVersion, runtime.boardProduct and runtime.hardware.cards hold measured values. Each card can have psid, firmwareVersion, nextBoot settings and hostPrivileges. For example, nextBoot.numVFs: 0 is an explicit measured zero, not a missing value; next-boot settings do not prove the running mode. Host RShim service state, when readable, is under runtime.hardware.rshim.

Host BMC discovery keeps system identity, PCI adapter identities and advertised reset types for host-to-DPU mapping. It does not dump host firmware or manufacture DPU-only component placeholders. Host/DPU output omits generic observation maps, authentication/time placeholders, raw command strings and collection bookkeeping.

New saved inventories use format v1alpha3. This CLI also reads legacy v1alpha1 and v1alpha2 conservatively: absent state or verification does not become successful identity or administrator proof. Retired qualification and inventoryCompleteness device metadata is read and discarded. Keep previous outputs as history and refresh through discovery rather than editing version tags or facts.

Review the saved handoff

Use the saved inventory and report to review selected identities, readiness checks and field-specific reasons. Internal comparison fields in detailed output are for the CLI's refresh behavior; operators do not need to interpret them or change saved observations. The report keeps named facts and issues needed to resolve a failed or unavailable check.

Review and refresh the handoff

Review each card's serial and its host association. Missing or conflicting identity must be resolved before accepting the inventory; an IP address, PCI address or CPU serial does not establish card identity. Cards with incomplete information remain visible with their available PCI/slot details. Every requested endpoint remains represented on failure, and missing firmware or authorization facts remain unknown. Inventory completion does not establish hardware support for DPF deployment.

Complete discovery writes the requested YAML. Partial collection preserves an existing handoff and writes partial.yaml plus report.json beneath <output-stem>.discovery/<run-id>/. JSON stdout is one final DPF result, with progress on stderr. Invalid command-line arguments are reported on stderr. Configuration failures identify the field path and original YAML line/column when available. Correct that location and retry; diagnostics omit field values and source snippets so credential values are not repeated in errors. The report contains facts, checks, factual diffs, later-phase gaps, errors and successfully written artifacts. Redfish errors retain sanitized method/resource, HTTP status and observation/cleanup stage. Cleanup failures retain the exact validated session URI when known, never its token. Verify ownership before manual recovery; an unknown cleanup result is not success. Authentication at session creation does not establish permission to read protected inventory. A complete in-place refresh uses the same input/output path and saves source-before.yaml before replacing the inventory. A partial refresh leaves the original file unchanged. Avoid concurrent runs or edits to the same output, and use real directories without symlink aliases. Follow the refresh procedure when inputs, trust settings or an older saved inventory need to change.

Exit Meaning
0 Explicit-mode checks, cleanup and publication completed
2 Invalid input, incomplete required identity/mapping or DPU BMC administrator evidence, unsupported probe platform or proven mismatch
3 Required observation, authentication, TLS, API or remote cleanup failure
1 Cancellation or local output error

Check HBN-BGP prerequisites

Use --use-case hbn-bgp to add fabric inspection to DPF inventory collection. The CLI reads your selected switches over SSH from the machine running Launch Kit. It runs NVUE commands for applied interfaces, VRFs, BGP and bridges, then reads operational interfaces, bridges, LLDP and FRR BGP summaries. It does not change VLAN, VRF, BGP or forwarding configuration. The required direct ASIC RIF/VRF check supports only the catalog-qualified Cumulus Linux/NVUE reader below. Other builds can still supply software facts, but their ASIC check remains unknown and blocks HBN-BGP readiness; cumulus-nvue alone does not establish support. There is no site override to waive reader qualification.

Reader identity Supported value
OS Cumulus Linux 5.15.1 (cumulus-linux)
Code drop CD28 Base 5.deb12.dev.1481 - SDK 4.8.2052 - Nvue Core Tag 1.11.0.79 - Nvue OM Tag 1.3.33.61
/usr/bin/sx_api_router_interface_dump_all.py SHA-256 e58025b5dba285a4041099bf4bad6a3b6c81b9c34cb8aa42d43b5cc08456f608
/usr/bin/flex_acl_common.py SHA-256 2f0424de6dfc867056f2852e9af937334b2cd256cf11a9dcaa007d940030e9cf

This reader qualification is independent of the DPF release and does not qualify every switch model or topology. The collector joins observed physical ports, SDK RIF/Router IDs, switchd table mappings and Linux VRFs; missing, ambiguous, unsupported or changing sources cannot pass. Port bindings, VRF names, table IDs, MACs and MTU expectations come from site intent and observed identities.

The stock SDK diagnostic briefly changes router SDK log verbosity and restores it on its normal path. It does not change forwarding configuration. Failure, timeout or interruption leaves log restoration unconfirmed: collection stops without automatic diagnostic retry or network repair. Closing SSH does not prove that the remote command stopped or restored logging. Arrange exclusive use of router SDK diagnostics during collection and resolve uncertain log state with the switch administrator before another run.

Add switch access and intended DPU uplink connections to your existing site file. Use the DPU serial numbers from physical inventory. A port binding is intent; an LLDP hostname alone does not verify it.

dpf:
  useCase: hbn-bgp
  hbn:
    fabricVRF: default
credentials:
  fabric-reader:
    username: fabric-reader
    passwordRef:
      file: ./credentials/switch-password
discovery:
  switches:
    - name: leaf-a
      credentialRef: fabric-reader
      ssh:
        address: leaf-a.example
        knownHostsFile: ./credentials/switch-known-hosts
        sudo: true
      ports:
        - {name: swp1, dpuSerial: DPU-SERIAL-A, dpuInterface: p0}
        - {name: swp2, dpuSerial: DPU-SERIAL-A, dpuInterface: p1}

Keep the host and DPU endpoints and their credentials alongside these additions. Each DPU needs one binding for p0 and one for p1. If the mapping is unknown, retain the DPU in inventory and resolve the missing mapping before deployment. SSH requires a pinned known-hosts file; Redfish's TLS bypass does not apply. With sudo: true, LLDP, FRR, switchd table reads and the SDK diagnostic use sudo. Password authentication passes the sudo password through stdin; key authentication requires noninteractive sudo authorization.

l8k discover --target dpf --use-case hbn-bgp \
  --user-config dpf-site.yaml --save-cluster-config dpf-discovered.yaml

The explicit CLI selection overrides dpf.useCase and is saved with the result. HBN-BGP defaults to inventory mode and the release catalog's HBN-BGP release 26.8.0; the same catalog row supplies default HBN chart and image coordinates. Other dpf.release values are rejected unless the catalog explicitly supports HBN-BGP for them. The profile supplies operator namespace dpf-operator-system and networking/policy defaults. Override the operator namespace with dpf.namespace; it is independent of the namespace used for optional management-network probes. Defaults are included in the binary.

Supply management.kubeconfigRef to inspect the management cluster. Launch Kit reads its Kubernetes version and ready control-plane nodes, DPF operator Deployment, DPFOperatorConfig, tenant clusters, existing DPU enrollments, storage classes, and served DPF API schemas. These API calls run from the CLI machine. The default inventory mode creates no probe Pods; explicit management mode adds the management-network probes. Tenant clusters and DPU enrollments are read across namespaces so an existing tenant VIP or physical serial claim cannot be missed. Saved inventory includes the selected objects and concise conflict or missing-identity details; unrelated tenant and enrollment records are omitted. Denied or incomplete reads block readiness. Production HBN deployment requires multiple management control-plane nodes, all Ready. This is a necessary prerequisite, not proof of control-plane HA; the site owner must establish the etcd and API load-balancer design. An existing operator must match the selected release, and its configuration must use zero-trust mode. A release candidate does not match a selected GA release. A clean cluster can be planned for operator installation; leftover or incompatible resources require resolution before deployment.

For tenant storage, Launch Kit checks Kamaji's shared default datastore, which the selected DPF release uses, then follows its endpoints to the etcd StatefulSet, service, pods, claims and bound volumes in the selected DPF namespace. Resource names are resolved from these live references. The current supported storage backend is local-path: its StorageClass must use the cluster.local/local-path-provisioner provisioner with wait-for-first-consumer binding, and exactly one ready provisioner Deployment must be discoverable. DataStore member endpoints may use the default cluster.local or a custom service DNS domain configured in Kamaji. Every endpoint must use the same canonical DNS suffix and match the exact referenced pod, headless service, selected namespace and etcd client port. The StorageClass provisioner identity above is independent of the service DNS domain. Missing permissions, stale status, mismatched bindings, ambiguous references and unsupported storage backends block readiness. These checks are read-only; existing tenants may share the datastore.

A successful storage check describes the current backend and its bound volumes. It does not measure remaining filesystem space or guarantee capacity for future growth. Deployment repeats the storage check instead of trusting a saved inventory. Discovery does not reserve a tenant API address.

The native workflow checks every directed host pair sequentially, with three ordinary and three DF packets at one-second intervals. Packet spacing alone requires 4 × N × (N − 1) seconds for N selected physical hosts. Discovery and generation reject a matrix whose lower bound cannot fit the two-hour native maximum. This rejects 43 or more selected hosts under the current protocol; fewer hosts are not guaranteed to finish because provisioning, SSH and API checks take additional time. The check counts only uniquely associated selected hosts. Missing associations or several selected cards on one host block the native path. A discovery pass does not reserve execution time; deployment checks its actual remaining deadline.

Once the provisioning inputs and current device identities are complete, the CLI downloads the selected operator and HBN charts over HTTPS and verifies their digests and generated resource schemas. It uses that plan to ask the management API whether the configured Kubernetes identity has the scoped permissions needed for management-side provisioning. These checks include operator installation, selected DPF resources, backing-resource inspection and the software registry port-forward. Missing inputs, failed chart verification, denied permissions and incomplete authorization responses block readiness with a recorded reason.

The console summarizes successful permission checks in one line and lists each denied or unmeasured operation separately. The structured readiness report keeps the individual results for automation and troubleshooting.

The authorization results concern the CLI caller on the management cluster. Controller service accounts, tenant credentials and host/switch access must be verified separately. Roles and credentials can change, so deployment repeats its permission checks before performing operations. No generated resources are installed during this discovery check.

For the tenant control plane, add the reserved VIP and the interface on the management control-plane nodes that will carry it. For example:

provisioning:
  bootstrap:
    tenant:
      vip: 192.0.2.20
      interface: eth0
      allocation:
        vipReserved: true
        vipExcludedFromDHCP: true
        routerIDUniqueOnSelectedNodes: true

Replace the example address and interface with your site's allocation. Set the three allocation declarations to true only after the site owner has reserved the VIP for this tenant, excluded it from dynamic DHCP allocation, and verified that the selected VRRP ID is available on the selected control-plane nodes. Omitting a declaration leaves it unknown; false reports a failed prerequisite. Both block readiness. Launch Kit records these as site declarations, not as independent DHCP or IPAM verification. They cannot override an observed collision. If another DPUCluster uses the same VRRP ID, Launch Kit compares its control-plane node selector with the requested selector. Selectors that can select the same nodes fail this check; selectors with conflicting values for a shared label key are disjoint and do not conflict. An explicitly empty selector covers all nodes. A missing or unreadable selector leaves the comparison unknown. A missing VRRP ID on another configured endpoint also blocks the comparison. A cluster with no Keepalived endpoint does not reserve a VIP or VRRP ID through that configuration.

The VIP must be outside DHCP allocation and unused by another tenant. Launch Kit defaults the tenant names, capacity, pod CIDR and VRRP ID from the profile; verify that the address ranges and VRRP ID do not conflict with existing use. Changing the VIP, VRRP ID or selected nodes requires reviewing the declarations again. If discovery observes a literal management API IP and port, it can reuse them for the operator configuration. Otherwise, supply provisioning.bootstrap.managementAPIIP and managementAPIPort. Missing values block use-case readiness without discarding the hardware inventory. See the configuration reference for defaults and overrides.

For each selected DPU, Launch Kit follows its verified host association to the matching PCI adapter. Through host SSH it checks the PCI functions, mlx5_core driver, network interfaces and IOMMU groups. For interfaces associated with a host PCI function, it reads the permanent hardware MAC with ethtool -P and checks the interface's sysfs PCI binding before and after the read. The saved link keeps permanentMAC separately from its current mac; a missing tool, denied read or changed binding leaves the permanent address unavailable with a reason. The current address is never a substitute for a permanent one. It also inspects IPv4/IPv6 addresses, routes and bridge/bond relationships: a selected interface carrying a management address or default route blocks readiness. Missing tools or denied reads retain their specific failure reason. These checks do not assign host workload addresses.

Launch Kit also inspects the selected host workload port's persistent network backend over that same explicit SSH connection. The current backend requires Ubuntu 24.04, Netplan 1.1.2, systemd-networkd 255 and iproute2 6.1.0, with root access through the configured account or sudo. Install the normal host tools before discovery, including jq, dmidecode, lspci, ethtool and Netplan; Launch Kit does not install them. Missing tools or unavailable kernel MTU limits block the check with a reason. Other operating systems and network managers remain unsupported by this host-configuration workflow.

The selected workload PF must already have an active Netplan configuration managed by systemd-networkd, with its permanent MAC and interface name bound unambiguously. An unmanaged port needs site preparation before this workflow can configure its workload address. Discovery reports this prerequisite rather than taking ownership of an unmanaged interface.

The check reads the active networkd mapping and merged Netplan configuration, then validates the exact permanent-MAC/name binding, renderer and selected interface settings. Unsupported DHCP, virtual-device membership, policy rules, default routes and malformed address or route entries block the result. Raw merged configuration is kept out of the saved inventory and logs. Discovery runs reads only: it does not generate Netplan files, reload managers or change interfaces.

If a read fails, the result identifies the operation, tool and exit status without including raw network configuration or command output. Discovery stops that host-network check at the failed read; independent checks can continue.

A current MTU of 1500 can pass the backend prerequisite when the port supports the profile's desired MTU of 9000. The report identifies both values; observed MTU never replaces the desired value. Exact reserved host address and route checks happen after DPF supplies the real allocation. A backend pass establishes support for the planned operation, rather than configured addresses, reboot persistence, BGP adjacency or workload traffic. The flat profile supports one selected DPU per physical host; multiple selected paths require a supported multipath policy.

This host backend requires both the current and desired workload MTU to be at least 1280. Crossing that boundary can remove or create existing IPv6 addresses and routes, even in an IPv4 workload. A lower kernel-reported minimum does not establish support for this workflow. An unsupported override remains unchanged in the configuration and blocks readiness with an explanation.

To check cabling, Launch Kit reads permanent network-function MAC addresses from the identity-selected DPU card through Redfish. It compares them with switch LLDP port MACs and p0/p1 names or descriptions. Each binding needs a unique match; a hostname or port label alone is insufficient. The saved DPU field networkFunctionMACs records MAC ownership, not a physical-port assignment. If this path cannot establish a binding, Launch Kit can receive LLDP on the selected host's physical interfaces through SSH. It verifies the host UUID, card serial, PCI functions and Linux phys_port_name before and after capture. Each capture uses the existing tcpdump and timeout tools for up to 65 seconds; it neither installs tools nor changes the interface's promiscuous mode. The advertised switch chassis MAC, system name and port must match the switch facts read through authenticated SSH. Expired or conflicting advertisements cannot satisfy a binding. Missing tools and denied reads retain their failure reason. This fallback does not replace a known mismatch from the first path. Saved facts contain the selected peer identity, not packet captures. LLDP corroboration does not authenticate the peer or prove workload packet delivery.

HBN-BGP discovery also checks the selected DPF release's initial BMC enrollment reads. For DPF 26.8.0 on BlueField-4, these include the controller's BF4 chassis, PSID and PF0 permanent-MAC resources. An older BMC can support physical inventory while lacking those resources. In that case, inventory can complete but readiness fails with the missing resource and a firmware compatibility explanation. Denied reads and changing identities also block readiness. A pass covers these reads; DPF controller authentication, firmware updates and other provisioning actions remain later checks. Discovery does not update BMC firmware.

Host reset support is a separate prerequisite. On each selected DPU BMC, discovery reads and rechecks the firmware build required by the selected release's reviewed reset backend. An unsupported model/build or an unavailable read blocks HBN-BGP readiness even when physical inventory completes. Resolve the reported firmware/backend mismatch and rediscover. Deployment repeats this check before provisioning changes. Passing it does not authorize a reboot: the current reset request, safe shutdown, idle tasks and firmware-copy state are checked at reset time.

On each configured switch, Launch Kit reads both the NVUE interface list and the individual selected ports. The per-port reads supply VRF and parent relationships that the list may omit. Conflicting observations block readiness; an absent bridge field alone does not prove that a port is routed. The switch's own LLDP chassis MAC and system name are read through the authenticated SSH connection. Your switch's display name in the site file is not its physical identity. These switch reads do not change forwarding configuration. The qualified ASIC diagnostic separately adjusts router SDK log verbosity briefly; see its restoration limits before running it. Launch Kit reads the NVUE revision table before and after these switch reads. The explicit active application ID must remain stable and match exactly one saved-history record. An unconfirmed change, unsupported revision state, missing identity or changing application blocks readiness. Historical saved revisions and unrelated staged changes can remain present. This check reads NVUE's reported state; it does not inspect the startup file or test persistence through a reboot.

Switch readiness uses the available switch configuration and routing observations for the selected uplinks. Missing or conflicting observations stay unknown or failed with a reason. A configuration observation does not prove hardware forwarding, and discovery does not change switch forwarding configuration. The qualified ASIC diagnostic may briefly adjust router SDK log verbosity; see its restoration limits.

Through the same switch SSH connection, Launch Kit reads FRR's running BGP configuration to check effective eBGP policy mode and filter attachments for the selected peers and their peer groups. The supported flat profile has no required import-prefix filter. A verified unfiltered configuration can pass this check; an attached route map or another unsupported policy remains unknown with a reason. An enabled requirement for import/export policies with none configured fails. This check does not prove which routes a future DPU will advertise or accept. Saved output keeps selected policy facts rather than raw configuration.

The switch address check reads interface addresses and IPv4/IPv6 routes from all routing tables, including referenced kernel nexthops. Switch SSH must permit these read-only observations even before any DPU advertises a route. Missing, unsupported or changing path observations block ownership verification on resume. Specific routes or addresses overlapping the workload or loopback pool block readiness when they belong to the selected VRF; unresolved VRF ownership remains unknown. A default route is not an address allocation. The saved switch view retains selected peers and interfaces plus prefixes relevant to both pools. It does not contain the switch's complete routing table. Site and cluster IPAM allocation and effective BGP route policy are separate checks.

Omit dpf.hbn to use the flat IPv4 BGP profile defaults, or override individual fields:

Field Default Purpose
fabricVRF default Switch VRF expected on the selected uplinks
fabricASN 65000 Expected switch BGP autonomous system
dpuASNBase / dpuASNStride 65101 / 100 Per-DPU ASNs allocated in sorted serial-number order
uplinkMTU / workloadMTU 9216 / 9000 Desired uplink and workload MTUs
workloadCIDR / workloadPrefix 10.0.120.0/22 / 29 Desired workload address pool and per-allocation prefix

These defaults describe the desired configuration. They do not establish that ASNs or addresses are free, that ports are routed, or that the fabric is ready. Discovery compares the observed infrastructure with this expected configuration. Customize only the values your environment needs; omitted values keep their profile defaults. For example:

dpf:
  release: "26.8.0"
  useCase: hbn-bgp
  hbn:
    fabricVRF: tenant-fabric
    fabricASN: 65010
    uplinkMTU: 9000
    workloadMTU: 8800
    workloadCIDR: 172.20.0.0/22

These overrides change what discovery expects and what generation uses. They do not configure the switches during discovery. A different observed VRF or ASN is a mismatch to resolve, rather than a replacement for your requested value. Keep switch access and physical port bindings in the site's discovery inputs; they are separate from these network defaults.

For example, an MTU check can report expected at least 9216 bytes; configured 9000; operational 9000. Change the desired MTU only if the use case permits the smaller value, or correct the infrastructure and rerun discovery. Not measured means the command could not establish a value; it does not mean the default was observed.

Changing the selected DPU set can change ASN assignments; use a fresh output and review the resolved profile and assignments before deployment.

Read HBN-BGP readiness separately from physical inventory. Missing switch access, unknown facts and configuration mismatches block readiness and return a nonzero status. A complete physical inventory can still be saved for diagnosis. The report names each failed check and its reason; the inventory stores the resolved profile and selected switch observations under inventory.hbn.

The HBN-BGP readiness assessment keeps unverified provisioning, artifact, host and routing-policy prerequisites blocked. It does not authorize deployment from a successful fabric read. Live BGP adjacency, advertised routes and workload traffic must be checked after deployment; discovery cannot prove those outcomes before the DPU services exist.

After reviewing the inventory, follow HBN-BGP generation to prepare a local deployment bundle. Generation can run before live prerequisites are remediated; its success does not change discovery's blocked readiness result. The default DPU ASN base and stride cover five devices. For a larger selection, override the allocation to fit the private ASN range and your fabric policy.