roksbnkctl

package module
v1.64.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 1 Imported by: 0

README

roksbnkctl

Read the book — Deploying and Testing BIG-IP Next for Kubernetes with roksbnkctl

A single-binary CLI for deploying F5 BIG-IP Next for Kubernetes (BNK) onto IBM Cloud ROKS, managing its IBM Cloud Object Storage supply chain, and validating the deployment with built-in connectivity, DNS, and throughput tests.

Status: v1.0 — first stable release.

The book at https://jgruberf5.github.io/roksbnkctl/book/ is the canonical user documentation, covering concepts, lifecycle, day-2 operations, execution backends, the GSLB-aware DNS probe, and full reference material. This README is a quickstart pointer — read the book for everything else.

Quick start

# 1. Install the binary
go install github.com/jgruberf5/roksbnkctl/cmd/roksbnkctl@latest
#   …or grab a pre-built binary for your OS/arch from the releases page:
#   https://github.com/jgruberf5/roksbnkctl/releases/latest

# 2. Interactive setup — region, RG, cluster, OpenShift version.
roksbnkctl init

# 3. Make your IBM Cloud API key available (env, OS keychain, or
#    `roksbnkctl init` will offer to persist it for you).
export IBMCLOUD_API_KEY=...

# 4. Plan + confirm + apply + auto-fetch admin kubeconfig.
roksbnkctl up

# 5. Run the built-in DNS + connectivity + throughput tests.
roksbnkctl test

That's the 4-command lifecycle (init → up → test → down). See Chapter 7 — Quick start for the full walkthrough; Chapter 24 — Day-2 ops for what comes after.

Install

Option How
One-liner (recommended) Linux/macOS: curl -fsSL https://raw.githubusercontent.com/jgruberf5/roksbnkctl/main/install.sh | sh · Windows (PowerShell): irm https://raw.githubusercontent.com/jgruberf5/roksbnkctl/main/install.ps1 | iex. Downloads the release for your OS/arch, verifies its checksum, and installs it onto PATH.
go install go install github.com/jgruberf5/roksbnkctl/cmd/roksbnkctl@latest (Go 1.26+)
Pre-built binary Linux/macOS/Windows × amd64/arm64 archives + SHA256 checksums on every tagged release at https://github.com/jgruberf5/roksbnkctl/releases. Verify with sha256sum -c checksums.txt.
From source git clone https://github.com/jgruberf5/roksbnkctl && cd roksbnkctl && make build (output at bin/roksbnkctl; see Chapter 31 — Building from source).
In-place upgrade roksbnkctl upgrade lists the releases newer than your binary and lets you pick one (or --yes for the latest), verifies the SHA256 against checksums.txt, and replaces the running binary. Works on Linux, macOS, and Windows.

A Homebrew tap is on the v1.x roadmap.

Every tagged release also attaches an offline roksbnkctl-book-<tag>.pdf — the same book as the published HTML, rendered with Mermaid diagrams pre-baked as vector SVG. Grab it from the same releases page when you want the docs without a network round-trip.

Prerequisites

terraform (1.5+) on PATH is the only required host install. roksbnkctl doctor reports green on a stock dev box with terraform alone — every other tool the binary needs (kubectl, oc, ibmcloud, iperf3, dig) is internalised:

Surface Internalised path
kubectl, oc client-go — roksbnkctl k get/apply/describe/delete/logs/exec/port-forward
ibmcloud Bundled tools image — --backend docker or --backend ssh:<target>
iperf3 Bundled tools image — --backend k8s runs the throughput probe as a one-shot Job
dig miekg/dns — roksbnkctl test dns (multi-vantage GSLB-aware probe)

See Chapter 17 — Execution backends for the full backend matrix.

What's in this repo

roksbnkctl/
├── cmd/roksbnkctl/         # binary entry point
├── internal/               # Go packages (cli, tf, ibm, k8s, cred, exec, test, doctor, ...)
├── terraform/              # the HCL deployment — embedded into the binary at build time
├── tools/                  # vendored tool images + cobra-md / tfvars-md reference generators
├── book/                   # mdBook sources for https://jgruberf5.github.io/roksbnkctl/book/
├── docs/                   # PLAN.md (sprint history), prd/ (per-feature design specs)
└── scripts/                # e2e test runners

