Configuration reference

Field-by-field schema reference for the workspace config.yaml. Source of truth is the Workspace struct in internal/config/workspace.go; this chapter is the human-readable rendering of those tags.

Chapter 12 — Workspace config is the teaching chapter; this one is the lookup chapter. Use chapter 12 to learn the shape, use this one to look up the type of a specific field.

File location and lifecycle

The file is hand-editable; YAML is parsed with gopkg.in/yaml.v3 so anchors and aliases work but are not idiomatic for this file. Plaintext credentials in any of the regex-matched secret fields (api_key, apikey, password, token, secret_access_key, hmac_secret) are rejected at load time — the file fails to parse with a clear error. Base64-encoded credentials in ibmcloud.api_key_b64 are allowed (the field name doesn’t match the rejection regex). See Chapter 14.

Top-level structure

ibmcloud:        # required
cluster:         # required
bnk:             # optional; populates upstream HCL bnk variables
test:            # optional; populates test.* settings
tf_source:       # required (defaults to embedded if omitted)
cos:             # optional; supply-chain auto-upload
targets:         # optional; populated automatically by up's post-apply hook
exec:            # optional; per-tool default-backend map

The order of the top-level keys in the file doesn’t matter; YAML is a mapping. The order shown above is the canonical render order produced by roksbnkctl init.

ibmcloud: block

ibmcloud:
  region: ca-tor
  resource_group: default
  api_key_source: keychain
  api_key_b64: <base64>

cluster: block

cluster:
  create: true
  name: tf-openshift-cluster
  openshift_version: "4.18"
  workers_per_zone: 1

bnk: block

bnk:
  cneinstance_size: Small
  far_repo_url: repo.f5.com
  manifest_version: 2.3.0-3.2598.3-0.0.170

All three fields are optional; omitting renders the HCL’s own defaults. See Chapter 13 — Terraform variables for the upstream defaults.

test: block

test:
  throughput:
    image: ghcr.io/jgruberf5/roksbnkctl-tools-iperf3:v0.9.0
    duration: 30
    streams: 8
    default_mode: north-south
  connectivity:
    extra_hosts:
      - https://www.example.com/healthz
      - https://internal.bnk.local/status
  dns:
    resolvers:
      google: "8.8.8.8:53"
      cloudflare: "1.1.1.1:53"
      gslb-vip: "169.45.91.5:53"
    default_target: www.example.com

test.throughput

test.connectivity

test.dns

tf_source: block

tf_source:
  type: embedded         # or: github | local
  repo: jgruberf5/roksbnkctl-tf
  ref: v1.0.0
  path: /path/to/checkout

Most users want embedded (the default). The github mode is for testing forks or pinning to an upstream tag that’s newer than the bundled one. The local mode is for active development on the HCL itself.

cos: block

cos:
  instance: bnk-orchestration
  bucket: bnk-schematics-resources
  upload:
    - source: ./local/f5-far-auth-key.tgz
      key: f5-far-auth-key.tgz
    - source: ./local/trial.jwt
      key: trial.jwt

See Chapter 25 — COS supply chain management for the full surface.

targets: block

targets:
  jumphost:
    host: 169.45.91.10
    port: 22
    user: ubuntu
    key_path: /path/to/private/key.pem      # one of key_path
    key_source: tf-output:jumphost_shared_key  # ...or key_source

The top-level value is a map; the key is the target name (jumphost, eu-bastion, etc.). Each entry:

Auto-populated by roksbnkctl up post-apply for the upstream HCL’s TGW jumphost when testing_create_tgw_jumphost = true. See Chapter 15 — SSH targets and Chapter 16 — The --on flag.

exec: block

exec:
  ibmcloud:  { backend: local }
  iperf3:    { backend: k8s }
  terraform: { backend: local }

Top-level value is a map keyed by tool name. Each entry has one field:

The per-tool defaults at v1.0:

See Chapter 17 — Execution backends and Chapter 18 — Choosing a backend per tool.

Field-by-field reference table

Sorted by top-level block. Lookup-friendly. Every field that appears in internal/config/workspace.go.

Behaviour when fields are missing

roksbnkctl falls through three layers: workspace config → upstream HCL default → fail.

How --var-file interacts with config.yaml

roksbnkctl up --var-file <file> layers user-supplied tfvars after the auto-rendered tfvars derived from config.yaml. Later wins, terraform-style. Multiple --var-file flags are accepted and stack in command-line order.

The auto-render path: config.yaml → typed Workspace struct → key/value tfvars → ~/.roksbnkctl/<ws>/state/terraform.tfvars. The user’s --var-file is appended to the terraform invocation as an additional -var-file=<path> argument. See Chapter 13 — Terraform variables for the layering rules.

A workspace-persistent override file is ~/.roksbnkctl/<ws>/terraform.tfvars.user — when present, it’s auto-layered after the rendered tfvars and before any explicit --var-file. Useful for “always pass this bigip_password value when applying this workspace” without putting it in config.yaml (where the plaintext-secret rejection would reject it).

Cross-references

• Chapter 12 — Workspace config — the teaching counterpart to this lookup.
• Chapter 13 — Terraform variables — how config.yaml fields render into tfvars.
• Chapter 14 — Credentials and the resolver chain — the ibmcloud.api_key_* semantics.
• Chapter 29 — Terraform variable reference — the upstream HCL variable surface that bnk.* and cluster.* populate.