Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command reference

Auto-generated by go run ./tools/refgen/cobra-md > book/src/27-command-reference.md. Re-run on every CLI surface change.

roksbnkctl deploys F5 BIG-IP Next for Kubernetes (BNK) onto IBM Cloud ROKS, manages the COS supply chain BNK depends on, and runs built-in connectivity, DNS, and throughput tests against the deployed environment.

The 4-command lifecycle: roksbnkctl init Interactive setup; writes the workspace config roksbnkctl up Provision (or attach) and deploy BNK roksbnkctl test Run connectivity, DNS, and throughput tests roksbnkctl down Tear down BNK (and the cluster if cluster up provisioned it)

See https://jgruberf5.github.io/roksbnkctl/book/ for the canonical user guide.

Global flags

These flags apply to every command. They are declared on the root command and inherited by every subcommand.

FlagTypeDefaultDescription
--backendstring—execution backend: local | docker | k8s | ssh:<target> (default: per-tool from workspace exec: block, else local)
--bootstrapboolfalsefor –backend ssh:<target>: auto-install missing tools on Ubuntu via apt-get (requires passwordless sudo on the target)
--insecure-host-keyboolfalseskip the host-key TOFU prompt; record on first contact (CI use)
--no-colorboolfalsedisable colored output
--onstring—run on the named SSH target instead of locally (roksbnkctl targets list to see options)
--output / -ostringtextoutput format: text | json
--quiet / -qboolfalsesuppress all but errors
--verbose / -vboolfalseverbose output
--workspace / -wstring—workspace name (default: current; first run creates ‘default’)

roksbnkctl agent

Drive this workspace with an agentic CLI (personas + AGENTS.md)

roksbnkctl agent [claude|gemini|aider|openai|pi|opencode|agy] [flags]

Agentic mode. roksbnkctl embeds no LLM — bring your own coding-agent CLI.

roksbnkctl agent init Scaffold AGENTS.md + personas/ + journal/ into the workspace roksbnkctl agent List supported CLIs + this workspace’s default roksbnkctl agent <cli> Launch <cli> against the workspace\n roksbnkctl agent <cli> –show Print the invocation instead of running it

Personas (act as exactly one at a time): solution-architect (customer interface, owns scope), cloud-operator (runs the lifecycle), test-engineer (validation probes), doc-specialist (the report). See personas/ after init.

Flags

FlagTypeDefaultDescription
--showboolfalseprint the invocation instead of running the agent

roksbnkctl agent init

Scaffold the agentic-mode files into the workspace

Copies AGENTS.md, CLAUDE.md, the persona role contracts, and a decisions.md seed into the workspace dir, and creates an empty journal/. Safe to re-run: existing files are left untouched (your edits survive).

← back to roksbnkctl agent

roksbnkctl apikey

Print the workspace’s resolved IBM Cloud API key to stdout (a secret)

Resolve the workspace’s IBM Cloud API key via the standard chain and print it to stdout — the scripting seam for driving the ibmcloud CLI off a workspace:

ibmcloud login –apikey “$(roksbnkctl -w <ws> apikey)”

Resolution order (the same roksbnkctl itself uses):

  1. environment — IBMCLOUD_API_KEY / IC_API_KEY / TF_VAR_* (including any loaded from $PWD/.env, which roksbnkctl reads at startup)
  2. OS keychain (service “roksbnkctl”, account “<workspace>/ibmcloud_api_key”)
  3. workspace config.yaml — ibmcloud.api_key_b64 (base64-decoded)

Non-interactive: it never prompts — if no key is found it exits non-zero with an actionable error.

WARNING: this writes the credential to stdout. Pipe or redirect it; never echo it into logs or CI output.

roksbnkctl apply

Apply Terraform without re-prompting (assumes config.yaml exists)

roksbnkctl apply [flags]

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt
--no-kubeconfigboolfalseskip the post-apply admin kubeconfig fetch
--planstring—apply exactly this saved plan file (from plan --out) instead of re-planning
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

roksbnkctl backend

Configure the per-tool execution backend default (writes config.yaml for you)

Set or inspect the per-tool execution-backend default — the exec: block — from the CLI, instead of hand-editing config.yaml.

show effective backend for each tool, and where it came from set <tool> <be> persist exec.<tool>.backend (be: local | docker | k8s | ssh:<target>) unset <tool> remove the override; the tool reverts to its built-in default

The per-invocation --backend flag still wins over whatever is persisted here.

roksbnkctl backend set

Persist a per-tool execution-backend default

roksbnkctl backend set <tool> <backend>

← back to roksbnkctl backend

roksbnkctl backend show

Show the effective execution backend for each tool

← back to roksbnkctl backend

roksbnkctl backend unset

Remove a per-tool backend override (revert to the built-in default)

roksbnkctl backend unset <tool>

← back to roksbnkctl backend

roksbnkctl bnk

BNK trial lifecycle (sits on top of a cluster)

Manage the BNK trial resources (flo, cne_instance, license) as a short-lived layer on top of a shared, durable cluster.

Commands: roksbnkctl bnk up Deploy the BNK trial (auto-provisions the cluster if missing) roksbnkctl bnk down Destroy the BNK trial, leaving the cluster in place

Use roksbnkctl cluster ... to manage the cluster phase itself.

roksbnkctl bnk down

Destroy the BNK trial, leaving the cluster in place

roksbnkctl bnk down [flags]

Destroys only the BNK trial resources, leaving the cluster phase intact for the next bnk up to attach to. The common iteration loop:

roksbnkctl bnk down && roksbnkctl bnk up # ~5 min trial reset roksbnkctl down # full teardown, ~30 min

Exits 0 (“nothing to do”) when there’s no trial state (cluster-only or empty), so it’s safe in a reverse-order teardown of every phase. Refuses on legacy single-state workspaces (use roksbnkctl down there).

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl bnk

roksbnkctl bnk output

Print the BNK phase’s own terraform outputs (text or –json; [name] = one raw value)

roksbnkctl bnk output [name] [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

← back to roksbnkctl bnk

roksbnkctl bnk status

Live runtime status of the BNK trial phase (namespaces + component readiness)

roksbnkctl bnk status [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

← back to roksbnkctl bnk

roksbnkctl bnk up

Deploy the BNK trial; provisions the cluster first if missing

roksbnkctl bnk up [flags]

Provisions the BNK trial against the existing cluster phase. If the workspace has no cluster registered yet, bnk up bootstraps the cluster phase first (with a confirmation prompt — the cluster provision takes ~30 min) before the trial apply.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip confirmation prompts (cluster-bootstrap + apply)
--no-kubeconfigboolfalseskip the post-apply admin kubeconfig fetch
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl bnk

roksbnkctl bnkforge

Configure + drive BNK Forge cluster registration

Configure and drive registration of this workspace’s cluster with a co-located BNK Forge (v3) install — without hand-editing config.yaml.

enable turn on auto-registration on cluster up (writes config.yaml) disable turn it back off status show the effective config + readiness register register this workspace’s cluster with BNK Forge right now

Registration uses BNK Forge v3’s REST API (it has no CLI). It is credential- backed: an IBM Cloud credential template is stored in Forge so it re-derives the kubeconfig on demand — nothing perishable is stored. The password is read from BNK_FORGE_PASSWORD or an interactive prompt (never persisted); the resulting session token is cached in the OS keychain.

roksbnkctl bnkforge disable

Turn off BNK Forge auto-registration (LOCAL only — does not unregister)

Clears the workspace’s auto-register flag, so cluster up stops registering with BNK Forge.

This is a LOCAL setting and never contacts the server. A cluster already registered stays on Forge’s Kubernetes page — to remove it, use roksbnkctl bnkforge unregister.

← back to roksbnkctl bnkforge

roksbnkctl bnkforge enable

Enable BNK Forge auto-registration on cluster up (writes config.yaml for you)

roksbnkctl bnkforge enable [flags]

Flags

FlagTypeDefaultDescription
--forge-castring—PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure)
--insecureboolfalseDISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca
--projectstring—target BNK Forge project name (ensured-or-created)
--urlstring—BNK Forge server URL (e.g. https://forge.example.com)
--usernamestring—BNK Forge login username

← back to roksbnkctl bnkforge

roksbnkctl bnkforge register

Register this workspace’s cluster with BNK Forge now (no re-up needed)

roksbnkctl bnkforge register [flags]

Flags

FlagTypeDefaultDescription
--forceboolfalsetake over a cluster registered to ANOTHER Forge project (moves it, and its cluster id changes)
--forge-castring—PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure)
--insecureboolfalseDISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca
--passwordstring—BNK Forge password (prefer BNK_FORGE_PASSWORD env or the prompt)
--projectstring—target BNK Forge project name (overrides config)
--urlstring—BNK Forge server URL (overrides config)
--usernamestring—BNK Forge login username (overrides config)

← back to roksbnkctl bnkforge

roksbnkctl bnkforge ssh-credential

Give BNK Forge the SSH private key for an appliance this workspace built

roksbnkctl bnkforge ssh-credential [flags]

Stores an appliance’s SSH private key in BNK Forge and attaches it to the workspace’s project, so Forge can reach the appliance itself.

bnk.flp.vsi.ssh_key names an IBM Cloud VPC key, which puts the PUBLIC half on the VSI — that is operator access, and it already works. Forge separately needs the PRIVATE half, and nothing supplied it, so a healthy FLP reports:

infrastructure_private_key_available: false
infrastructure_access_status:         recovery_required

Nothing can be recovered there — the credential was never created.

–host must be the address FORGE can reach, which for an FLP is the FLOATING IP. flp status reports a services-VPC endpoint that Forge sits outside of, so a credential built from it can never connect.

Flags

FlagTypeDefaultDescription
--expect-fingerprintstring—SHA256 fingerprint the key must match (e.g. the VPC key’s) — a credential that cannot log in is worse than none
--forge-castring—PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure)
--hoststring—address FORGE reaches the appliance on — the FLOATING IP, not the endpoint flp status prints
--insecureboolfalseDISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca
--keystring—PRIVATE key file Forge will use (unencrypted; Forge stores it and cannot prompt)
--namestring—credential name in Forge (default: <project>-ssh)
--passwordstring—BNK Forge password (prefer BNK_FORGE_PASSWORD env or the prompt)
--portint22SSH port on the appliance
--projectstring—BNK Forge project to attach the credential to
--ssh-usernamestringubuntuSSH user on the appliance
--urlstring—BNK Forge server URL (overrides config)
--usernamestring—BNK Forge login username (overrides config)