The Terraform that drives the deployment is embedded into the binary at build time — every tagged release ships a matched CLI + HCL pair, eliminating skew between binary and TF. tf_source overrides (type: github or local) let you point at a fork for testing.

Pointers

  • Book — https://jgruberf5.github.io/roksbnkctl/book/ — canonical user documentation; start at the preface or jump to Chapter 7 for the deploy walkthrough. Auto-published from main via GitHub Actions on every push to book/**. An offline PDF (roksbnkctl-book-<tag>.pdf) attaches to each GitHub Release.
  • MIGRATING.md — upgrade notes from bnk (the pre-roksbnkctl bash workflow), from manual BNK deployment, and between roksbnkctl versions.
  • CHANGELOG.md — per-release change log; v1.0.0 rolls up the seven-sprint history.
  • docs/PLAN.md — sprint-by-sprint development history and the v1.x deferral list.
  • docs/prd/ — per-feature design rationale (cred propagation, execution backends, DNS probe, kubectl internalisation, …).
  • CONTRIBUTING.md — how to contribute, run tests, add a chapter, and cut a release (the make release driver wraps the book + PDF + goreleaser snapshot + Pages preflight into one command). Failing that, file issues at https://github.com/jgruberf5/roksbnkctl/issues.

What this is not

  • Not a Terraform authoring tool. The HCL lives in this repo under ./terraform/ and is the source of truth for the deployment shape.
  • Not a general-purpose IBM Cloud CLI — ibmcloud covers that. roksbnkctl's scope on IBM Cloud is the BNK supply chain: ROKS for the cluster, COS for prerequisite artefacts (FAR pull keys, JWT licenses), IAM for what BNK consumes.
  • Not a general-purpose Kubernetes CLI — kubectl / oc cover that. The internalised roksbnkctl k * verbs make their workspace context easy to load without a host install.
  • Not an arbitrary workload deployer. BNK is the workload; the iperf3 / nginx test fixtures exist only to validate it.

License

MIT.

Documentation

Overview

Package roksbnkctl exposes the embedded Terraform source tree as an embed.FS so the compiled binary ships with the matched HCL — no separate TF download for the default deploy path. External tf_source overrides (a GitHub release, a local path) bypass this and still work for users who want to test forks.

This file lives at the module root because //go:embed paths are resolved relative to the source file's directory and Go forbids embedding paths outside the embedding file's package — so the embedding shim has to sit alongside ./terraform/.

Index

Constants

This section is empty.

Variables

View Source
var EmbeddedTerraform embed.FS

EmbeddedTerraform is the entire ./terraform/ tree (HCL root + modules + terraform.tfvars.example). Walked at runtime by tf.FetchSource when the workspace's tf_source is unset / type=embedded, and extracted into the workspace state dir for terraform-exec to operate on.

Two directives, deliberately.

The first embeds the committed HCL. It is NOT `all:terraform`: the `all:` prefix pulls in dotfiles, including the gitignored `.terraform/` provider/module cache (~400MB of plugin binaries) that a local `terraform init`/`validate` leaves in ./terraform during development. Embedding that bloated the binary to ~670MB AND, once extracted (extractEmbeddedTF writes 0644), shipped non-executable provider binaries that broke `terraform plan` with "fork/exec ... permission denied".

