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.

roksbnkctl apply

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

roksbnkctl apply [flags]

Flags

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, cert-manager, jumphost) roksbnkctl cluster down Destroy the cluster and everything cluster-scoped roksbnkctl cluster register Discover an already-existing cluster and persist its identity roksbnkctl cluster show Print the registered cluster from cluster-outputs.json

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 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

← 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.

By default the registry COS instance name follows the upstream HCL fallback formula “<cluster-name>-cos”. Pass –registry-cos-name to override (e.g. if your tfvars sets roks_cos_instance_name to a different value).

Flags

← back to roksbnkctl cluster

roksbnkctl cluster show

Print the registered cluster (cluster-outputs.json)

← back to roksbnkctl cluster

roksbnkctl cluster up

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

roksbnkctl cluster up [flags]

Runs terraform apply with deploy_bnk=false forced — creates the ROKS cluster, transit gateway, registry COS, cert-manager, and the test jumphost, but skips the BNK trial modules (flo, cne_instance, license). On success, writes the cluster’s identity to ~/.roksbnkctl/<workspace>/cluster-outputs.json so subsequent roksbnkctl up runs can deploy BNK trials onto this cluster.

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

Flags

← back to roksbnkctl cluster

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

← back to roksbnkctl cos

roksbnkctl cos bucket create

Create a bucket on the named instance

roksbnkctl cos bucket create <bucket> [flags]

Flags

← 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 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

← 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

← 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

← 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

roksbnkctl down

Destroy everything in the workspace — terraform destroy

roksbnkctl down [flags]

Flags

roksbnkctl exec

Run a single command with cluster context loaded

roksbnkctl exec [command...]

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

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

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, 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)

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

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

← 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

← 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

← 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

← 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

← 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

← 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

← back to roksbnkctl k

roksbnkctl kubeconfig

Print the kubeconfig path (or contents with –export)

roksbnkctl kubeconfig [flags]

Flags

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

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

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.

← 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

← back to roksbnkctl ops

roksbnkctl plan

Read-only; show what roksbnkctl up would change

roksbnkctl plan [flags]

Flags

roksbnkctl self

Manage the roksbnkctl binary itself

roksbnkctl self update

Pull the latest roksbnkctl release matching the host arch

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

Linux/macOS only — Windows can’t replace a running .exe in place; use scoop update roksbnkctl instead.

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 status

Summary of the workspace: cluster, components, last apply

roksbnkctl status reports a quick read of the workspace:

• workspace name + region
• configured cluster name
• pinned Terraform source
• last terraform apply timestamp (mtime of terraform.tfstate)
• 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.

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

← 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 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

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

← back to roksbnkctl test

roksbnkctl test list

List available test suites

← 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

← back to roksbnkctl test

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

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

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

← 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