← back to roksbnkctl bnkforge

roksbnkctl bnkforge status

Show this workspace’s BNK Forge registration config + readiness

← back to roksbnkctl bnkforge

roksbnkctl bnkforge unregister

Remove this workspace’s cluster from its BNK Forge project

roksbnkctl bnkforge unregister [flags]

Removes the cluster this workspace registered, so a teardown can undo what bnkforge register did.

Without it a workspace can create a registration it has no way to remove: bnkforge disable only clears the local auto-register flag and never contacts the server, so the cluster stays on Forge’s Kubernetes page pointing at something that may no longer exist.

Absence is success. No project, no cluster of that name, or a cluster already gone all report and exit 0, so this is safe to run from a destroy path that may run twice or run late.

Flags

FlagTypeDefaultDescription
--forge-castring—PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure)
--insecureboolfalseDISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca
--passwordstring—BNK Forge password (prefer BNK_FORGE_PASSWORD)
--projectstring—BNK Forge project holding the cluster
--urlstring—BNK Forge base URL
--usernamestring—BNK Forge username

← back to roksbnkctl bnkforge

roksbnkctl cleanup

Delete orphaned IBM Cloud resources left by a failed down

roksbnkctl cleanup [flags]

cleanup sweeps the current workspace’s IBM Cloud account for resources named after the workspace prefix (<prefix>-*) and deletes them in dependency order.

Use it to recover from a ‘down’ that errored partway and stranded resources (jumphosts, security groups, floating IPs, subnets, VPCs, the Transit Gateway, the registry COS instance, the ROKS cluster, and the BNK trusted profile).

This is a DESTRUCTIVE, best-effort sweep keyed purely on the <prefix>- name convention. It always lists what it found and asks before deleting (unless –auto); –dry-run lists without deleting. Re-run if some deletes fail (e.g. a VPC waiting on an async cluster delete).

A Transit Gateway is deleted only once its connections are detached, and cleanup detaches only connections to VPCs it is also deleting. A gateway still attached to anything else — a VPC under another prefix, a Direct Link, a GRE tunnel — is REFUSED rather than silently disconnected from its other tenants. Re-running will not clear that: detach it yourself, or delete those networks.

Flags

FlagTypeDefaultDescription
--all-regionsboolfalsesweep every IBM Cloud region (slower; catches resources in regions not recorded in config)
--auto / -yboolfalseskip the confirmation prompt
--dry-runboolfalselist orphaned resources without deleting
--regionstringSlice[]additional region(s) to sweep (repeatable); defaults to the cluster + client regions

roksbnkctl cluster

ROKS cluster lifecycle (separate from BNK trials)

Manage the ROKS cluster as a durable, reusable resource that sits underneath your BNK trials.

Commands: roksbnkctl cluster up Create the ROKS cluster (+ transit gateway, registry COS) roksbnkctl cluster down Destroy the cluster and everything cluster-scoped roksbnkctl cluster register Discover an already-existing cluster and persist its identity roksbnkctl cluster config Print the recorded cluster identity from cluster-outputs.json roksbnkctl cluster status Live runtime status (endpoints + node readiness)

Each roksbnkctl up against this workspace will reuse the registered cluster (reading cluster-outputs.json) so multiple BNK trials can share one cluster.

roksbnkctl cluster config

Print the recorded cluster identity (cluster-outputs.json)

Aliases: show

roksbnkctl cluster config [flags]

Prints the cluster identity recorded at cluster up / register time (~/.roksbnkctl/<workspace>/cluster-outputs.json): cluster ID, endpoints, VPC, transit gateway, registry COS, and the create-time settings the cluster was built with (network mode, and the VPC address block when this tool created the VPC). This is the RECORDED config, and for the create-time settings it is AUTHORITATIVE — config.yaml describes what is wanted, this describes what exists. For live runtime state (node readiness) use roksbnkctl cluster status.

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

← back to roksbnkctl cluster

roksbnkctl cluster down

Destroy the cluster phase (ROKS + cluster-shared services)

roksbnkctl cluster down [flags]

Tears down everything roksbnkctl cluster up created. Refuses to run if any BNK trial state exists for this workspace — destroy those first with roksbnkctl down to avoid orphaned BNK resources.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl cluster

roksbnkctl cluster output

Print the Cluster phase’s own terraform outputs (text or –json; [name] = one raw value)