The second names .terraform.lock.hcl explicitly, because a plain directory pattern skips every dotfile and this one has to ship (#147). It pins each provider to an exact version and records the checksums `terraform init` verifies downloads against. Without it in the binary, `init` runs in the extract directory against the `>=` constraints in versions.tf alone, so two operators running the same release on different days can resolve different providers, and nothing verifies what the registry serves. CI ran against the committed lockfile while every user got a freshly resolved set.

An explicit path is what keeps this from costing anything: it ships the one dotfile that matters without reopening the `all:` problem above.

Functions

This section is empty.

Types

This section is empty.

Directories

Path Synopsis
cmd
flp-status command
Command flp-status serves the F5 License Proxy status web UI.
Command flp-status serves the F5 License Proxy status web UI.
roksbnkctl command
Command roksbnkctl is the user-facing CLI entrypoint.
Command roksbnkctl is the user-facing CLI entrypoint.
internal
bnkbom
Package bnkbom builds the bill-of-materials (BOM) of artifacts a BNK install needs — every helm chart and container image — by parsing the f5-bigip-k8s-manifest that FAR publishes per BNK release, and unioning the non-F5 dependencies roksbnkctl installs that the manifest does not cover (cert-manager from Jetstack, bitnami/kubectl for the node-labeler).
Package bnkbom builds the bill-of-materials (BOM) of artifacts a BNK install needs — every helm chart and container image — by parsing the f5-bigip-k8s-manifest that FAR publishes per BNK release, and unioning the non-F5 dependencies roksbnkctl installs that the manifest does not cover (cert-manager from Jetstack, bitnami/kubectl for the node-labeler).
cli
Package cli wires the cobra command tree for roksbnkctl.
Package cli wires the cobra command tree for roksbnkctl.
config
Package config loads workspace and global configuration, resolves the IBM Cloud API key (env / OS keychain / prompt), and renders Terraform variables files.
Package config loads workspace and global configuration, resolves the IBM Cloud API key (env / OS keychain / prompt), and renders Terraform variables files.
cos
Package cos wraps IBM/ibm-cos-sdk-go for COS bucket and object I/O. The SDK is S3-compatible (literally a fork of AWS S3 SDK with IBM IAM auth bolted in), so the operations look familiar:
Package cos wraps IBM/ibm-cos-sdk-go for COS bucket and object I/O. The SDK is S3-compatible (literally a fork of AWS S3 SDK with IBM IAM auth bolted in), so the operations look familiar:
cred
Package cred is the single source of truth for credential resolution across roksbnkctl execution backends.
Package cred is the single source of truth for credential resolution across roksbnkctl execution backends.
doctor
Package doctor implements the prerequisite checks used by `roksbnkctl doctor`.
Package doctor implements the prerequisite checks used by `roksbnkctl doctor`.
embedded
Package embedded ships the agentic-mode scaffolding inside the binary.
Package embedded ships the agentic-mode scaffolding inside the binary.
exec
Package exec defines the Backend interface and per-backend implementations roksbnkctl uses to run external tools (ibmcloud, kubectl, terraform, iperf3, etc.).
Package exec defines the Backend interface and per-backend implementations roksbnkctl uses to run external tools (ibmcloud, kubectl, terraform, iperf3, etc.).
exitcode
Package exitcode defines roksbnkctl's exit-code contract and the error type that carries a code out of a command.
Package exitcode defines roksbnkctl's exit-code contract and the error type that carries a code out of a command.
flp
Package flp holds the F5 License Proxy install's chart fix-ups.
Package flp holds the F5 License Proxy install's chart fix-ups.
flpstatus
Package flpstatus gathers and serves the runtime status of an F5 License Proxy (FLP) — the same four-container stack whether it runs as a podman pod on a standalone VSI or as the helm chart in a ROKS cluster.
Package flpstatus gathers and serves the runtime status of an F5 License Proxy (FLP) — the same four-container stack whether it runs as a podman pod on a standalone VSI or as the helm chart in a ROKS cluster.
forge
Package forge is a small REST client for BNK Forge v3 (FastAPI).
Package forge is a small REST client for BNK Forge v3 (FastAPI).
ibm
Package ibm wraps the IBM Cloud Go SDKs for everything that isn't COS bucket/object I/O:
Package ibm wraps the IBM Cloud Go SDKs for everything that isn't COS bucket/object I/O:
k8s
Package k8s wraps client-go for roksbnkctl's internal Kubernetes operations:
Package k8s wraps client-go for roksbnkctl's internal Kubernetes operations:
naming
Package naming derives every account-scoped IBM Cloud resource name a workspace needs from a single workspace prefix, and validates that prefix against the per-resource-type length/charset limits BEFORE terraform ever runs — so an over-long or malformed prefix is rejected at `init` time rather than mid-`apply` by IBM Cloud.
Package naming derives every account-scoped IBM Cloud resource name a workspace needs from a single workspace prefix, and validates that prefix against the per-resource-type length/charset limits BEFORE terraform ever runs — so an over-long or malformed prefix is rejected at `init` time rather than mid-`apply` by IBM Cloud.
orchestration
Package orchestration is roksbnkctl's service layer: the lifecycle / cluster / remote-dispatch orchestration extracted out of the internal/cli god-package (Sprint 15 phase-1 decomposition), plus the single path/env normalization chokepoint that structurally retires the recurring "a value correct in the invocation context is wrong once it crosses a boundary" bug class (Sprint 12 Issues 1/2 + Sprint 13 Issue 1).
Package orchestration is roksbnkctl's service layer: the lifecycle / cluster / remote-dispatch orchestration extracted out of the internal/cli god-package (Sprint 15 phase-1 decomposition), plus the single path/env normalization chokepoint that structurally retires the recurring "a value correct in the invocation context is wrong once it crosses a boundary" bug class (Sprint 12 Issues 1/2 + Sprint 13 Issue 1).
registry/mirror
Package mirror is the Sprint 29 replication engine: it copies the BNK bill-of-materials (charts + images) from their source registries into a single private target, idempotently and concurrently.
Package mirror is the Sprint 29 replication engine: it copies the BNK bill-of-materials (charts + images) from their source registries into a single private target, idempotently and concurrently.
registry/ocireg
Package ocireg implements the Sprint 30 RegistryTarget for any STANDARD OCI registry that nests the FAR category under a configured namespace/repository prefix: "<host>/<namespace>/images/<name>".
Package ocireg implements the Sprint 30 RegistryTarget for any STANDARD OCI registry that nests the FAR category under a configured namespace/repository prefix: "<host>/<namespace>/images/<name>".
registry/source
Package source is the FAR (F5 Artifact Repository, repo.f5.com) OCI source client for the Sprint 29 registry mirror (PRD 11 §3).
Package source is the FAR (F5 Artifact Repository, repo.f5.com) OCI source client for the Sprint 29 registry mirror (PRD 11 §3).
remote
Package remote implements the embedded SSH client and related plumbing for roksbnkctl's --on <target> flag (PRD 01).
Package remote implements the embedded SSH client and related plumbing for roksbnkctl's --on <target> flag (PRD 01).
sshkey
Package sshkey generates ed25519 SSH keypairs and writes them to disk for the testing jumphosts (the IBM Cloud VPC SSH key roksbnkctl uploads + manages).
Package sshkey generates ed25519 SSH keypairs and writes them to disk for the testing jumphosts (the IBM Cloud VPC SSH key roksbnkctl uploads + manages).
test
Package test contains the deployment-validation probe runners for `roksbnkctl test`.
Package test contains the deployment-validation probe runners for `roksbnkctl test`.
tf
Package tf wraps hashicorp/terraform-exec to drive `terraform init / plan / apply / destroy` against the pinned TF source for a roksbnkctl workspace.
Package tf wraps hashicorp/terraform-exec to drive `terraform init / plan / apply / destroy` against the pinned TF source for a roksbnkctl workspace.
ui
Package ui provides terminal output primitives — spinners, progress bars, tables, structured logging, and JSON output formatting (versioned schema: "schema":"roksbnkctl.v1").
Package ui provides terminal output primitives — spinners, progress bars, tables, structured logging, and JSON output formatting (versioned schema: "schema":"roksbnkctl.v1").
tools
refgen/cobra-md command
Command cobra-md walks the roksbnkctl cobra command tree and emits a single Markdown reference document on stdout.
Command cobra-md walks the roksbnkctl cobra command tree and emits a single Markdown reference document on stdout.
refgen/config-cheatsheet command
Command config-cheatsheet renders every possible config.yaml entry as a single self-contained HTML page.
Command config-cheatsheet renders every possible config.yaml entry as a single self-contained HTML page.
refgen/config-md command
Command config-md parses internal/config/workspace.go and emits the workspace `config.yaml` schema reference on stdout.
Command config-md parses internal/config/workspace.go and emits the workspace `config.yaml` schema reference on stdout.
refgen/env-example command
Command env-example generates the annotated .env template `roksbnkctl config env` prints.
Command env-example generates the annotated .env template `roksbnkctl config env` prints.
refgen/mdesc
Package mdesc prepares free text that is about to be interpolated into markdown by the refgen tools.
Package mdesc prepares free text that is about to be interpolated into markdown by the refgen tools.
refgen/tfvars-md command
Command tfvars-md parses terraform/variables.tf (plus each submodule's own variables.tf) and emits a single Markdown reference document on stdout covering every Terraform variable with type, default, description, sensitive flag, and source file.
Command tfvars-md parses terraform/variables.tf (plus each submodule's own variables.tf) and emits a single Markdown reference document on stdout covering every Terraform variable with type, default, description, sensitive flag, and source file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL