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.
| Flag | Type | Default | Description |
|---|---|---|---|
--backend | string | — | execution backend: local | docker | k8s | ssh:<target> (default: per-tool from workspace exec: block, else local) |
--bootstrap | bool | false | for –backend ssh:<target>: auto-install missing tools on Ubuntu via apt-get (requires passwordless sudo on the target) |
--insecure-host-key | bool | false | skip the host-key TOFU prompt; record on first contact (CI use) |
--no-color | bool | false | disable colored output |
--on | string | — | run on the named SSH target instead of locally (roksbnkctl targets list to see options) |
--output / -o | string | text | output format: text | json |
--quiet / -q | bool | false | suppress all but errors |
--verbose / -v | bool | false | verbose output |
--workspace / -w | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--show | bool | false | print 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):
- environment — IBMCLOUD_API_KEY / IC_API_KEY / TF_VAR_* (including any loaded from $PWD/.env, which roksbnkctl reads at startup)
- OS keychain (service “roksbnkctl”, account “
<workspace>/ibmcloud_api_key”) - 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt |
--no-kubeconfig | bool | false | skip the post-apply admin kubeconfig fetch |
--plan | string | — | apply exactly this saved plan file (from plan --out) instead of re-planning |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip confirmation prompts (cluster-bootstrap + apply) |
--no-kubeconfig | bool | false | skip the post-apply admin kubeconfig fetch |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--forge-ca | string | — | PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure) |
--insecure | bool | false | DISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca |
--project | string | — | target BNK Forge project name (ensured-or-created) |
--url | string | — | BNK Forge server URL (e.g. https://forge.example.com) |
--username | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | take over a cluster registered to ANOTHER Forge project (moves it, and its cluster id changes) |
--forge-ca | string | — | PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure) |
--insecure | bool | false | DISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca |
--password | string | — | BNK Forge password (prefer BNK_FORGE_PASSWORD env or the prompt) |
--project | string | — | target BNK Forge project name (overrides config) |
--url | string | — | BNK Forge server URL (overrides config) |
--username | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--expect-fingerprint | string | — | SHA256 fingerprint the key must match (e.g. the VPC key’s) — a credential that cannot log in is worse than none |
--forge-ca | string | — | PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure) |
--host | string | — | address FORGE reaches the appliance on — the FLOATING IP, not the endpoint flp status prints |
--insecure | bool | false | DISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca |
--key | string | — | PRIVATE key file Forge will use (unencrypted; Forge stores it and cannot prompt) |
--name | string | — | credential name in Forge (default: <project>-ssh) |
--password | string | — | BNK Forge password (prefer BNK_FORGE_PASSWORD env or the prompt) |
--port | int | 22 | SSH port on the appliance |
--project | string | — | BNK Forge project to attach the credential to |
--ssh-username | string | ubuntu | SSH user on the appliance |
--url | string | — | BNK Forge server URL (overrides config) |
--username | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--forge-ca | string | — | PEM file holding the CA the Forge server’s certificate must chain to (pins a self-signed lab cert; supersedes –insecure) |
--insecure | bool | false | DISABLE TLS verification — the API token is then sent over an unauthenticated connection; prefer –forge-ca |
--password | string | — | BNK Forge password (prefer BNK_FORGE_PASSWORD) |
--project | string | — | BNK Forge project holding the cluster |
--url | string | — | BNK Forge base URL |
--username | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--all-regions | bool | false | sweep every IBM Cloud region (slower; catches resources in regions not recorded in config) |
--auto / -y | bool | false | skip the confirmation prompt |
--dry-run | bool | false | list orphaned resources without deleting |
--region | stringSlice | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal 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
| Flag | Type | Default | Description |
|---|---|---|---|
--prompt | bool | false | prompt for the cluster name even if one is given as an argument |
--registry-cos-name | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt before apply |
--no-kubeconfig | bool | false | skip the post-apply admin kubeconfig fetch |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--from-env | string | — | read settings from a .env file and print the populated equivalent (no comments) |
--from-yaml | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--from-env | string | — | read settings from a .env file and print the populated equivalent (no comments) |
--from-yaml | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--instance | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--class | string | standard | storage class (standard, vault, cold, smart) |
--region | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--no-clobber | bool | false | skip 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
| Flag | Type | Default | Description |
|---|---|---|---|
--plan | string | standard | service plan name (standard | lite) |
--plan-id | string | — | service plan UUID (overrides –plan; for plans roksbnkctl hasn’t mapped) |
--target | string | global | target 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt |
--no-recursive | bool | false | do 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
| Flag | Type | Default | Description |
|---|---|---|---|
--instance | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--backend | string | — | additionally run per-backend checks: k8s | ssh:<target> |
--target | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal 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
| Flag | Type | Default | Description |
|---|---|---|---|
--url | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--add-node-port-access | bool | false | expose the proxy outside its cluster (NodePort + node-IP cert SANs) so a BNK install in another cluster can license through it |
--auto | bool | false | skip the confirmation prompt before apply |
--node-port-source-cidr | stringSlice | [] | 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-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt before apply |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--all-namespaces / -A | bool | false | list across all namespaces |
--namespace / -n | string | — | namespace scope (default: current-context’s namespace) |
--output / -o | string | — | output format: yaml | json | wide | name | jsonpath=… | go-template=… |
--selector / -l | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--config-file | string | — | path or http(s) URL to a workspace config.yaml to seed (non-interactive when complete; see init example) |
--non-interactive | bool | false | build config.yaml from environment variables ALONE — no prompts, no –config-file (for argv+env runners; pair with the ROKSBNKCTL_* env vars) |
--override-from-env | bool | false | after seeding, overlay config.yaml fields from environment variables (e.g. IBMCLOUD_API_KEY → ibmcloud.api_key_b64) |
--tf-source | string | — | override TF source (path or URL); relative local paths are resolved to absolute before being pinned into config.yaml |
--upgrade-tf | bool | false | resolve 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
| Flag | Type | Default | Description |
|---|---|---|---|
--dir | string | — | destination directory (default: a PATH dir — ~/.local/bin on Unix, %LOCALAPPDATA%\Microsoft\WindowsApps on Windows) |
--force | bool | false | overwrite 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
| Flag | Type | Default | Description |
|---|---|---|---|
--filename / -f | string | — | file, directory, or ‘-’ for stdin |
--force | bool | false | force-conflicts on server-side apply (kubectl apply –force-conflicts) |
--namespace / -n | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--all-namespaces / -A | bool | false | delete across all namespaces |
--cascade | string | background | cascade: orphan|background|foreground |
--force | bool | false | force-delete: implies –grace-period=0 unless overridden |
--grace-period | int | -1 | graceful termination period (seconds); -1 = use resource default |
--namespace / -n | string | — | namespace scope |
--selector / -l | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--all-namespaces / -A | bool | false | describe across all namespaces |
--namespace / -n | string | — | namespace scope |
--selector / -l | string | — | label selector |
--show-events | bool | true | include 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
| Flag | Type | Default | Description |
|---|---|---|---|
--container / -c | string | — | container name in a multi-container pod |
--namespace / -n | string | — | namespace scope (default: default) |
--stdin / -i | bool | false | attach stdin |
--tty / -t | bool | false | allocate 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
| Flag | Type | Default | Description |
|---|---|---|---|
--all-namespaces / -A | bool | false | list across all namespaces |
--namespace / -n | string | — | namespace scope (default: current-context’s namespace) |
--output / -o | string | — | output format: yaml | json | wide | name | jsonpath=… | go-template=… |
--selector / -l | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--container / -c | string | — | container name in a multi-container pod |
--follow / -f | bool | false | follow log output |
--namespace / -n | string | — | namespace scope (default: default) |
--previous | bool | false | fetch logs from the previous container instance |
--since | string | — | only return logs newer than this duration (e.g. 5s, 2m, 1h) |
--tail | int64 | -1 | tail 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
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace / -n | string | — | namespace scope (default: default) |
← back to roksbnkctl k
roksbnkctl kubeconfig
Print the kubeconfig path (or contents with –export)
roksbnkctl kubeconfig [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--cluster | string | — | cluster name or ID for –download (default: workspace cluster.name) |
--download | bool | false | fetch admin kubeconfig from IBM Cloud and save to ~/.kube/config |
--export | bool | false | print kubeconfig contents instead of path |
--refresh | bool | false | force-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
| Flag | Type | Default | Description |
|---|---|---|---|
--container / -c | string | — | container name in a multi-container pod |
--follow / -f | bool | false | follow log output |
--namespace / -n | string | — | override the component’s default namespace |
--previous | bool | false | fetch logs from the previous container instance |
--since | string | — | only return logs newer than this duration (e.g. 5s, 2m, 1h) |
--tail | int64 | -1 | tail 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
| Flag | Type | Default | Description |
|---|---|---|---|
--trusted-profile | string | auto | IBM 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
| Flag | Type | Default | Description |
|---|---|---|---|
--confirm | bool | false | actually 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal sensitive output values (default redacted) |
roksbnkctl plan
Read-only; show what roksbnkctl up would change
roksbnkctl plan [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--out | string | — | save the plan to <file> (binary plan + a readable <file>.txt) for later apply --plan |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | record the mirror even when it holds nothing under the configured prefix |
--verify-contents | bool | false | digest-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
| Flag | Type | Default | Description |
|---|---|---|---|
--far-repo-url | string | — | FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com) |
--include-deps | bool | false | force-include the non-F5 dependency artifacts (cert-manager, node-labeler) |
--json | bool | false | emit the BOM as JSON (overrides –output) |
--manifest-version | string | — | BNK manifest version (default: workspace bnk.manifest_version) |
--no-include-deps | bool | false | exclude the non-F5 dependency artifacts |
--source-sa-b64 | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | skip the confirmation prompt |
--target | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--far-repo-url | string | — | FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com) |
--include-deps | bool | false | force-include the non-F5 dependency artifacts (cert-manager, node-labeler) |
--manifest-version | string | — | BNK manifest version (default: workspace bnk.manifest_version) |
--no-include-deps | bool | false | exclude the non-F5 dependency artifacts |
--source-sa-b64 | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--far-repo-url | string | — | FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com) |
--include-deps | bool | false | force-include the non-F5 dependency artifacts (cert-manager, node-labeler) |
--manifest-version | string | — | BNK manifest version (default: workspace bnk.manifest_version) |
--no-include-deps | bool | false | exclude the non-F5 dependency artifacts |
--source-sa-b64 | string | — | FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64) |
--target | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--concurrency | int | 0 | parallel copy workers (default: 4) |
--far-repo-url | string | — | FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com) |
--include-deps | bool | false | force-include the non-F5 dependency artifacts (cert-manager, node-labeler) |
--insecure-capture-ca | bool | false | adopt a self-signed mirror CA over an UNAUTHENTICATED connection (trust-on-first-use); prefer –registry-ca or –registry-ca-fingerprint |
--manifest-version | string | — | BNK manifest version (default: workspace bnk.manifest_version) |
--no-include-deps | bool | false | exclude the non-F5 dependency artifacts |
--registry-ca | string | — | PEM CA the mirror serves TLS with, for air-gap node trust (preferred: the file you generated; else registry.generic_ca_b64) |
--registry-ca-fingerprint | string | — | expected SHA-256 of the mirror CA (“sha256:ab:cd…” or bare hex), authenticating a captured CA out of band |
--source-sa-b64 | string | — | FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64) |
--target | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--password-stdin | bool | false | read 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
| Flag | Type | Default | Description |
|---|---|---|---|
--far-repo-url | string | — | FAR registry host (default: workspace bnk.far_repo_url, else repo.f5.com) |
--include-deps | bool | false | force-include the non-F5 dependency artifacts (cert-manager, node-labeler) |
--manifest-version | string | — | BNK manifest version (default: workspace bnk.manifest_version) |
--no-include-deps | bool | false | exclude the non-F5 dependency artifacts |
--source-sa-b64 | string | — | FAR _json_key_base64 service account (default: workspace registry.source_service_account_b64) |
--target | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | migrate 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
| Flag | Type | Default | Description |
|---|---|---|---|
--access-key-source | string | — | env var holding the HMAC access key (default ROKSBNKCTL_COS_HMAC_ACCESS_KEY) |
--bucket | string | — | pre-provisioned bucket name (required) |
--endpoint | string | — | COS S3 endpoint URL (required) |
--key-prefix | string | — | state key prefix (default: the workspace name) |
--region | string | — | COS location / region (required) |
--secret-key-source | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--host | string | — | host or IP |
--key-path | string | — | path to a PEM private key |
--key-source | string | — | key source — “agent” or “tf-output:<name>” |
--port | int | 0 | ssh port (default 22) |
--user | string | — | 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//.roksbnkctl/<ws>/state-cluster/); the default is the trial/single
state (<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
| Flag | Type | Default | Description |
|---|---|---|---|
--insecure | bool | false | skip 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
| Flag | Type | Default | Description |
|---|---|---|---|
--gslb-compare | bool | false | fan out the probe across all configured backends (local + k8s + ssh:<targets>) and emit a comparison JSON with gslb_divergence |
--iterations | int | 1 | number of repeated queries; >1 enables RTT distribution |
--require-divergence | bool | false | with –gslb-compare: exit non-zero if NO divergence is observed (CI assertion that GSLB is doing something) |
--server | string | — | resolver: <ip>[:<port>] | system | cluster | <named-from-workspace> (default: system) |
--target | string | — | DNS name to query (overrides workspace test.dns.default_target) |
--timeout | duration | 2s | per-query timeout |
--type | string | A | record 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip 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
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | bool | false | expand the grid and print the plan + fixtures; no cluster calls |
--file | string | — | path to matrix.yaml (default: <workspace>/matrix.yaml, then ./matrix.yaml) |
--keep | bool | false | leave fixtures running after the run |
--only | string | — | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--cross-node | bool | false | force east-west client and server onto different nodes |
--keep | bool | false | leave the iperf3 server pod running after the test |
--mode | string | north-south | throughput 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output JSON (CI-friendly) |
--show-sensitive | bool | false | reveal 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
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | output 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt before apply |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | overwrite the destination if it already exists |
--output / -o | string | ./terraform.tfvars | destination 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt before apply |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the destroy confirmation |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--dir | string | — | directory to remove roksbnkctl from (default: ~/.local/bin or ~/bin) |
--yes / -y | bool | false | skip 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
| Flag | Type | Default | Description |
|---|---|---|---|
--auto | bool | false | skip the confirmation prompt before apply |
--no-kubeconfig | bool | false | skip the post-apply admin kubeconfig fetch |
--tf-source | string | — | override TF source for this run only (path or URL; relative local paths resolved against the invocation CWD) |
--var-file | stringArray | [] | 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
| Flag | Type | Default | Description |
|---|---|---|---|
--version | string | — | release to install, e.g. v1.20.1 (default: latest) |
--yes / -y | bool | false | skip 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
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | delete 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