roksbnkctl cluster output [name] [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

← back to roksbnkctl cluster

roksbnkctl cluster register

Discover an existing ROKS cluster and persist its identity

roksbnkctl cluster register [cluster-name-or-id] [flags]

Looks up an existing ROKS cluster in your IBM Cloud account, verifies its registry COS instance exists, and writes the cluster’s identity to ~/.roksbnkctl/<workspace>/cluster-outputs.json.

Subsequent roksbnkctl up runs in this workspace will pick up the registered cluster automatically — no need to repeat its identity in trial tfvars.

The registry COS instance is found by probing the names roksbnkctl and the upstream HCL actually use: “<prefix>-registry-cos” (what cluster up creates), “<cluster>-registry-cos”, then the upstream fallback “<cluster>-cos”. Pass –registry-cos-name to override (e.g. if your tfvars sets roks_cos_instance_name to something else).

Flags

FlagTypeDefaultDescription
--promptboolfalseprompt for the cluster name even if one is given as an argument
--registry-cos-namestring—registry COS instance name (default: probe “<prefix>-registry-cos”, “<cluster>-registry-cos”, “<cluster>-cos”)

← back to roksbnkctl cluster

roksbnkctl cluster status

Live runtime status of the Cluster phase (endpoints + node readiness)

roksbnkctl cluster status [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

← back to roksbnkctl cluster

roksbnkctl cluster up

Provision the ROKS cluster (and cluster-shared services) only

roksbnkctl cluster up [flags]

Creates the durable cluster-shared infrastructure only — the ROKS cluster, transit gateway, and registry COS. cert-manager and the BNK trial modules (flo, cne_instance, license) deploy in the BNK phase; the jumphosts deploy in the testing phase. On success, writes the cluster’s identity to ~/.roksbnkctl/<workspace>/cluster-outputs.json so subsequent roksbnkctl up runs can deploy the BNK and testing phases onto this cluster.

Uses a separate state directory (~/.roksbnkctl/<workspace>/state-cluster/) so it doesn’t tangle with BNK or testing state.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt before apply
--no-kubeconfigboolfalseskip the post-apply admin kubeconfig fetch
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl cluster

roksbnkctl config

Print an example config.yaml or .env, or convert one into the other

Prints the workspace input in either form, for piping to a file.

With no –from flag it prints an ANNOTATED template — every setting with the comment explaining it, which is what you want when starting from nothing:

roksbnkctl config yaml > config.yaml roksbnkctl config env > .env

With –from-yaml or –from-env it prints the POPULATED equivalent, without comments — the same settings expressed in the other form:

roksbnkctl config env –from-yaml config.yaml > .env roksbnkctl config yaml –from-env .env > config.yaml

The conversion carries what the input actually sets. A setting left at its default is omitted rather than written out, so the result stays a statement of intent instead of a snapshot of every default at the moment it ran – except the handful of REQUIRED fields, which are emitted empty so a missing one is visible rather than silently absent.

roksbnkctl config env

Print an annotated .env of ROKSBNKCTL_* overrides, or the .env equivalent of a config.yaml

roksbnkctl config env [flags]

Flags

FlagTypeDefaultDescription
--from-envstring—read settings from a .env file and print the populated equivalent (no comments)
--from-yamlstring—read settings from a config.yaml and print the populated equivalent (no comments)

← back to roksbnkctl config

roksbnkctl config yaml

Print an annotated config.yaml, or the config.yaml equivalent of a .env

roksbnkctl config yaml [flags]

Flags

FlagTypeDefaultDescription
--from-envstring—read settings from a .env file and print the populated equivalent (no comments)
--from-yamlstring—read settings from a config.yaml and print the populated equivalent (no comments)

← back to roksbnkctl config

roksbnkctl cos

Manage IBM Cloud Object Storage (instances, buckets, objects)

roksbnkctl cos provides full CRUD on the COS supply chain BNK depends on: COS instances (via Resource Controller), buckets, and keyed objects (FAR pull keys, JWT licenses, etc.). All calls go through the IBM Go SDKs — no ibmcloud CLI dependency.

roksbnkctl cos bucket

Manage COS buckets

Flags

FlagTypeDefaultDescription
--instancestring—COS instance name or CRN (required)

← back to roksbnkctl cos

roksbnkctl cos bucket create

Create a bucket on the named instance

roksbnkctl cos bucket create <bucket> [flags]

Flags

FlagTypeDefaultDescription
--classstringstandardstorage class (standard, vault, cold, smart)
--regionstring—bucket region (default: workspace region)

← back to roksbnkctl cos bucket

roksbnkctl cos bucket delete

Delete a bucket (must be empty)

roksbnkctl cos bucket delete <bucket>

← back to roksbnkctl cos bucket

roksbnkctl cos bucket get

Recursively download every object in a bucket to a local directory

roksbnkctl cos bucket get <bucket> <local-dir> [flags]

Recursively download every object in <bucket> to <local-dir>.

<local-dir> is created if it does not exist (mkdir -p semantics, mode 0755). Object keys map to nested subdirectories — a key foo/bar/baz.json lands at <local-dir>/foo/bar/baz.json. Streaming download per object (no whole-object in-memory buffering); text and binary are both copied through verbatim.

Default behavior is overwrite (the operator just asked to download); pass –no-clobber to skip objects whose local target already exists, matching cp -n.

With –output json, emits one JSON object per file completed: {“key”,“local_path”,“size”,“outcome”}. The final counts line goes to stderr in text mode; the JSON stream concludes with one summary record of shape {“counts”:{…}}.

Flags

FlagTypeDefaultDescription
--no-clobberboolfalseskip objects whose local target already exists (cp -n semantics)

← back to roksbnkctl cos bucket

roksbnkctl cos bucket list

List buckets on the named instance

← back to roksbnkctl cos bucket

roksbnkctl cos instance

Manage COS instances (service instances under Resource Controller)

← back to roksbnkctl cos

roksbnkctl cos instance create

Create a COS instance

roksbnkctl cos instance create <name> [flags]

Create a COS service instance under the workspace’s resource group.

–plan accepts a friendly name (standard | lite); –plan-id takes a catalog UUID directly when IBM ships a tier roksbnkctl hasn’t mapped yet. –target defaults to “global” (COS instances are global; buckets carry the regional affinity).

Flags

FlagTypeDefaultDescription
--planstringstandardservice plan name (standard | lite)
--plan-idstring—service plan UUID (overrides –plan; for plans roksbnkctl hasn’t mapped)
--targetstringglobaltarget region (default: global; COS instances are global)

← back to roksbnkctl cos instance

roksbnkctl cos instance delete

Delete a COS instance (and its bound resources unless –no-recursive)

roksbnkctl cos instance delete <name> [flags]

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt
--no-recursiveboolfalsedo NOT delete bound resources (HMAC keys, service credentials)

← back to roksbnkctl cos instance

roksbnkctl cos instance list

List COS instances in the current account

← back to roksbnkctl cos instance

roksbnkctl cos object

Manage objects in COS buckets

Flags

FlagTypeDefaultDescription
--instancestring—COS instance name or CRN (required)

← back to roksbnkctl cos

roksbnkctl cos object delete

Delete an object

roksbnkctl cos object delete <bucket>/<key>

← back to roksbnkctl cos object

roksbnkctl cos object get

Download an object (streaming)

roksbnkctl cos object get <bucket>/<key> <local-file>

← back to roksbnkctl cos object

roksbnkctl cos object list

List objects (optionally under a prefix)

roksbnkctl cos object list <bucket>[/<prefix>]

← back to roksbnkctl cos object

roksbnkctl cos object put

Upload an object (multipart for large files, streaming)

roksbnkctl cos object put <bucket>/<key> <local-file>

← back to roksbnkctl cos object

roksbnkctl doctor

Check prerequisites and report missing pieces

roksbnkctl doctor [flags]

Verifies the host has what roksbnkctl needs.

Required (hard fail on missing):

  • terraform on PATH (the local backend’s workhorse for roksbnkctl up)

Informational (the binary internalises each surface; missing → no warning):

  • kubectl / oc — internalised via client-go (roksbnkctl k *)
  • ibmcloud — bundled image, run via –backend docker / –backend ssh:<target>
  • iperf3 — bundled image, run via –backend k8s
  • dig — DNS probe internalised via miekg/dns

A stock dev box with only terraform installed should produce exit 0 and zero warnings.

Pass –target <name> to additionally probe an SSH target (runs whoami). Pass –backend k8s | ssh:<target> for per-backend prereq checks.

Exits non-zero only when a required check fails (warnings don’t block).

Flags

FlagTypeDefaultDescription
--backendstring—additionally run per-backend checks: k8s | ssh:<target>
--targetstring—additionally probe the named SSH target with whoami

roksbnkctl down

Destroy everything in the workspace — terraform destroy

roksbnkctl down [flags]

Tears down the workspace’s phases in reverse-dependency order: BNK and Testing in parallel, then the cluster. Two behaviours worth knowing:

  • If the cluster was attached to an EXISTING (shared) Transit Gateway, down auto-detaches that connection first — removing only this cluster’s connection; the shared gateway and every other cluster’s connection are left intact.
  • If this workspace CREATED a VPC that another cluster’s subnets still live in (the shared-VPC topology), down refuses: the VPC owner must be torn down LAST, so tear the workspaces sharing the VPC down first.

The Gateway and FLP phases are separate and optional; if present, tear them down first (down reports which command to run).

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

roksbnkctl exec

Run a single command with cluster context loaded

roksbnkctl exec [command...]

roksbnkctl flp

F5 License Proxy phase — optional in-cluster licensing proxy

Manage the F5 License Proxy (FLP) as an optional, independent phase on an existing cluster: it deploys the f5-license-proxy chart (vault + postgresql + proxy) pulling from the configured registry (Harbor mirror or FAR), and records its root CA + service endpoint so a subsequent BNK install can license in FLP mode. Runs in its own state (state-flp/), separate from cluster/BNK/testing/gateway.

Commands: roksbnkctl flp up Install the F5 License Proxy (needs a cluster) roksbnkctl flp down Remove the F5 License Proxy, leaving the other phases intact

Typical flow (FLP-licensed BNK): roksbnkctl cluster up # or cluster register for an existing cluster roksbnkctl registry replicate # mirror FAR into your registry (optional) roksbnkctl flp up # install the proxy roksbnkctl bnk up # with bnk.license_mode: f5licenseproxy

FLP is opt-in: without it, BNK licenses with a subscription JWT as before.

roksbnkctl flp down

Remove the F5 License Proxy, leaving the other phases

roksbnkctl flp down [flags]

Destroys only the FLP-phase resources (state-flp/), leaving cluster, BNK, testing and gateway intact, and clears flp-outputs.json.

Exits 0 (“nothing to do”) when there’s no FLP state, so it’s safe in a reverse-order teardown of every phase.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl flp

roksbnkctl flp output

Print the FLP phase’s own terraform outputs (text or –json; [name] = one raw value)

roksbnkctl flp output [name] [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

← back to roksbnkctl flp

roksbnkctl flp status

Show the F5 License Proxy’s live status (services, listener, F5/TEEM, CNE fields)

roksbnkctl flp status [flags]

Fetches /api/status from the FLP’s status service (the flp-status container, which runs alongside the proxy on the VSI pod or in the cluster) and renders it.

The service URL is derived from the workspace’s flp-outputs.json (the FLP endpoint host, port 80) unless –url is given. Output honors -o json.

Flags

FlagTypeDefaultDescription
--urlstring—flp-status base URL (default: derived from the FLP endpoint, port 80)

← back to roksbnkctl flp

roksbnkctl flp up

Install the F5 License Proxy (a cluster must exist)

roksbnkctl flp up [flags]

Deploys the F5 License Proxy into the existing cluster (read from cluster-outputs.json) in its own state (state-flp/), and writes flp-outputs.json (root CA + endpoint) for a later bnk up in f5licenseproxy mode.

Refuses when no cluster exists yet.

With –add-node-port-access the proxy is also reachable from OUTSIDE its own cluster, so a BNK install in a DIFFERENT cluster (same VPC, or across a transit gateway) can license through it — a “shared licensing cluster”, where only the cluster running the proxy needs egress to F5. That additionally puts the worker node IPs in the proxy’s server certificate (without them the remote cluster’s controller rejects the TLS handshake) and records an external endpoint in flp-outputs.json. Feed that endpoint + CA to the other workspace via its bnk.flp.external block.

Flags

FlagTypeDefaultDescription
--add-node-port-accessboolfalseexpose the proxy outside its cluster (NodePort + node-IP cert SANs) so a BNK install in another cluster can license through it
--autoboolfalseskip the confirmation prompt before apply
--node-port-source-cidrstringSlice[]with –add-node-port-access: open the NodePort on the worker security group to this CIDR. REPEATABLE — a multi-zone VPC has one address prefix PER ZONE, and a consuming pod scheduled in an unlisted zone is silently dropped. Pass every zone’s CIDR (or a supernet covering them).
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl flp

roksbnkctl gateway

Gateway-phase (data-plane config) lifecycle — optional ingress/egress setup

Manage the BNK data-plane configuration as an optional, independent phase on top of a healthy BNK deployment: the Gateway API objects (GatewayClass, F5BnkGateway, Gateway, HTTPRoute), the egress SnatPool + Egress CRs, the per-zone static routes, and the cluster security-group VXLAN rule. Runs in its own state (state-gateway/), separate from cluster/BNK/testing.

Commands: roksbnkctl gateway up Apply the data-plane config (needs a healthy BNK) roksbnkctl gateway down Remove the data-plane config, leaving cluster/BNK/testing intact

Run this only after roksbnkctl up has brought up the cluster + BNK and the BNK is healthy (TMM pods Ready). The composite up/down never runs this phase — it is opt-in.

roksbnkctl gateway down

Remove the BNK data-plane config, leaving cluster/BNK/testing

roksbnkctl gateway down [flags]

Destroys only the Gateway-phase resources (state-gateway/), leaving the cluster, BNK and testing phases intact.

Exits 0 (“nothing to do”) when there’s no gateway state, so it’s safe in a reverse-order teardown of every phase.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl gateway

roksbnkctl gateway output

Print the Gateway phase’s own terraform outputs (text or –json; [name] = one raw value)

roksbnkctl gateway output [name] [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

← back to roksbnkctl gateway

roksbnkctl gateway status

Runtime status of the Gateway phase (CR readiness + assigned address)

roksbnkctl gateway status [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

← back to roksbnkctl gateway

roksbnkctl gateway up

Apply the BNK data-plane config (BNK must be healthy)

roksbnkctl gateway up [flags]

Applies the Gateway API + SnatPool + Egress + static-route CRs and the VXLAN security-group rule against the existing cluster + BNK (read from cluster-outputs.json). Runs in its own state (state-gateway/).

Refuses when no cluster/BNK exists yet.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt before apply
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl gateway

roksbnkctl get

Get one or more resources (pods, nodes, services, CRDs, …)

roksbnkctl get <resource> [name] [-n <ns> | -A] [-l <selector>] [-o <fmt>] [flags]

Fetches Kubernetes resources via client-go, no host kubectl required.

The resource argument accepts plurals, singulars, and short names from RESTMapper (pods/pod/po, services/svc, deployments/deploy). Multiple types can be comma-separated:

roksbnkctl k get pods,services -n f5-bnk roksbnkctl k get nodes -o yaml roksbnkctl k get pods -A -l app.kubernetes.io/name=f5-lifecycle-operator roksbnkctl k get pod my-pod -n default -o jsonpath=‘{.status.phase}’

CRDs work via dynamic discovery without a hardcoded list — roksbnkctl k get cneinstances resolves the same way kubectl does.

Flags

FlagTypeDefaultDescription
--all-namespaces / -Aboolfalselist across all namespaces
--namespace / -nstring—namespace scope (default: current-context’s namespace)
--output / -ostring—output format: yaml | json | wide | name | jsonpath=… | go-template=…
--selector / -lstring—label selector (e.g. ‘app=foo,tier!=cache’)

roksbnkctl ibmcloud

Passthrough to local ibmcloud with workspace API key + region loaded

roksbnkctl ibmcloud [args...]

roksbnkctl init

Interactive setup; writes the workspace config.yaml

roksbnkctl init [flags]

roksbnkctl init walks through the prompts (region, resource group, cluster, BNK version) and writes ~/.roksbnkctl/<workspace>/config.yaml.

On first run with no -w flag, creates and uses the ‘default’ workspace. Re-run with –upgrade-tf to bump the pinned Terraform source to its latest release.

Flags

FlagTypeDefaultDescription
--config-filestring—path or http(s) URL to a workspace config.yaml to seed (non-interactive when complete; see init example)
--non-interactiveboolfalsebuild config.yaml from environment variables ALONE — no prompts, no –config-file (for argv+env runners; pair with the ROKSBNKCTL_* env vars)
--override-from-envboolfalseafter seeding, overlay config.yaml fields from environment variables (e.g. IBMCLOUD_API_KEY → ibmcloud.api_key_b64)
--tf-sourcestring—override TF source (path or URL); relative local paths are resolved to absolute before being pinned into config.yaml
--upgrade-tfboolfalseresolve and pin the latest TF release into config.yaml

roksbnkctl init example

Print an annotated example config.yaml to stdout (a template, or for piping)

Writes an annotated config.yaml to stdout — the canonical declarative input, with the required fields filled and every optional axis documented (cluster create-or-attach, BYO infrastructure reuse, BNK install, gateway, registry mirror, remote state). config.yaml is the single input to a workspace; the embedded terraform is internal.

Create a starting config or inspect the knobs with ordinary pipes:

roksbnkctl init example > config.yaml roksbnkctl -w demo init –config-file config.yaml roksbnkctl init example | grep -E ‘manifest_version|cluster_vpc’

← back to roksbnkctl init

roksbnkctl install

Copy the running roksbnkctl binary into a directory on PATH

roksbnkctl install [flags]

Install the roksbnkctl binary you’re currently running into a directory on $PATH so you can invoke it as roksbnkctl from any working directory.

Default destination: Linux/macOS, in order of preference: $HOME/.local/bin (preferred — typically writable without sudo) $HOME/bin (older convention; still on PATH for some setups) /usr/local/bin (system-wide; usually needs sudo) Windows: a writable directory already on %PATH% — preferring %LOCALAPPDATA%\Microsoft\WindowsApps (on the per-user PATH by default, no admin) — so the binary resolves immediately. Falls back to %LOCALAPPDATA%\Programs\roksbnkctl (with a PATH hint) if none is usable.

Override the destination with –dir.

Idempotent: if the running binary already lives at the destination, prints a message and exits 0. Use –force to overwrite (useful right after a local rebuild that landed at the install path).

Examples: roksbnkctl install # default — ~/.local/bin roksbnkctl install –dir ~/bin # specific user dir sudo roksbnkctl install –dir /usr/local/bin # system-wide

Note: this is distinct from roksbnkctl self update, which pulls the latest GitHub release tarball over the network.

Flags

FlagTypeDefaultDescription
--dirstring—destination directory (default: a PATH dir — ~/.local/bin on Unix, %LOCALAPPDATA%\Microsoft\WindowsApps on Windows)
--forceboolfalseoverwrite even if destination resolves to the running binary

roksbnkctl journal

Append-only timeline + report for agentic-mode handoffs

Manage the workspace journal (<workspace>/journal/), the append-only timeline the agentic-mode personas use to hand off to one another.

roksbnkctl journal add “<note>” Append a note to today’s journal roksbnkctl journal list List entries chronologically with summaries roksbnkctl journal report Assemble report.md from decisions + journal

roksbnkctl journal add

Append a note to today’s journal entry

roksbnkctl journal add <message>

← back to roksbnkctl journal

roksbnkctl journal list

List journal entries (chronological) with one-line summaries

← back to roksbnkctl journal

roksbnkctl journal report

Assemble report.md from decisions.md + the journal timeline

← back to roksbnkctl journal

roksbnkctl k

Kubernetes verbs (kubectl-internalised; no host kubectl required)

roksbnkctl k <verb> runs the BNK-relevant kubectl/oc verb subset natively in-process via client-go, with no host kubectl/oc binary required. Output formatting matches kubectl byte-for-byte for -o yaml/json/wide/name/jsonpath/go-template.

Verbs: k get list/show resources k describe human-friendly resource detail (delegates to kubectl/pkg/describe) k apply server-side apply for files, dirs, kustomize bases, or stdin k delete delete with cascade + grace period control k logs pod or component logs (extends roksbnkctl logs) k exec exec into a pod via SPDY k port-forward forward a local port to a pod via SPDY

The existing roksbnkctl kubectl / roksbnkctl oc passthroughs remain as escape hatches for verbs not internalised here (edit, patch, rollout, scale, etc.) — they require kubectl/oc on PATH.

roksbnkctl k apply

Server-side apply YAML/JSON manifests, directories, or kustomize bases

roksbnkctl k apply -f <file-or-dir> [-n <ns>] [--force] [flags]

Server-side apply with field-manager ‘roksbnkctl’.

-f <file> single YAML/JSON file (multi-doc YAML supported) -f <dir> directory: kustomization.yaml-detected → krusty build; otherwise recursive *.yaml / *.yml -f - stdin (multi-doc YAML)

–force passes through to SSA’s force-conflicts flag, identical to kubectl apply –server-side –force-conflicts.

Examples:

roksbnkctl k apply -f deploy.yaml -n f5-bnk roksbnkctl k apply -f manifests/ cat deploy.yaml | roksbnkctl k apply -f -

Flags

FlagTypeDefaultDescription
--filename / -fstring—file, directory, or ‘-’ for stdin
--forceboolfalseforce-conflicts on server-side apply (kubectl apply –force-conflicts)
--namespace / -nstring—namespace for namespaced resources without an explicit namespace field

← back to roksbnkctl k

roksbnkctl k delete

Delete resources by name or label selector

roksbnkctl k delete <resource> [name] [-n <ns> | -A] [-l <selector>] [--force] [--grace-period N] [--cascade orphan|background|foreground] [flags]

Deletes resources via the dynamic client. Cascade options match kubectl’s:

–cascade=background delete the object; controller cleans dependents async (default) –cascade=foreground block until dependents are gone –cascade=orphan delete only the object, leave dependents

Examples:

roksbnkctl k delete pod my-pod -n f5-bnk roksbnkctl k delete pods -l app=stale –force –grace-period=0 roksbnkctl k delete deployment foo –cascade=foreground

Flags

FlagTypeDefaultDescription
--all-namespaces / -Aboolfalsedelete across all namespaces
--cascadestringbackgroundcascade: orphan|background|foreground
--forceboolfalseforce-delete: implies –grace-period=0 unless overridden
--grace-periodint-1graceful termination period (seconds); -1 = use resource default
--namespace / -nstring—namespace scope
--selector / -lstring—label selector

← back to roksbnkctl k

roksbnkctl k describe

Show detailed human-readable resource info (events, conditions, related objects)

roksbnkctl k describe <resource> [name] [-n <ns> | -A] [-l <selector>] [flags]

Delegates to k8s.io/kubectl/pkg/describe — the same library kubectl/oc use internally, so output is byte-equivalent.

Examples:

roksbnkctl k describe pod my-pod -n f5-bnk roksbnkctl k describe nodes roksbnkctl k describe deployment f5-lifecycle-operator -n f5-bnk

Flags

FlagTypeDefaultDescription
--all-namespaces / -Aboolfalsedescribe across all namespaces
--namespace / -nstring—namespace scope
--selector / -lstring—label selector
--show-eventsbooltrueinclude the Events block (kubectl default: true)

← back to roksbnkctl k

roksbnkctl k exec

Exec into a pod via SPDY (kubectl-equivalent in-process)

roksbnkctl k exec <pod> [-n <ns>] [-c <container>] [-i] [-t] -- <cmd> [args...] [flags]

Opens an exec stream against the named pod over SPDY. The semantics mirror kubectl exec:

-i / –stdin attach stdin to the remote process -t / –tty allocate a PTY (use for top, bash-style interactive work) -c / –container pick a container in a multi-container pod

Examples:

roksbnkctl k exec my-pod – ls /tmp roksbnkctl k exec my-pod -it – bash roksbnkctl k exec my-pod -c sidecar – cat /etc/hostname

Note: this is the cluster-side exec. The host-side equivalent is ‘roksbnkctl exec <cmd>’ — distinct on purpose (PRD 02 §“Disambiguating roksbnkctl exec”, Option B).

Flags

FlagTypeDefaultDescription
--container / -cstring—container name in a multi-container pod
--namespace / -nstring—namespace scope (default: default)
--stdin / -iboolfalseattach stdin
--tty / -tboolfalseallocate a PTY

← back to roksbnkctl k

roksbnkctl k get

Get one or more resources (pods, nodes, services, CRDs, …)

roksbnkctl k get <resource> [name] [-n <ns> | -A] [-l <selector>] [-o <fmt>] [flags]

Fetches Kubernetes resources via client-go, no host kubectl required.

The resource argument accepts plurals, singulars, and short names from RESTMapper (pods/pod/po, services/svc, deployments/deploy). Multiple types can be comma-separated:

roksbnkctl k get pods,services -n f5-bnk roksbnkctl k get nodes -o yaml roksbnkctl k get pods -A -l app.kubernetes.io/name=f5-lifecycle-operator roksbnkctl k get pod my-pod -n default -o jsonpath=‘{.status.phase}’

CRDs work via dynamic discovery without a hardcoded list — roksbnkctl k get cneinstances resolves the same way kubectl does.

Flags

FlagTypeDefaultDescription
--all-namespaces / -Aboolfalselist across all namespaces
--namespace / -nstring—namespace scope (default: current-context’s namespace)
--output / -ostring—output format: yaml | json | wide | name | jsonpath=… | go-template=…
--selector / -lstring—label selector (e.g. ‘app=foo,tier!=cache’)

← back to roksbnkctl k

roksbnkctl k logs

Stream pod logs (kubectl-equivalent direct path)

roksbnkctl k logs <pod-name> [-n <ns>] [-c <container>] [-f] [--previous] [--since 5m] [--tail N] [flags]

Streams logs for a named pod. Differs from the top-level ‘roksbnkctl logs <component>’ in that this takes a literal pod name — matching kubectl’s surface — while the component variant maps a known BNK component name to a label selector.

Both forms honour -n, -c, -f, –previous, –since, –tail.

Flags

FlagTypeDefaultDescription
--container / -cstring—container name in a multi-container pod
--follow / -fboolfalsefollow log output
--namespace / -nstring—namespace scope (default: default)
--previousboolfalsefetch logs from the previous container instance
--sincestring—only return logs newer than this duration (e.g. 5s, 2m, 1h)
--tailint64-1tail the last N lines (-1 = full log)

← back to roksbnkctl k

roksbnkctl k port-forward

Forward local port(s) to a pod via SPDY

Aliases: port_forward

roksbnkctl k port-forward <pod> [-n <ns>] <local-port>[:<remote-port>] [...] [flags]

Forwards one or more local TCP ports to ports on the named pod. Equivalent to kubectl port-forward; signal handling closes the tunnel cleanly on Ctrl+C.

Port spec:

8080 local 8080 → pod 8080 8080:80 local 8080 → pod 80
80 ephemeral local port → pod 80

Examples:

roksbnkctl k port-forward my-pod 8080:80 roksbnkctl k port-forward my-pod -n f5-bnk 9090:9090 8080:80

Flags

FlagTypeDefaultDescription
--namespace / -nstring—namespace scope (default: default)

← back to roksbnkctl k

roksbnkctl kubeconfig

Print the kubeconfig path (or contents with –export)

roksbnkctl kubeconfig [flags]

Flags

FlagTypeDefaultDescription
--clusterstring—cluster name or ID for –download (default: workspace cluster.name)
--downloadboolfalsefetch admin kubeconfig from IBM Cloud and save to ~/.kube/config
--exportboolfalseprint kubeconfig contents instead of path
--refreshboolfalseforce-refresh the forge kubeconfig now (re-fetch the admin client certs)

roksbnkctl kubectl

Passthrough to local kubectl with workspace KUBECONFIG loaded

roksbnkctl kubectl [args...]

roksbnkctl logs

Tail logs for a BNK component (flo, cis, cert-manager, cneinstance)

roksbnkctl logs <component> [flags]

Looks up the named BNK component, finds its pod(s) by label, and streams logs to stdout. With –follow, streams live. With multiple matching pods, tails the first and prints a hint about using roksbnkctl kubectl for per-pod selection.

The component → namespace/selector map is hardcoded for v1 against the upstream TF chart’s default labels; if your install renamed namespaces or relabelled, fall back to:

roksbnkctl kubectl logs -n <ns> <pod>

Flags

FlagTypeDefaultDescription
--container / -cstring—container name in a multi-container pod
--follow / -fboolfalsefollow log output
--namespace / -nstring—override the component’s default namespace
--previousboolfalsefetch logs from the previous container instance
--sincestring—only return logs newer than this duration (e.g. 5s, 2m, 1h)
--tailint64-1tail the last N lines (-1 = full log)

roksbnkctl oc

Passthrough to local oc with workspace KUBECONFIG loaded

roksbnkctl oc [args...]

roksbnkctl ops

Manage the in-cluster ops pod (k8s execution backend)

roksbnkctl ops manages the long-lived ops pod the k8s execution backend exec’s tools into. The pod runs in the roksbnkctl-ops namespace with a least-privilege ServiceAccount + ClusterRole, and gets its IBM Cloud API key from a Secret apply-time-templated from the workspace credential.

Subcommands: install apply the embedded manifests (idempotent) show print pod + Secret + RBAC status uninstall delete every roksbnkctl.io/managed object created by install

roksbnkctl ops install

Apply (or update) the in-cluster ops fixtures

roksbnkctl ops install [flags]

Applies the embedded namespaces, ServiceAccount, Secret, ClusterRole, ClusterRoleBinding, and ops Pod. Idempotent: re-running with a new API key updates the Secret and rolls the Pod.

Credential mode is selected via –trusted-profile (auto|on|off):

auto (default) — provision an IBM Cloud IAM trusted profile linked to the ops pod’s ServiceAccount when the resolved API key has ‘iam-identity’ perms; otherwise fall back to the static-key Secret with a stderr warning. on — require the trusted-profile path; fail loudly if perms don’t allow. off — skip the trusted-profile path; install the v1.0.x static-key Secret.

Flags

FlagTypeDefaultDescription
--trusted-profilestringautoIBM IAM trusted profile mode: auto (default; provision when perms allow, fall back to static-key Secret), on (require trusted profile), off (static-key Secret only)

← back to roksbnkctl ops

roksbnkctl ops show

Print the ops pod’s status, image, RBAC subject, and Secret rotation timestamp

← back to roksbnkctl ops

roksbnkctl ops uninstall

Delete the ops fixtures (namespaces, RBAC, Pod, Secret)

roksbnkctl ops uninstall [flags]

Flags

FlagTypeDefaultDescription
--confirmboolfalseactually perform the uninstall (otherwise prints what would be deleted)

← back to roksbnkctl ops

roksbnkctl output

Print the merged outputs across all phases (cluster + bnk + testing + gateway + flp)

roksbnkctl output [name] [flags]

Print the union of every phase’s own outputs — each read from its owning phase’s state, so values are the populated ones and never conflict. This is the “everything” view; the per-phase <phase> output commands scope to just that phase’s managed attributes.

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

roksbnkctl plan

Read-only; show what roksbnkctl up would change

roksbnkctl plan [flags]

Flags

FlagTypeDefaultDescription
--outstring—save the plan to <file> (binary plan + a readable <file>.txt) for later apply --plan
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

roksbnkctl registry

Air-gap registry mirror — replicate BNK artifacts into a private registry (PRD 11)

Manage the air-gap registry mirror: replicate every chart + image a BNK install needs (the f5-bigip-k8s-manifest set plus the non-F5 dependencies) from the F5 Artifact Repository (repo.f5.com) into a private target — IBM Container Registry (ICR) or a generic OCI registry (Artifactory / Harbor / Quay) — so an air-gapped cluster installs BNK from a registry it controls.

Commands: roksbnkctl registry target Show or set the mirror target (icr|generic) roksbnkctl registry bom Build + print the bill-of-materials roksbnkctl registry list List the artifacts the last replicate recorded roksbnkctl registry diff Show what replicate would copy (BOM vs. mirror) roksbnkctl registry replicate Copy the BOM into the mirror (registry-to-registry; no cluster) roksbnkctl registry verify Confirm every BOM artifact is present + digest-matched roksbnkctl registry prune Remove mirrored artifacts no longer in the BOM roksbnkctl registry delete Delete ALL replicated artifacts from the target

registry bom works entirely offline against the FAR manifest. The other verbs need a configured registry: block and network reachability to the target registry — replicate also needs the FAR source (repo.f5.com). NONE require a Kubernetes cluster: replicate copies registry-to-registry (via go-containerregistry) from wherever roksbnkctl runs, so you can pre-seed the mirror as a standalone supply-chain step before any cluster exists.

roksbnkctl registry adopt

Record a mirror this workspace did not populate, so bnk up can use it

roksbnkctl registry adopt [flags]

Writes registry-mirror.json for a mirror that already exists.

bnk up refuses to render against a mirror the workspace has no record of — otherwise BNK would be pointed at far_repo_url, which an air-gapped cluster cannot reach. Until now only registry replicate wrote that record, which means a workspace could only use a mirror it had populated itself.

That is the wrong constraint for how mirrors are actually used. The registry is filled once, as a supply-chain step, and then many installs pull from it — often from a different workspace, a different host, or a different team. Those installs were forced to re-run replicate purely to re-derive a record, which needs the FAR source reachable at install time. An air-gapped operator frequently does not have that, and it is the whole point of having mirrored in the first place.

adopt derives the record from the configured registry target: the chart and image hosts, the repo namespace, the manifest version, and the mirror CA all come from the workspace config, so no source access is needed. It then asks the MIRROR what it holds under the configured prefix — a sanity check that catches a typo in the prefix or an empty registry, without pretending to prove the contents are correct.

Pass –verify-contents when the source IS reachable and you want proof rather than assertion: it builds the BOM and digest-checks every artifact before recording, and the record then carries the full artifact inventory.

Flags

FlagTypeDefaultDescription
--forceboolfalserecord the mirror even when it holds nothing under the configured prefix
--verify-contentsboolfalsedigest-check every BOM artifact before recording (needs the FAR source)

← back to roksbnkctl registry

roksbnkctl registry bom

Build + print the BNK bill-of-materials from the FAR manifest

roksbnkctl registry bom [flags]

Pulls the f5-bigip-k8s-manifest for the configured BNK release, parses it into the full artifact set (charts + images), unions the non-F5 dependencies, and prints the resulting BOM. Needs no target — it only reads from FAR.

Flags

FlagTypeDefaultDescription
--far-repo-urlstring—FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com)
--include-depsboolfalseforce-include the non-F5 dependency artifacts (cert-manager, node-labeler)
--jsonboolfalseemit the BOM as JSON (overrides –output)
--manifest-versionstring—BNK manifest version (default: workspace bnk.manifest_version)
--no-include-depsboolfalseexclude the non-F5 dependency artifacts
--source-sa-b64string—FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64)

← back to roksbnkctl registry

roksbnkctl registry delete

Delete ALL replicated artifacts from the target registry

roksbnkctl registry delete [flags]

Removes every artifact roksbnkctl replicated (recorded in registry-mirror.json) from the configured target, then clears the mirror record so the BNK install reverts to pulling from FAR. Destructive — pass –force to skip the confirmation.

Deletion is by digest where recorded (the reliable form for a registry manifest DELETE). Artifacts that fail to delete are kept in the record so a re-run retries them. For target=icr the API key needs Manager (delete) rights on the namespace; for target=generic the registry must have deletes enabled.

Flags

FlagTypeDefaultDescription
--forceboolfalseskip the confirmation prompt
--targetstring—mirror target backend: icr|generic (default: workspace registry.target, else “icr”)

← back to roksbnkctl registry

roksbnkctl registry diff

Show BOM vs. mirror drift (what replicate would copy)

roksbnkctl registry diff [flags]

Flags

FlagTypeDefaultDescription
--far-repo-urlstring—FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com)
--include-depsboolfalseforce-include the non-F5 dependency artifacts (cert-manager, node-labeler)
--manifest-versionstring—BNK manifest version (default: workspace bnk.manifest_version)
--no-include-depsboolfalseexclude the non-F5 dependency artifacts
--source-sa-b64string—FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64)

← back to roksbnkctl registry

roksbnkctl registry list

List artifacts currently recorded in the mirror

Lists the artifacts the last replicate recorded in registry-mirror.json.

← back to roksbnkctl registry

roksbnkctl registry prune

Remove mirrored artifacts no longer in the BOM

roksbnkctl registry prune [flags]

Flags

FlagTypeDefaultDescription
--far-repo-urlstring—FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com)
--include-depsboolfalseforce-include the non-F5 dependency artifacts (cert-manager, node-labeler)
--manifest-versionstring—BNK manifest version (default: workspace bnk.manifest_version)
--no-include-depsboolfalseexclude the non-F5 dependency artifacts
--source-sa-b64string—FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64)
--targetstring—mirror target backend: icr|generic (default: workspace registry.target, else “icr”)

