k8s-launch-kit-shared

l8k — Shared Reference

Installation

# Build and install (production — copies binary + profiles)
make build && sudo scripts/install.sh
 
# Development (symlinks into source tree)
make build && scripts/install.sh --dev-env

Install Paths

After installation, l8k is available system-wide.

Binary Discovery (for AI agents)

CRITICAL — follow these steps exactly:

1. Run which l8k in a single Bash call. If it returns a path, use it. Done.
2. If which l8k fails (exit code 1), tell the user l8k is not installed. Point them to: make build && sudo scripts/install.sh. Stop — do not proceed.
3. NEVER do any of the following to find l8k:
   • find or ls commands
   • Spawn a subagent to locate the binary
   • Check multiple paths or directories
   • Explore the repo contents

Available Commands

The root command l8k --discover-cluster-config ... still works for backward-compatible full-pipeline usage.

Target selection

discover, generate, deploy, validate, and the root pipeline default to the host target. Existing invocations must omit --target unless the user explicitly requests it; --target host is an equivalent explicit form.

The dpf target name is reserved but its phases are not implemented in this build. Do not attempt DPF provisioning. Use l8k schema and inspect targets[].phases before selecting any non-host target. Host-only flags such as --fabric, --kubeconfig, and the Network Operator/Spectrum-X flags are rejected when explicitly combined with another target.

Internally, each lifecycle command snapshots the explicitly supplied Host arguments, binds a phase-specific adapter through the target registry, and runs the resulting operation exactly once with the command context. Do not bypass this route when extending or automating a lifecycle phase. The canonical component and data-flow diagrams live in docs/architecture/overview.md; update them with any change to lifecycle, package ownership, artifacts, or external integration boundaries.

Global Flags

The persistent networkOperator.skipHelmChart setting also makes l8k clean retain the externally owned Helm release while deleting Network Operator custom resources. Clean does not route the skip flag; use config for the ownership policy or --keep-helm-chart for an explicit retention-only override.

l8k discover and l8k generate both accept the profile flags --fabric, --deployment-type, --multirail, --spectrum-x, --multiplane-mode, and --number-of-planes. Discovery persists the resolved values; later generation reuses them unless another explicit CLI override is supplied.

For automation, l8k schema exposes configPaths on config-backed flags. The metadata comes from the same registry that applies explicit flag values, so use it instead of maintaining a separate CLI-to-YAML mapping.

Agent / JSON Mode

RULE: AI agents MUST always use --output json 2>/dev/null when calling any l8k subcommand. Never use text mode — it produces unstructured output with spinners and ANSI codes that is hard to parse.

Do NOT use --yes with subcommands — it only exists on the root command and will cause "unknown flag" errors. --output json already auto-confirms all prompts (no interactive input needed).

# Correct
l8k discover --output json 2>/dev/null
l8k generate --output json 2>/dev/null
 
# WRONG — --yes is not a valid flag on subcommands
l8k discover --output json --yes 2>/dev/null

• stdout: Exactly one JSON object (JSONResult) at completion
• stderr: Human-readable log lines
• Pipe with jq for downstream processing: l8k discover ... --output json 2>/dev/null | jq .success

Exit Codes

Structured Error Output (JSON mode)

{
  "success": false,
  "phase": "discover",
  "deployed": false,
  "error": {
    "code": "CLUSTER_ERROR",
    "message": "cluster discovery failed",
    "category": "cluster",
    "transient": true,
    "suggestion": "Check that kubeconfig is valid and the cluster is reachable"
  },
  "messages": [...]
}

Error categories: validation, cluster, deployment. The transient field hints whether retrying might help.

Schema Discovery

# List all l8k capabilities as JSON
l8k schema

Use l8k schema to programmatically discover available profiles, fabrics, deployment types, flags, exit codes, and output formats.

Security Rules

• Confirm with the user before executing --deploy on a production cluster
• Prefer --dry-run for destructive operations
• Never expose kubeconfig contents in output

Network Operator Namespace Resolution

Applies to l8k generate / l8k deploy / l8k validate only. l8k discover manages its own private namespace (nvidia-k8s-launch-kit) and ignores this flag.

Both nvidia-network-operator and network-operator are common default namespaces for an existing Network Operator install. If l8k generate / l8k deploy / l8k validate can't find Network Operator resources, retry with --network-operator-namespace <correct-namespace>.