← back to roksbnkctl registry

roksbnkctl registry replicate

Copy the BOM into the mirror (registry-to-registry; no cluster needed)

roksbnkctl registry replicate [flags]

Prepares the target registry (auth + repository namespace), then copies every BOM artifact into it, idempotently. Records the result in registry-mirror.json so the BNK install can be redirected to the mirror.

Runs entirely host-side: it pulls each artifact by digest from the FAR source (repo.f5.com) and pushes to the target registry via go-containerregistry — no Kubernetes cluster is involved. So you can pre-seed the mirror as a standalone supply-chain step, before creating any cluster, from any host that can reach both the FAR source and the target registry. Requires a configured registry: block and the FAR source credential (registry.source_service_account_b64, the workspace FAR auth, or –source-sa-b64).

Flags

FlagTypeDefaultDescription
--concurrencyint0parallel copy workers (default: 4)
--far-repo-urlstring—FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com)
--include-depsboolfalseforce-include the non-F5 dependency artifacts (cert-manager, node-labeler)
--insecure-capture-caboolfalseadopt a self-signed mirror CA over an UNAUTHENTICATED connection (trust-on-first-use); prefer –registry-ca or –registry-ca-fingerprint
--manifest-versionstring—BNK manifest version (default: workspace bnk.manifest_version)
--no-include-depsboolfalseexclude the non-F5 dependency artifacts
--registry-castring—PEM CA the mirror serves TLS with, for air-gap node trust (preferred: the file you generated; else registry.generic_ca_b64)
--registry-ca-fingerprintstring—expected SHA-256 of the mirror CA (“sha256:ab:cd…” or bare hex), authenticating a captured CA out of band
--source-sa-b64string—FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64)
--targetstring—mirror target backend: icr|generic (default: workspace registry.target, else “icr”)

← back to roksbnkctl registry

roksbnkctl registry target

Show or set the registry mirror target and its fields

roksbnkctl registry target [icr|generic | <field> <value>] [flags]

Configure the registry replication target without hand-editing config.yaml.

With no arguments, prints the current target + configured fields. Otherwise the first argument is either a backend KIND (sets registry.target) or a FIELD name (set with a following value):

Kinds: icr | generic Fields: icr_host icr_namespace generic_host generic_repo_prefix generic_username generic_password generic_ca (a PEM file) generic_ca_sha256

Examples: roksbnkctl registry target # show current config roksbnkctl registry target icr # use IBM Container Registry roksbnkctl registry target icr_namespace bnk-test roksbnkctl registry target generic # use a generic OCI registry roksbnkctl registry target generic_host art.example.com roksbnkctl registry target generic_repo_prefix bnk roksbnkctl registry target generic_username ci-bot echo “$TOKEN” | roksbnkctl registry target generic_password –password-stdin roksbnkctl registry target generic_ca /opt/harbor/certs/harbor.crt

Flags

FlagTypeDefaultDescription
--password-stdinboolfalseread the generic registry password from stdin (for registry target generic_password)

← back to roksbnkctl registry

roksbnkctl registry verify

Confirm every BOM artifact is present + digest-matched in the mirror

roksbnkctl registry verify [flags]

Flags

FlagTypeDefaultDescription
--far-repo-urlstring—FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com)
--include-depsboolfalseforce-include the non-F5 dependency artifacts (cert-manager, node-labeler)
--manifest-versionstring—BNK manifest version (default: workspace bnk.manifest_version)
--no-include-depsboolfalseexclude the non-F5 dependency artifacts
--source-sa-b64string—FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64)
--targetstring—mirror target backend: icr|generic (default: workspace registry.target, else “icr”)

← back to roksbnkctl registry

roksbnkctl self

Manage the roksbnkctl binary itself

roksbnkctl self update

Pull the latest roksbnkctl release matching the host arch

Downloads the latest GitHub release for this platform, verifies its SHA256 against the release’s checksums.txt, and replaces the running binary in place. Works on Linux, macOS, and Windows.

This is the latest-only, interactive form; use roksbnkctl upgrade to pin a specific --version or to skip the prompt with --yes.

Requires write permission on the binary’s directory (typical install under /usr/local/bin needs sudo; brew/scoop should use their own upgrade verb).

← back to roksbnkctl self

roksbnkctl shell

Interactive bash with KUBECONFIG, IBMCLOUD_API_KEY, and region pre-loaded

roksbnkctl shell drops into a $SHELL subshell with the workspace’s KUBECONFIG, IBMCLOUD_API_KEY, IC_API_KEY, and IBMCLOUD_REGION exported so locally-installed kubectl / oc / ibmcloud commands work without further setup. Exits when the subshell does.

roksbnkctl state

Manage where terraform state lives (local vs COS/S3 remote backend)

roksbnkctl state local

Use local per-phase terraform state (the default) — writes config.yaml for you

← back to roksbnkctl state

roksbnkctl state migrate

Copy each phase’s local terraform state into the configured COS/S3 backend

roksbnkctl state migrate [flags]

Migrates a workspace’s terraform state from local files into the COS/S3 remote backend declared in config.yaml’s state: block (PRD 16).

Pre-requisite: set state.backend = “s3” (+ state.s3.{endpoint,bucket,region}) and export the COS HMAC keys (ROKSBNKCTL_COS_HMAC_ACCESS_KEY / ROKSBNKCTL_COS_HMAC_SECRET_KEY, or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) before running.

For each deployed phase (cluster / bnk / testing / gateway), this runs terraform init -migrate-state to copy its local state to the per-phase key in the bucket. It refuses to overwrite a key that already holds state (pass –force to override). The local state files are left in place; verify the remote read-back before deleting them.

Flags

FlagTypeDefaultDescription
--forceboolfalsemigrate even if the remote key already holds state (overwrites it)

← back to roksbnkctl state

roksbnkctl state s3

Use the COS/S3 remote terraform-state backend — writes the state: block for you

roksbnkctl state s3 [flags]

Switch this workspace to the COS/S3 remote state backend (PRD 16) by writing its state: block to config.yaml — no hand-edit.

You still provision the bucket + HMAC credentials yourself: the HMAC access/ secret keys are NEVER written to config.yaml — only the names of the env vars they come from are (–access-key-source / –secret-key-source, defaulting to ROKSBNKCTL_COS_HMAC_ACCESS_KEY / ROKSBNKCTL_COS_HMAC_SECRET_KEY). After this, export those env vars and run roksbnkctl state migrate to move existing state.

Flags

FlagTypeDefaultDescription
--access-key-sourcestring—env var holding the HMAC access key (default ROKSBNKCTL_COS_HMAC_ACCESS_KEY)
--bucketstring—pre-provisioned bucket name (required)
--endpointstring—COS S3 endpoint URL (required)
--key-prefixstring—state key prefix (default: the workspace name)
--regionstring—COS location / region (required)
--secret-key-sourcestring—env var holding the HMAC secret key (default ROKSBNKCTL_COS_HMAC_SECRET_KEY)

← back to roksbnkctl state

roksbnkctl state show

Show the workspace’s terraform-state backend config

← back to roksbnkctl state

roksbnkctl status

Summary of the workspace: cluster, components, last apply

roksbnkctl status [flags]

roksbnkctl status reports a quick read of the workspace:

  • workspace name + region
  • configured cluster name
  • pinned Terraform source
  • per-phase deployment status (Cluster, BNK trial, Testing, Gateway)
  • kubeconfig path (if any)
  • cluster reachability (node count + ready count)

v1.x will add per-BNK-component readiness (flo, cis, cert-manager, cneinstance) once the component-discovery shape is finalised.

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

roksbnkctl targets

Manage SSH targets used by –on

Targets are named SSH endpoints stored under the workspace’s targets: block. They become reachable via the persistent –on flag on commands like roksbnkctl exec, roksbnkctl shell, roksbnkctl kubectl, etc.

A jumphost target is auto-populated after a successful roksbnkctl up when the upstream HCL provisions one (testing_tgw_jumphost outputs).

roksbnkctl targets add

Add or update a target

roksbnkctl targets add <name> --host H --user U [--port P] [--key-path P | --key-source S] [flags]

Flags

FlagTypeDefaultDescription
--hoststring—host or IP
--key-pathstring—path to a PEM private key
--key-sourcestring—key source — “agent” or “tf-output:<name>”
--portint0ssh port (default 22)
--userstring—remote user

← back to roksbnkctl targets

roksbnkctl targets list

List all targets in the current workspace

← back to roksbnkctl targets

roksbnkctl targets remove

Remove a target

roksbnkctl targets remove <name>

← back to roksbnkctl targets

roksbnkctl targets show

Show detail for one target

roksbnkctl targets show <name>

← back to roksbnkctl targets

roksbnkctl terraform

Read-only passthrough to terraform against the workspace’s managed state

Aliases: tf

roksbnkctl terraform [subcommand] [args...]

roksbnkctl terraform runs a READ-ONLY terraform subcommand against the workspace’s managed state, with terraform’s working directory and TF_DATA_DIR resolved for you (no need to cd into ~/.roksbnkctl/… or export TF_DATA_DIR).

This command is read-only by allowlist. Permitted subcommands: output, show, state list, state show, state pull, providers, version, graph, validate, fmt -check

Everything else — including apply, destroy, init, plan, import, taint, untaint, state rm/mv/replace-provider, and any -auto-approve — is rejected before terraform runs. Mutations go exclusively through roksbnkctl up / plan / apply / down (or cluster/bnk up/down); running terraform apply/destroy outside the orchestration skips the rendered tfvars, the apply-retry wrapper, the post-apply kubeconfig fetch, the applied-tfvars snapshot, and the auto-jumphost seeding, and desyncs the managed state.

Use –phase cluster to target the cluster-phase state (/.roksbnkctl/<ws>/state-cluster/); the default is the trial/single state (/.roksbnkctl/<ws>/state/). –on is not supported: the managed terraform state lives on this workstation, not on a jumphost.

Examples: roksbnkctl terraform output testing_cluster_jumphost_ssh_commands roksbnkctl terraform state list roksbnkctl –phase cluster terraform show

roksbnkctl test

Run deployment validation tests (default: all)

roksbnkctl test [suite] [flags]

roksbnkctl test runs deployment validation against the current workspace.

Suites: connectivity HTTP/HTTPS reachability of deployed BNK services dns DNS resolution of ingress and service hostnames throughput iperf3 measurements (north-south by default; v1.x) all run all of the above (default if no suite is specified)

Honors -o json with the roksbnkctl.v1 schema. Exit code 0 on all-pass, non-zero on any-fail — CI-friendly.

Flags

FlagTypeDefaultDescription
--insecureboolfalseskip TLS certificate validation (connectivity only)

roksbnkctl test connectivity

HTTP/HTTPS reachability against configured hosts

← back to roksbnkctl test

roksbnkctl test dns

DNS resolution probe (single-vantage, GSLB-compare, or workspace-driven)

roksbnkctl test dns [flags]

roksbnkctl test dns runs DNS probes against configured resolvers.

Two modes:

Workspace-driven (no flags) — resolves each host listed under test.connectivity.extra_hosts via the std-lib resolver. Same as Sprint 0–4 behaviour; preserves CI invocations using the legacy roksbnkctl.v1 schema.

Flag-driven (any of –target/–type/–server/–gslb-compare set) — uses the embedded miekg/dns probe (no external dig install needed). Single-vantage emits roksbnkctl.dns.v1.vantage; –gslb-compare emits roksbnkctl.dns.v1 with a gslb_divergence boolean across all configured backends (local + k8s + ssh:<targets>).

Use –backend local|k8s|ssh:<target> to pick a single vantage point; –gslb-compare fans out across all available vantages. PRD 03 §“DNS probe (GSLB-aware)”.

Flags

FlagTypeDefaultDescription
--gslb-compareboolfalsefan out the probe across all configured backends (local + k8s + ssh:<targets>) and emit a comparison JSON with gslb_divergence
--iterationsint1number of repeated queries; >1 enables RTT distribution
--require-divergenceboolfalsewith –gslb-compare: exit non-zero if NO divergence is observed (CI assertion that GSLB is doing something)
--serverstring—resolver: <ip>[:<port>] | system | cluster | <named-from-workspace> (default: system)
--targetstring—DNS name to query (overrides workspace test.dns.default_target)
--timeoutduration2sper-query timeout
--typestringArecord type: A | AAAA | CNAME | MX | NS | TXT | SRV | SOA | PTR | CAA | DS | DNSKEY | ANY

← back to roksbnkctl test

roksbnkctl test hosts

Manage test.connectivity.extra_hosts in the workspace config

Test hosts are URLs probed by roksbnkctl test connectivity and (in workspace-driven mode) roksbnkctl test dns. They are stored under test.connectivity.extra_hosts in the workspace’s config.yaml.

This command group is the first-class CLI for managing that slice — without it, the only path is hand-editing ~/.roksbnkctl/<workspace>/config.yaml. Mirrors roksbnkctl targets’ ergonomics: idempotent add/remove, -o json on list.

← back to roksbnkctl test

roksbnkctl test hosts add

Append URLs to test.connectivity.extra_hosts (idempotent)

roksbnkctl test hosts add <url> [<url> ...]

Appends each <url> to test.connectivity.extra_hosts. Idempotent — adding an already-present URL is a no-op (logs to stderr; exit 0).

Each <url> is validated via the std-lib url.Parse; non-URLs are rejected with an actionable error naming the offending arg. Insertion order is preserved.

← back to roksbnkctl test hosts

roksbnkctl test hosts clear

Remove ALL entries from test.connectivity.extra_hosts

roksbnkctl test hosts clear [flags]

Clears test.connectivity.extra_hosts. Confirmation prompt defaults to No; pass --auto to skip the prompt (matches the roksbnkctl down / cluster down confirmation pattern).

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt

← back to roksbnkctl test hosts

roksbnkctl test hosts list

List configured test hosts (one per line; -o json for array)

Prints the workspace’s test.connectivity.extra_hosts one per line on stdout. Empty list emits zero bytes + exit 0 (NOT an error; distinguishes “nothing configured” from “command failed” by exit code).

With -o json, emits the slice as a JSON array ([] when empty).

← back to roksbnkctl test hosts

roksbnkctl test hosts remove

Remove URLs from test.connectivity.extra_hosts (idempotent)

roksbnkctl test hosts remove <url> [<url> ...]

Removes each <url> from test.connectivity.extra_hosts. Idempotent — removing an absent URL is a no-op (logs to stderr; exit 0). Preserves the order of remaining entries.

← back to roksbnkctl test hosts

roksbnkctl test list

List available test suites

← back to roksbnkctl test

roksbnkctl test matrix

Run the declarative BNK-on-ROKS performance grid (iperf3 L4 + h2load L7)

roksbnkctl test matrix [flags]

roksbnkctl test matrix runs a declarative performance grid against an already-deployed cluster + BNK. It reads a matrix.yaml describing cells (endpoint-pair × test-family) and runs each, emitting a report shaped like the BNK-on-ROKS perf plan.

Two families: iperf3 — L4 TCP throughput over an L4Route VIP, with content-size knobs (length: “128” vs “512K”) — the L4 analog of the plan’s 128 B / 512 KB payload axis. l7 — h2load against an HTTPRoute, http and https (TLS terminate at TMM); cps / tps / throughput modes.

The locality axis (same-zone / different-zone / different-VPC) is implicit in which jumphost (“vsi”) endpoint a cell names as its client, so the per-AZ jumphost targets the Testing phase auto-registers (jumphost, jumphost-<zone>) are the traffic-source fleet. The Testing phase preinstalls both generators (iperf3 + h2load/nghttp2-client) on every jumphost, so the ssh runs need no –bootstrap.

This command provisions only ephemeral, runner-owned fixtures (an iperf3 server, an HTTP file backend, and optional L4Route/HTTPRoute/TLS objects that attach to the EXISTING Gateway by name) and tears them down after (unless –keep). It never touches Terraform or the gateway-phase objects.

roksbnkctl test matrix –dry-run expand + print the plan, no cluster calls roksbnkctl test matrix –only ‘L7*’ run a subset (glob on cell name) roksbnkctl test matrix -o md Markdown grid report

Honors -o json|text|md with the roksbnkctl.v1 schema. Exit code is non-zero if any cell fails.

Flags

FlagTypeDefaultDescription
--dry-runboolfalseexpand the grid and print the plan + fixtures; no cluster calls
--filestring—path to matrix.yaml (default: <workspace>/matrix.yaml, then ./matrix.yaml)
--keepboolfalseleave fixtures running after the run
--onlystring—glob on cell name; run only matching cells

← back to roksbnkctl test

roksbnkctl test throughput

iperf3 throughput; deploys server pod automatically (v1.x)

roksbnkctl test throughput [flags]

Deploys an iperf3 server in the test namespace and runs the client either from the roksbnkctl host (–mode north-south, default) or from a second in-cluster pod (–mode east-west).

Not yet implemented — landing in v1.x once the internal/k8s client-go fixture lifecycle is wired.

Flags

FlagTypeDefaultDescription
--cross-nodeboolfalseforce east-west client and server onto different nodes
--keepboolfalseleave the iperf3 server pod running after the test
--modestringnorth-souththroughput mode: north-south | east-west

← back to roksbnkctl test

roksbnkctl testing

Testing-phase (jumphost) lifecycle — provisions the test rig

Manage the testing jumphost infrastructure (TGW jumphost, per-AZ cluster jumphosts, client VPC) as an independent phase that sits beside the BNK phase on top of a shared cluster. Pure IBM VPC — no Kubernetes.

Commands: roksbnkctl testing up Provision the jumphosts (needs a cluster: VPC + transit gateway) roksbnkctl testing down Destroy the jumphosts, leaving the cluster and BNK intact roksbnkctl testing status Live jumphost IPs / SSH commands + reachability

This is the provisioning phase. To RUN connectivity/DNS/throughput probes against a deployed environment, use roksbnkctl test (and roksbnkctl test hosts to manage the probe target list) — those provision nothing.

roksbnkctl testing down

Destroy the testing jumphosts, leaving the cluster and BNK

roksbnkctl testing down [flags]

Destroys only the testing jumphost resources (state-testing/), leaving the cluster phase and the BNK phase intact. The inverse of bnk down: each phase tears down independently. Exits 0 (“nothing to do”) when there’s no testing state, so it’s safe in a reverse-order teardown of every phase.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl testing

roksbnkctl testing output

Print the Testing phase’s own terraform outputs (text or –json; [name] = one raw value)

roksbnkctl testing output [name] [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)
--show-sensitiveboolfalsereveal sensitive output values (default redacted)

← back to roksbnkctl testing

roksbnkctl testing status

Live runtime status of the Testing phase (jumphost IPs + SSH reachability)

roksbnkctl testing status [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseoutput JSON (CI-friendly)

← back to roksbnkctl testing

roksbnkctl testing up

Provision the testing jumphosts (cluster must exist)

roksbnkctl testing up [flags]

Provisions the testing jumphosts against the existing cluster’s VPC + transit gateway (read from cluster-outputs.json). Runs in its own state (state-testing/), independent of the BNK phase — bnk down leaves the jumphosts and testing down leaves BNK.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt before apply
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl testing

roksbnkctl tfvars

Emit the upstream TF’s terraform.tfvars.example for editing

roksbnkctl tfvars [flags]

Resolves the workspace’s pinned TF source (downloading the tarball if not yet cached) and writes its terraform.tfvars.example as a starting point you can edit and pass to roksbnkctl up.

Default writes to ./terraform.tfvars in the current directory. Pass -o <path> to write elsewhere, or -o - to print to stdout.

Refuses to overwrite an existing destination unless –force is set.

Workflow: roksbnkctl init # pins a TF source roksbnkctl tfvars # writes ./terraform.tfvars from the upstream example $EDITOR ./terraform.tfvars roksbnkctl up –var-file ./terraform.tfvars

Flags

FlagTypeDefaultDescription
--forceboolfalseoverwrite the destination if it already exists
--output / -ostring./terraform.tfvarsdestination file (or - for stdout)

roksbnkctl tgw

Attach the cluster to an existing Transit Gateway (share one across clusters)

Connect this workspace’s cluster VPC to an EXISTING IBM Transit Gateway, by name or id — at create time or after. Multiple workspaces can point at the same gateway; each owns its own connection.

Commands: roksbnkctl tgw connect <name-or-id> Attach the cluster VPC to the gateway roksbnkctl tgw disconnect Detach (leaves the gateway + other clusters) roksbnkctl tgw status Gateway id/name + live connection state

Runs in its own state (state-tgw/), separate from cluster/BNK/testing/gateway/FLP, and works against a created OR a registered cluster.

roksbnkctl tgw connect

Attach the cluster VPC to an existing Transit Gateway

roksbnkctl tgw connect [transit-gateway-name-or-id] [flags]

Attaches this workspace’s cluster VPC to an existing Transit Gateway.

The gateway may be given by NAME or by ID — either is resolved against your account. Pass it as the argument (persisted to config for later re-applies), or set resources.transit_gateway (create: false, existing: <name-or-id>) in config.yaml / the init interview.

Idempotent and shareable: run it in several workspaces with the same gateway and each cluster gets its own connection to the one gateway.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt before apply
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl tgw

roksbnkctl tgw disconnect

Detach the cluster VPC from its Transit Gateway

roksbnkctl tgw disconnect [flags]

Removes ONLY this cluster’s connection to the Transit Gateway. The gateway itself and every other cluster’s connection to it are left intact.

Exits 0 (“nothing to do”) when there’s no connection.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the destroy confirmation
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

← back to roksbnkctl tgw

roksbnkctl tgw status

Show the Transit Gateway id/name and the live connection state

← back to roksbnkctl tgw

roksbnkctl uninstall

Remove the installed roksbnkctl binary from ~/.local/bin (opposite of install)

roksbnkctl uninstall [flags]

Delete the roksbnkctl binary that roksbnkctl install copied onto $PATH.

By default it removes <install-dir>/roksbnkctl, where <install-dir> is the same directory install uses (~/.local/bin, then ~/bin). Override with –dir.

It refuses to delete the binary you are currently running on Windows (a running .exe cannot be removed there) — delete it manually or run uninstall from a different binary. On Linux/macOS removing the running (installed) binary is fine.

Examples: roksbnkctl uninstall # remove ~/.local/bin/roksbnkctl roksbnkctl uninstall –dir ~/bin sudo roksbnkctl uninstall –dir /usr/local/bin

Flags

FlagTypeDefaultDescription
--dirstring—directory to remove roksbnkctl from (default: ~/.local/bin or ~/bin)
--yes / -yboolfalseskip the confirmation prompt

roksbnkctl up

Provision (or attach) and deploy BNK — terraform plan + apply

roksbnkctl up [flags]

roksbnkctl up validates credentials, resolves the pinned Terraform source, runs plan, and (after confirmation, unless –auto) applies. Idempotent and resumable: a partial failure is recovered by re-running ‘roksbnkctl up’.

Flags

FlagTypeDefaultDescription
--autoboolfalseskip the confirmation prompt before apply
--no-kubeconfigboolfalseskip the post-apply admin kubeconfig fetch
--tf-sourcestring—override TF source for this run only (path or URL; relative local paths resolved against the invocation CWD)
--var-filestringArray[]extra TF var-file (repeatable; later files override earlier)

roksbnkctl upgrade

Upgrade (or pin) the roksbnkctl binary to a GitHub release

roksbnkctl upgrade [flags]

Downloads a roksbnkctl release for this OS/arch from GitHub, verifies its SHA256 against the release’s checksums.txt, and replaces the running binary in place. With no –version it upgrades to the latest release; –version pins a specific release (and may downgrade or reinstall).

Works on Linux, macOS, and Windows. On Windows the running .exe cannot be overwritten, so it is moved aside to <binary>.old and the new binary takes its place; the .old file is removed automatically on the next run.

Requires write permission on the binary’s directory (a /usr/local/bin install needs sudo; Homebrew/Scoop installs should use their own upgrade verb).

Note: release binaries are not yet code-signed, so on a host with an application-allowlist policy (e.g. Windows Device Guard/WDAC) the freshly downloaded binary may be blocked until its hash is trusted.

Flags

FlagTypeDefaultDescription
--versionstring—release to install, e.g. v1.20.1 (default: latest)
--yes / -yboolfalseskip the confirmation prompt

roksbnkctl version

Print version, commit, and build date

roksbnkctl workspaces

Manage roksbnkctl workspaces (per-environment config + state bundles)

Aliases: ws

Each workspace lives under ~/.roksbnkctl/<name>/ with its own config.yaml and state. The current_workspace pointer in ~/.roksbnkctl/config.yaml decides which one commands run against; -w/–workspace overrides for one invocation.

roksbnkctl workspaces current

Print the current workspace name

← back to roksbnkctl workspaces

roksbnkctl workspaces delete

Delete a workspace (refuses if state is non-empty unless –force)

roksbnkctl workspaces delete <name> [flags]

Flags

FlagTypeDefaultDescription
--forceboolfalsedelete even if Terraform state lists provisioned resources

← back to roksbnkctl workspaces

roksbnkctl workspaces list

List workspaces and their states

← back to roksbnkctl workspaces

roksbnkctl workspaces new

Create a new (empty) workspace skeleton — run roksbnkctl init -w <name> to populate

roksbnkctl workspaces new <name>

← back to roksbnkctl workspaces

roksbnkctl workspaces use

Set the current workspace pointer

roksbnkctl workspaces use <name>

← back to roksbnkctl workspaces