Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration reference

Field-by-field schema for the workspace config.yaml, generated from the Workspace struct in internal/config/workspace.go. This chapter is the single source of truth for what a field is called, what type it takes, and which BNK line it applies to.

For a one-page version carrying the full dotted paths and each field’s ROKSBNKCTL_* override, see the config.yaml cheatsheet — generated from the same struct, so the two cannot disagree.

Chapter 12 — Workspace config is the teaching chapter: use it to learn the shape. Use this one to look up a specific field. Every other chapter links here rather than restating fields, because a field restated in four places is a field that will disagree with itself by the next release.

The line column says which BNK release line a field applies to. Most apply to both. A field marked 2.4 has no effect on a 2.3 install and vice versa — the line itself is selected by bnk.manifest_version and nothing else.

Required means the field has no omitempty: it is always rendered, and its zero value is meaningful. It does not mean you must type it into your config.yaml.

Default is carried on the field as a default:"..." struct tag. A dash means no default is declared — either the zero value applies, or the default is computed at run time and belongs in the prose rather than a table cell.

Workspace

Workspace is ~/.roksbnkctl/<name>/config.yaml. Mirrors the per-workspace example in docs/PRD.md. Note that there is no api_key field — secrets live in env vars or the OS keychain, never in this struct. Plaintext keys in the YAML are rejected at load time by rejectPlaintextSecrets.

keytypelinedefaultrequireddescription
ibmcloudIBMCloudCfg2.3 + 2.4—yesIBMCloud is the account context every phase runs against: region, resource group, and the API key (base64-obfuscated, never plaintext).
clusterClusterCfg2.3 + 2.4—yesCluster describes the ROKS cluster — either one to CREATE, or one that already exists and is being adopted (create: false plus its name).
bnkBNKCfg2.3 + 2.4—noBNK configures the BIG-IP Next for Kubernetes install itself: the manifest version (which also decides whether the 2.3 or 2.4 model is rendered), licensing, the per-zone network mapping, and the CNEInstance settings that place the TMM pods.
gatewayGatewayCfg2.3 + 2.4—noGateway configures the Gateway API resources installed after BNK.
registry*RegistryCfg2.3 + 2.4—noRegistry selects where images and charts are pulled from: F5’s Artifact Repository directly, or a mirror that a disconnected cluster can reach — IBM Container Registry, or any OCI registry (generic) such as Artifactory or Harbor.
testTestCfg2.3 + 2.4—noTest configures the connectivity, DNS and throughput probes roksbnkctl test runs, and the jumphost they run FROM.
tf_sourceTFSourceCfg2.3 + 2.4—yesTFSource selects which Terraform the binary applies: the embedded tree shipped inside this binary (the default, and the only version matched to it), a GitHub release, or a local path for testing a fork.
cos*COSCfg2.3 + 2.4—noCOS is the IBM Cloud Object Storage bucket the FAR service-account credential is read from, for estates that stage it there rather than passing a local file.
targetsmap[string]TargetCfg2.3 + 2.4—noTargets are named remote hosts (ssh:<target>) that Exec backends can run tools on — a jumphost inside the VPC, say, when the operator’s workstation cannot reach the cluster directly.
stateStateCfg2.3 + 2.4—noState controls where Terraform state is kept and how it is locked.
bnkforge*BNKForgeCfg2.3 + 2.4—noBNKForge points at a BNK Forge server, which takes over a durable cluster once roksbnkctl has built it.
agent*AgentCfg2.3 + 2.4—noAgent configures roksbnkctl agent, which hands the workspace to a coding agent.
prefixstring2.3 + 2.4—noPrefix is the workspace’s account-scoped resource-name base.
resources*ResourcesCfg2.3 + 2.4—noResources carries the per-resource create toggles (and the existing-resource name/ID for any declined-but-still-depended-on resource).
execmap[string]ExecToolCfg2.3 + 2.4—noExec is the per-tool execution-backend config block introduced in Sprint 3 (PRD 03).

AdvancedComponentCfg

AdvancedComponentCfg is one component’s advanced settings. Only env is surfaced today; the CR’s advanced block carries more, and this is the shape that lets those arrive without moving what already works.

keytypelinedefaultrequireddescription
envmap[string]string2.3 + 2.4—noEnv sets environment variables on that component’s containers, name → value.

AgentCfg

AgentCfg configures roksbnkctl’s agentic mode (the agent command). It is purely advisory metadata for launching an external coding-agent CLI against the workspace’s scaffolded AGENTS.md + personas/ — roksbnkctl embeds no LLM. nil/absent = agent defaults to claude and the CLI’s own endpoint config.

keytypelinedefaultrequireddescription
defaultstring2.3 + 2.4—noDefault is the agentic CLI roksbnkctl agent (no arg) reports as this workspace’s default — claude | gemini | aider | openai | pi | opencode.
llm_endpointstring2.3 + 2.4—noLLMEndpoint is an optional OpenAI-/Anthropic-compatible base URL woven into the printed invocation (cloud vendor, local vLLM, etc.).

BNKCISCfg

BNKCISCfg configures the BNK CIS controller’s BIG-IP target. All optional. BigIPPasswordB64 stores the password base64-encoded (obfuscation, NOT encryption — like ibmcloud.api_key_b64); the raw value is rendered to terraform.tfvars as bigip_password at apply time.

keytypelinedefaultrequireddescription
bigip_urlstring2.3 + 2.4—noBigIPURL is the management address of the classic BIG-IP that the Container Ingress Services controller configures, e.g. “https://10.1.1.5”.
bigip_usernamestring2.3 + 2.4—noBigIPUsername is the account CIS authenticates to that BIG-IP as.
bigip_password_b64string2.3 + 2.4—noBigIPPasswordB64 is that account’s password, base64-encoded — obfuscation, not encryption.

BNKCertManagerCfg

BNKCertManagerCfg overrides cert-manager’s install coordinates. All optional; the create/skip decision stays on resources.cert_manager.create.

keytypelinedefaultrequireddescription
namespacestring2.3 + 2.4—noNamespace cert-manager installs into (rendered as cert_manager_namespace).
versionstring2.3 + 2.4—noVersion pins the cert-manager Helm chart (rendered as cert_manager_version).

BNKCfg

keytypelinedefaultrequireddescription
cneinstance_sizestring2.3 + 2.4—noCNEInstanceSize is the CNEInstance deploymentSize: Tiny, Small, Medium, Large or Max.
far_repo_urlstring2.3 + 2.4repo.f5.comnoFARRepoURL is the F5 Artifact Repository charts are pulled from.
manifest_versionstring2.3 + 2.4—noManifestVersion pins the BNK release, e.g. “2.4.0-EA”.
far_auth_filestring2.3 + 2.4—noFarAuthFile is the FAR auth tarball’s filename in the orchestration COS bucket; rendered as the f5_cne_far_auth_file tfvar + used by registry to resolve the FAR _json_key_base64 service account.
subscription_jwt_filestring2.3 + 2.4—noSubscriptionJWTFile is the subscription/license JWT’s filename in the orchestration COS bucket; rendered as the f5_cne_subscription_jwt_file tfvar.
far_auth_local_filestring2.3 + 2.4—noFarAuthLocalFile / SubscriptionJWTLocalFile point at LOCAL files instead of COS objects.
subscription_jwt_local_filestring2.3 + 2.4—noSubscriptionJWTLocalFile is the F5 subscription JWT as a LOCAL file, the companion to FarAuthLocalFile above.
trusted_profile*BNKTrustedProfileCfg2.3 + 2.4—noTrustedProfile tunes the IBM Cloud Trusted Profile the CNE controller assumes to manage its own cluster’s VPC.
flo_namespacestring2.3 + 2.4f5-bnknoFLONamespace / FLOUtilsNamespace override the namespaces the F5 Lifecycle Operator and its utility components install into (rendered as flo_namespace / flo_utils_namespace).
flo_utils_namespacestring2.3 + 2.4f5-utilsnoFLOUtilsNamespace is where FLO’s SHARED utility components install — coremond, the observer, the licence — as opposed to FLONamespace, which holds the BNK instance itself.
storage_class_namestring2.3 + 2.4—noStorageClassName is the StorageClass the CNEInstance’s persistent volumes use, TMM’s included.
gateway_api_mtlsbool2.4—noGatewayAPIMTLS opts into the Gateway API bundle BNK 2.4 needs for mTLS (#170).
tmm_replicasint2.43noTMMReplicas is the number of f5-tmm data-plane replicas.
watch_namespaces[]string2.4AllnoWatchNamespaces are the namespaces the CNE controller watches.
tmm_anti_affinity*bool2.4truenoTMMAntiAffinity requires f5-tmm pods onto different nodes.
tmm_anti_affinity_topology_keystring2.4kubernetes.io/hostnamenoTMMAntiAffinityTopologyKey is the node label the anti-affinity rule spreads across — the IBM ROKS per-node label.
tmm_zone_spread*bool2.4truenoTMMZoneSpread spreads f5-tmm pods across zones.
tmm_zone_topology_keystring2.4topology.kubernetes.io/zonenoTMMZoneTopologyKey is the IBM ROKS zone label the spread constraint uses.
tmm_zone_max_skewint2.41noTMMZoneMaxSkew is maxSkew for the zone topology-spread constraint.
tmm_zone_when_unsatisfiablestring2.4DoNotSchedulenoTMMZoneWhenUnsatisfiable is DoNotSchedule or ScheduleAnyway.
tmm_pod_labelstring2.4f5-tmmnoTMMPodLabel is the app label value the placement rules select TMM by.
tmm_rolling_update*bool2.4truenoTMMRollingUpdate pins TMM’s rolling update to maxSurge 0 / maxUnavailable 1 — the same shape as the cwc Multi-Attach deadlock, where an unconstrained rolling update on a single-attach resource wedges.
external_bigip*bool2.4falsenoExternalBigIP enables the external BIG-IP controller.
external_bigip_login_secretstring2.4f5-bigip-ctlr-loginnoExternalBigIPLoginSecret holds the external BIG-IP credentials.
cluster_identifierstring2.4—noClusterIdentifier is passed to the external BIG-IP controller.
gateway_api_versionstring2.41.5.0noGatewayAPIVersion is GATEWAY_API_VERSION for the CNE controller.
gateway_api_bundle_urlstring2.4—noGatewayAPIBundleURL is where the Gateway API standard-install bundle is FETCHED from when gateway_api_mtls is on (#185).
demo_mode*bool2.3 + 2.4false on 2.4, true on 2.3noDemoMode sets advanced.demoMode.enabled.
whole_cluster*bool2.3 + 2.4false on 2.4, true on 2.3noTCPSettings overrides fields on the data-plane F5BigTcpSetting CR.
hugepages*HugepagesCfg2.3 + 2.4—noHugepages optionally allocates hugepages on the worker pool via the OpenShift Node Tuning Operator.
tcp_settingsmap[string]string2.3 + 2.4—noTCPSettings overrides individual fields on the data-plane F5BigTcpSetting CR by name, e.g. {“congestionControl”: “bbr”, “delayedAcks”: “true”} — the key is the CR’s own spec field.
tcp_settings_namestring2.3 + 2.4sys-default-tcpnoTCPSettingsName is the F5BigTcpSetting to write.
advancedmap[string]AdvancedComponentCfg2.3 + 2.4—noAdvanced carries per-component environment passthrough for the 2.4 CNEInstance’s advanced.<component>.env[] lists (#175).
tmm_resourcesmap[string]map[string]string2.3 + 2.4—noTMMResources overrides the TMM pod’s resource requests/limits, rendered as the CNEInstance’s advanced.tmm.resources (#203).
gslb_datacenter_namestring2.3 + 2.4—noGSLBDatacenterName sets the optional CNEInstance GSLB datacenter name (rendered as cneinstance_gslb_datacenter_name).
cert_manager*BNKCertManagerCfg2.3 + 2.4—noCertManager overrides cert-manager’s namespace + chart version.
network*BNKNetworkCfg2.3 + 2.4—noNetwork holds the optional per-zone subnet CIDRs + TMM self-IPs for the cloud-network-mapping ConfigMap and the external/internal F5SPKVlan CRs (BNK install-guide “Configuration”).
cis*BNKCISCfg2.3 + 2.4—noCIS holds the BIG-IP management endpoint + credentials the BNK CIS controller (k8s-bigip-ctlr) uses.
license_modestring2.3 + 2.4connectednoLicenseMode selects the License CR operationMode: “connected” (default when empty), “disconnected”, or “f5licenseproxy”.
flp*BNKFLPCfg2.3 + 2.4—noFLP holds settings for the optional F5 License Proxy phase.
preflight*BNKPreflightCfg2.3 + 2.4—noPreflight tunes the pre-install checks bnk up runs before it plans anything.

BNKFLPCfg

BNKFLPCfg configures the F5 License Proxy (FLP) phase deployment. All optional; nil block means FLP is off. It never carries secrets — the FLP generates its own certs, and its subscription JWT is the same one resolved from COS.

keytypelinedefaultrequireddescription
modestring2.3 + 2.4—noMode selects HOW the FLP phase deploys the proxy: “” | “helm” → the f5-license-proxy Helm chart into the ROKS cluster (default).
vsi*BNKFLPVSICfg2.3 + 2.4—noVSI configures the mode: vsi deployment backend.
namespacestring2.3 + 2.4—noNamespace the FLP is installed into (helm mode).
chart_versionstring2.3 + 2.4—noChartVersion pins the f5-license-proxy chart.
storage_classstring2.3 + 2.4—noStorageClass is the dynamic StorageClass for the FLP’s PVCs (rendered as flp_storage_class).
node_port_accessbool2.3 + 2.4—noNodePortAccess exposes the proxy OUTSIDE its own cluster, so a BNK install in a DIFFERENT cluster (same VPC, or across a transit gateway) can license through it — the “shared licensing cluster” topology, where only the cluster running the proxy needs egress to F5.
node_port_source_cidrs[]string2.3 + 2.4—noNodePortSourceCIDRs, when set with NodePortAccess, opens the proxy’s NodePort on the cluster’s worker security group to these CIDRs — the consuming cluster’s subnets.
external*BNKFLPExternalCfg2.3 + 2.4—noExternal points a workspace at a FOREIGN proxy — one deployed by a DIFFERENT workspace/cluster.

BNKFLPExternalCfg

BNKFLPExternalCfg addresses an F5 License Proxy that this workspace does not own. Both fields come from the owning workspace’s roksbnkctl flp output — the URL is its externally-reachable endpoint and the CA is its (base64) root CA, which the CWC must trust to complete the TLS handshake to the proxy.

keytypelinedefaultrequireddescription
urlstring2.3 + 2.4—noURL of the proxy, e.g. https://10.240.64.5:30001 — reachable from THIS cluster’s pods.
root_ca_b64string2.3 + 2.4—noRootCAB64 is the proxy’s root CA, base64-encoded (as flp output emits it).

BNKFLPForwardProxyCfg

BNKFLPForwardProxyCfg describes an egress forward proxy for the FLP VSI’s calls to F5’s licensing backend (product-s.apis.f5.com).

keytypelinedefaultrequireddescription
hoststring2.3 + 2.4—noHost is the forward proxy’s address.
portint2.3 + 2.4—noPort is the forward proxy’s port.
protocolstring2.3 + 2.4—nohttp (default) | https.

BNKFLPVSICfg

BNKFLPVSICfg configures the mode: vsi FLP backend — a standalone VSI running the f5-license-proxy stack as a podman pod. All fields optional; sensible defaults apply.

keytypelinedefaultrequireddescription
name_prefixstring2.3 + 2.4—noNamePrefix prefixes the FLP VSI’s IBM Cloud resource names — instance, subnet, security group, floating IP, public gateway, boot volume, and the VPC when this module creates one.
vpcstring2.3 + 2.4—noVPC is an existing VPC id to deploy the standalone FLP VSI into, WITHOUT any ROKS cluster.
create_vpcbool2.3 + 2.4—noCreateVPC builds the proxy its OWN VPC, address prefix and public gateway rather than placing it in one that already exists (#60).
vpc_namestring2.3 + 2.4—noVPCName names the VPC created when CreateVPC is set.
subnet_cidrstring2.3 + 2.4—noSubnetCIDR is the address prefix for that VPC.
profilestring2.3 + 2.4—noProfile is the IBM Cloud VSI instance profile.
zonestring2.3 + 2.4—noZone the VSI lands in (e.g. us-south-1).
boot_size_gbint2.3 + 2.4—noBootSizeGB is the boot volume size.
management_allowed_cidrs[]string2.3 + 2.4—noManagementAllowedCIDRs are the source CIDRs permitted to reach the :80 flp-status web UI (read-only status).
licensing_allowed_cidrs[]string2.3 + 2.4—noLicensingAllowedCIDRs are the source CIDRs permitted to reach the :8443 licensing proxy (and :22 SSH).
allowed_cidrs[]string2.3 + 2.4—noAllowedCIDRs is DEPRECATED — a legacy single list.
ssh_keystring2.3 + 2.4—noSSHKey is the name of an existing IBM Cloud VPC SSH key (RSA) to attach to the FLP VSI, so an operator can SSH in to inspect/recover the licensing appliance (podman pod, Vault, logs).
floating_ip*bool2.3 + 2.4—noFloatingIP attaches an operator floating IP to the FLP VSI for remote management — running roksbnkctl flp status and reaching the :80 web UI + the :8443 proxy from a machine OUTSIDE the VPC.
status_imagestring2.3 + 2.4—noStatusImage, when set, runs the flp-status web UI as a container in the FLP pod (mobile-friendly status page + /api/status + live logs on :80, no auth — a read-only private status endpoint).
status_registry_hoststring2.3 + 2.4—noStatusRegistryHost + StatusRegistryCAB64 make the VSI trust a self-signed mirror so it can pull StatusImage: cloud-init drops the (base64) CA into /etc/containers/certs.d/<host>/ca.crt before the pod comes up.
status_registry_ca_b64string2.3 + 2.4—noStatusRegistryCAB64 is that registry’s CA, base64-encoded, written to /etc/containers/certs.d/<host>/ca.crt on the VSI.
forward_proxy*BNKFLPForwardProxyCfg2.3 + 2.4—noForwardProxy optionally routes the VSI’s egress to F5 licensing through an HTTP forward proxy (air-gapped/egress-controlled networks).

BNKForgeCfg

BNKForgeCfg is the optional integration with a co-located BNK Forge (v3) install. When Register is true, cluster up registers the just-provisioned ROKS cluster with BNK Forge via its REST API — credential-backed, so BNK Forge derives the kubeconfig on demand from an IBM Cloud credential template rather than storing a perishable one. Best-effort: registration never blocks or fails the deploy. nil/absent (legacy config) = no-op.

keytypelinedefaultrequireddescription
registerbool2.3 + 2.4—noRegister opts the workspace in.
urlstring2.3 + 2.4—noURL is the BNK Forge server base URL (e.g. https://forge.example.com).
projectstring2.3 + 2.4—noProject is the target BNK Forge project NAME.
usernamestring2.3 + 2.4—noUsername is the BNK Forge login user.
password_b64string2.3 + 2.4—noPasswordB64 is that user’s password, base64-encoded — obfuscation, NOT encryption, exactly as bnk.cis.bigip_password_b64 and registry.generic_password_b64 are.
insecurebool2.3 + 2.4—noInsecure skips TLS verification against the Forge server.
ca_b64string2.3 + 2.4—noCAB64 pins the CA the Forge server’s certificate must chain to, PEM, base64-encoded.

BNKNetworkCfg

BNKNetworkCfg is the optional cloud-network-mapping / VLAN zone data.

keytypelinedefaultrequireddescription
zones[]BNKZoneCfg2.3 + 2.4—noZones is the per-availability-zone network mapping, in zone order — one entry per zone the cluster spans.
vlan_prefixlen*int2.324noVLANPrefixLen is the self-IP prefix length (spec.prefixlen_v4) TMM applies to its external and internal self-IPs on the F5SPKVlan CRs — the size of the L2 subnet TMM treats as directly connected on each VLAN.
vlan_prefixlen_external*int2.3—noVLANPrefixLenExternal / VLANPrefixLenInternal override VLANPrefixLen for one VLAN.
vlan_prefixlen_internal*int2.3—noVLANPrefixLenInternal is the same override for the INTERNAL VLAN.
tmm_k8s_routesstring2.3 + 2.4172.17.0.0/18noTMMK8SRoutes is the Kubernetes pod CIDR TMM installs a route toward (advanced.tmm.env TMM_K8S_ROUTES), so TMM can reach backend pods on the internal data path.

BNKPreflightCfg

BNKPreflightCfg tunes the per-node reachability gate. These are exposed because the right values are a property of the ENVIRONMENT, not of roksbnkctl. A Transit Gateway attachment is asynchronous — IBM programs the routes some time after the connection reports attached — and how long that takes varies by account, region and gateway. A probe run ~73s after attach saw both targets unreachable and refused an install whose path was healthy minutes later (issue #57), while a sibling cluster on the same gateway passed simply by landing on the other side of route programming. A site that consistently sees slower propagation should raise the budget rather than rediscover the race; a site with a static, long-established gateway can lower it to fail faster.

keytypelinedefaultrequireddescription
reachability_retry_seconds*int2.3 + 2.4—noReachabilityRetrySeconds is how long a target may keep failing before the verdict is believed.
reachability_timeout_seconds*int2.3 + 2.4—noReachabilityTimeoutSeconds is how long to wait for the probe DaemonSet to report from every node.

BNKTrustedProfileCfg

BNKTrustedProfileCfg is the IBM Cloud Trusted Profile the CNE controller assumes at runtime — the identity that lets it manage the VPC network attachments it creates for TMM, without a stored API key. Both fields default in the HCL rather than here, so an absent block renders nothing and the shipped terraform decides — the same rule every other optional BNK field follows.

keytypelinedefaultrequireddescription
service_accountstring2.3 + 2.4—noServiceAccount is the Kubernetes service account the profile is LINKED to: which account may assume it.
roles[]string2.3 + 2.4[Viewer, Editor]noRoles granted to the profile, scoped to the cluster’s OWN VPC.

BNKZoneCfg

BNKZoneCfg is one availability zone’s subnet CIDRs + TMM self-IPs. Field order/names match the terraform cneinstance_network_zones object.

keytypelinedefaultrequireddescription
ext_vlan_cidrstring2.3 + 2.4—yesExtVLANCIDR is the zone’s EXTERNAL VLAN — the client side of the data plane, where traffic arrives.
int_vlan_cidrstring2.3—yesIntVLANCIDR is the zone’s INTERNAL VLAN — the pod side, where BNK reaches the workloads it fronts.
int_snat_cidrstring2.3 + 2.4—yesIntSNATCIDR is the pool BNK source-NATs to when it talks to pods, so the return traffic comes back through TMM rather than routing around it.
int_vip_cidrstring2.3 + 2.4—yesIntVIPCIDR is the range virtual servers are allocated from on the internal side.
external_selfipstring2.3—yesExternalSelfIP is TMM’s own address on the external VLAN.
internal_selfipstring2.3—yesInternalSelfIP is TMM’s own address on the internal VLAN.

COSCfg

COSCfg points roksbnkctl at the IBM Cloud Object Storage that holds the FAR auth key + subscription JWT (the “orchestration” COS). Empty fields fall back to the built-in defaults (bnk-supply-chain / bnk-artifacts / us-south). These are honoured BOTH by the terraform render (ibmcloud_cos_instance_name / ibmcloud_resources_cos_bucket / ibmcloud_cos_bucket_region) AND by the registry FAR-file resolver, so a customer-owned COS bucket is used consistently across both.

keytypelinedefaultrequireddescription
instancestring2.3 + 2.4bnk-supply-chainnoInstance is the IBM Cloud Object Storage service instance holding the bucket.
bucketstring2.3 + 2.4bnk-artifactsnoBucket is the bucket the FAR service-account credential is read from, for estates that stage it centrally rather than passing a local file.
regionstring2.3 + 2.4us-southnoRegion is the bucket’s region, which need not match ibmcloud.region.
resource_groupstring2.3 + 2.4—noResourceGroup is the IBM Cloud resource group holding Instance.
upload[]COSUpload2.3 + 2.4—noUpload lists local files to place into that bucket before the phases that read them run.

COSUpload

keytypelinedefaultrequireddescription
sourcestring2.3 + 2.4—yesSource is the local file to upload.
keystring2.3 + 2.4—yesKey is the object name it is stored under in the bucket.

ClusterCfg

keytypelinedefaultrequireddescription
createbool2.3 + 2.4—yesCreate decides whether this workspace BUILDS the ROKS cluster or adopts one that already exists.
namestring2.3 + 2.4—yesName is the ROKS cluster’s name — the one to create, or the existing one to adopt when Create is false.
openshift_versionstring2.3 + 2.4—noOpenShiftVersion pins the OpenShift version for a CREATED cluster (e.g. “4.20”).
workers_per_zoneint2.3 + 2.41noWorkersPerZone is the worker count PER ZONE, not in total: ROKS spans three availability zones, so 2 here is a six-node cluster.
public_gateway*bool2.3 + 2.4truenoPublicGateway controls whether the cluster subnets attach a public gateway for worker Internet egress.
vpc_cidrstring2.3 + 2.4—noVPCCIDR is the block the cluster VPC’s per-zone address prefixes are carved from — “10.241.0.0/16” becomes 10.241.0.0/18, 10.241.64.0/18, 10.241.128.0/18.
network_modestring2.3 + 2.4single-nicnoNetworkMode selects how the cluster’s worker nodes are attached: “single-nic” (the default, and today’s only behaviour) or “multi-nic”.
existing_subnet_ids[]string2.3 + 2.4—noExistingSubnetIDs places the cluster in subnets that ALREADY EXIST, one per zone in zone order, instead of creating them (#61).
worker_flavorstring2.3 + 2.4—noWorkerFlavor names the worker profile EXACTLY, e.g. “cx3d.8x20”.
min_worker_vcpu_countint2.3 + 2.416noMinWorkerVCPUCount is the vCPU floor for the worker-flavor auto-select: the cluster module picks the smallest bx2 profile meeting this and MinWorkerMemoryGB.
min_worker_memory_gbint2.3 + 2.464noMinWorkerMemoryGB is the memory floor for the same auto-select.

ConnectivityCfg

keytypelinedefaultrequireddescription
extra_hosts[]string2.3 + 2.4—noExtraHosts are additional targets the connectivity probe tries, beyond the defaults.

DNSCfg

DNSCfg drives the Sprint 5 flag-driven DNS probe (PRD 03 §“DNS probe (GSLB-aware)” §“Server resolution”). The map’s keys are the names users pass to --server <name> and the values are concrete “<ip>[:<port>]” strings the miekg/dns client dials. DefaultTarget is used when –target isn’t passed on the command line. Example: test: 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”

keytypelinedefaultrequireddescription
resolversmap[string]string2.3 + 2.4—noResolvers names the DNS servers to query, as name → “<ip>[:<port>]”.
default_targetstring2.3 + 2.4—noDefaultTarget is the resolver queried when a probe names none.

ExecToolCfg

ExecToolCfg is one entry under workspace.Exec — the chosen backend for a given tool.

keytypelinedefaultrequireddescription
backendstring2.3 + 2.4—yesBackend is the execution-backend spec: “local” | “docker” | “k8s” | “ssh:<target>”.

GatewayCfg

keytypelinedefaultrequireddescription
app_namespacestring2.3 + 2.4f5-appnoAppNamespace is the namespace the example application and its Gateway resources are created in.
class_namestring2.3 + 2.4gateway-classnoClassName is the GatewayClass name.
controller_namestring2.3 + 2.4—noControllerName is the GatewayClass controllerName.
backend_servicestring2.3 + 2.4nginx-servicenoBackendService is the Kubernetes Service the example HTTPRoute forwards to.
backend_portint2.3 + 2.480noBackendPort is the port on that Service.
egress_modestring2.3 + 2.4snatpoolnoEgressMode selects how return traffic is source-addressed: “snatpool”, “automap”, or “both”.
client_subnet_local[]string2.3 + 2.4—noClientSubnetLocal lists client CIDRs reachable on the same VPC as the cluster — routed directly rather than over the transit gateway.
client_subnet_remote[]string2.3 + 2.4—noClientSubnetRemote lists client CIDRs reached ACROSS the transit gateway, e.g. the testing client VPC.
vxlan_portint2.3 + 2.46789noVXLANPort is the UDP port for the VXLAN overlay between TMM and the nodes.
route_examples[]string2.3 + 2.4—noRouteExamples names extra route kinds to create WORKING examples of, alongside the HTTPRoute the gateway phase already creates.
l4_listener_portint2.3 + 2.48080noL4ListenerPort is the port for that TCP listener.

HugepagesCfg

HugepagesCfg allocates hugepages on the worker pool through the OpenShift Node Tuning Operator. BNK’s deploymentSize decides how much TMM asks for: Tiny requests none, Small requests 4Gi of hugepages-2Mi. A stock ROKS worker reports zero — including F5’s approved reference cluster, which runs Tiny for exactly this reason. So any size above Tiny needs this, or nodes prepared some other way. APPLYING THIS REBOOTS WORKERS. The profile sets a bootloader kernel argument, and the Machine Config Operator rolls the pool to apply it — draining and restarting each node in turn. On a live cluster that is a maintenance event, not a configuration change.

keytypelinedefaultrequireddescription
enabledbool2.3 + 2.4—yesEnabled allocates hugepages.
sizestring2.3 + 2.42MnoSize is the hugepage size, e.g. “2M” or “1G”.
countint2.3 + 2.42048noCount is the number of pages PER NODE.
node_rolestring2.3 + 2.4workernoNodeRole is the machineconfiguration.openshift.io/role the profile applies to.
profile_namestring2.3 + 2.4bnk-hugepagesnoProfileName names the Tuned profile and CR.

IBMCloudCfg

keytypelinedefaultrequireddescription
regionstring2.3 + 2.4—yesRegion is the IBM Cloud region everything in this workspace is created in or adopted from, e.g. “us-east”.
resource_groupstring2.3 + 2.4defaultyesResourceGroup is the IBM Cloud resource group resources are placed in, and the one an adopted cluster is looked up in.
api_key_sourcestring2.3 + 2.4—noenv | keychain | config | prompt — see secrets.go.
api_key_b64string2.3 + 2.4—noAPIKeyB64 stores the API key base64-encoded inline in the workspace config.

RegistryCfg

RegistryCfg configures the Sprint 29 air-gap registry mirror (PRD 11): which target the roksbnkctl registry replicate populates and which namespace it uses, plus the optional source/target credentials. All fields are optional — an absent block (nil) means the mirror is not configured and the BNK install pulls directly from FAR (far_repo_url). Additive + omitempty, so existing config.yaml files load unchanged.

keytypelinedefaultrequireddescription
targetstring2.3 + 2.4—noTarget selects the mirror backend: “icr” (IBM Container Registry — the DEFAULT when unset) or “generic” (any OCI-compliant registry — Artifactory / Harbor / Quay / registry:2).
icr_hoststring2.3 + 2.4—noICRHost overrides the IBM Container Registry host for target=icr (e.g. “de.icr.io”).
icr_namespacestring2.3 + 2.4—noICRNamespace is the ICR namespace artifacts nest under for target=icr.
generic_hoststring2.3 + 2.4—noGenericHost is the OCI registry host for target=generic (e.g. “artifactory.example.com”).
generic_repo_prefixstring2.3 + 2.4—noGenericRepoPrefix is the repository path artifacts nest under for target=generic (e.g. an Artifactory repo key).
generic_usernamestring2.3 + 2.4—noGenericUsername / GenericPasswordB64 are the static basic-auth credential for target=generic (an Artifactory user + access token).
generic_password_b64string2.3 + 2.4—noGenericPasswordB64 is that user’s password or access token, base64-encoded — obfuscation, not encryption.
generic_ca_b64string2.3 + 2.4—noGenericCAB64 is the mirror’s CA chain, PEM, base64-encoded — the AUTHORITATIVE copy, recorded from the file that generated it rather than learned from the network.
generic_ca_sha256string2.3 + 2.4—noGenericCASHA256 pins the mirror’s CA by SHA-256 (hex; a “sha256:” prefix and colons are accepted).
namespacestring2.3 + 2.4—noNamespace is the mirror project the artifacts land in.
include_deps*bool2.3 + 2.4—noIncludeDeps unions the non-F5 dependency artifacts (Jetstack cert-manager chart + images, the registry.k8s.io/kubectl node-labeler image) into the BOM.
source_service_account_b64string2.3 + 2.4—noSourceServiceAccountB64 is the FAR _json_key_base64 service-account JSON, base64-encoded, used as the replication SOURCE credential for repo.f5.com.

ResourceToggle

ResourceToggle is one create/reuse decision: Create=true provisions the resource (under its prefix-derived name); Create=false reuses an existing one named by Existing (when a live dependent consumes it).

keytypelinedefaultrequireddescription
createbool2.3 + 2.4—yesCreate decides whether roksbnkctl provisions this resource or adopts one that already exists.
existingstring2.3 + 2.4—noExisting is the name or ID of the resource to adopt when Create is false.

ResourcesCfg

ResourcesCfg holds the per-resource create toggles for a prefix-driven workspace (Sprint 26). The cluster itself is NOT here — it reuses the existing ClusterCfg.Create / ClusterCfg.Name (Name doubles as the existing id/name when Create=false, as today). Each toggle carries an Existing name/ID used when Create=false and a live dependent still needs to reference the resource by name.

keytypelinedefaultrequireddescription
transit_gatewayResourceToggle2.3 + 2.4—yesTransitGateway controls the transit gateway the cluster VPC attaches to.
registry_cosResourceToggle2.3 + 2.4—yesRegistryCOS controls the IBM Cloud Object Storage bucket that backs a mirror registry.
cert_managerResourceToggle2.3 + 2.4—yesCertManager controls whether cert-manager is INSTALLED or adopted.
bnkResourceToggle2.3 + 2.4—yesBNK controls whether the BIG-IP Next for Kubernetes install runs at all.
tgw_jumphostResourceToggle2.3 + 2.4—yesTGWJumphost controls the optional testing jumphost in the client VPC.
cluster_jumphostsResourceToggle2.3 + 2.4—yesClusterJumphosts controls the per-cluster jumphosts.
client_vpcResourceToggle2.3 + 2.4—yesClientVPC controls the testing client VPC that the jumphost lives in.
cluster_vpcResourceToggle2.3 + 2.4—yesClusterVPC controls the ROKS cluster’s OWN VPC.
client_regionstring2.3 + 2.4—noClientRegion is the region the testing client (TGW jumphost + client VPC) is installed in.
testing_client_vpc_namestring2.3 + 2.4tf-testing-vpcnoTestingClientVPCName names the testing client VPC when ClientVPC.Create is true (rendered as testing_client_vpc_name).
testing_ssh_key_namestring2.3 + 2.4—noTestingSSHKeyName is the IBM Cloud VPC SSH key name attached to the testing jumphosts (rendered as testing_ssh_key_name).
testing_jumphost_profilestring2.3 + 2.4—noJumphost sizing.
testing_min_vcpu_countint2.3 + 2.44noTestingMinVCPUCount is the vCPU floor for the jumphost auto-select.
testing_min_memory_gbint2.3 + 2.48noTestingMinMemoryGB is the memory floor for the same auto-select.
testing_jumphost_allowed_cidrs[]string2.3 + 2.4—noSecurity-group source CIDRs, following the flp_vsi module’s split between a management plane and an in-fabric plane.
testing_client_vpc_inbound_cidrs[]string2.3 + 2.4—noTestingClientVPCInboundCIDRs gates the client VPC’s DEFAULT security group, which the testing phase widens to all protocols and ports.
cluster_http_allowed_cidrs[]string2.3 + 2.4—noClusterHTTPAllowedCIDRs gates :80 on the cluster security group — the ingress/ALB path, which is meant to be publicly reachable, so empty means open.
cluster_vpc_default_sg_inbound_cidrs[]string2.3 + 2.4—noClusterVPCDefaultSGInboundCIDRs gates the cluster VPC’s DEFAULT security group, which the cluster phase widens to all protocols and ports.
copied_ssh_key_files[]string2.3 + 2.4—noCopiedSSHKeyFiles lists the ~/.ssh basenames roksbnkctl init ACTUALLY wrote when the user accepted the “copy the private key to ~/.ssh” prompt (only files it created — pre-existing files are skipped, never recorded).

StateCfg

GatewayCfg carries optional overrides for the Gateway phase (the BNK data-plane config). Every field is optional — unset values fall back to the terraform gateway module’s BNK install-guide defaults. Rendered as gateway_* tfvars. The phase itself is driven by roksbnkctl gateway up/down, not a toggle here. StateCfg selects where terraform state lives (PRD 16). Backend “” or “local” (the default) keeps per-phase local tfstate under the workspace dir — the original behaviour. “s3” stores each phase’s state in an S3-compatible bucket (IBM COS), so a stateless runner / parallel CI needs no shared volume, with native lockfile locking (terraform >= 1.10). Additive + omitempty — an absent state: block loads as the local default.

keytypelinedefaultrequireddescription
backendstring2.3 + 2.4—no“” | “local” | “s3”.
s3*StateS3Cfg2.3 + 2.4—noS3 configures an S3-compatible backend (IBM COS) for terraform state, so a workspace is not tied to one machine’s disk.

StateS3Cfg

StateS3Cfg configures the COS/S3 remote backend. The HMAC access/secret keys are NOT stored here — KeySource names the env var they come from (env-first), and roksbnkctl injects them as AWS_ env to the terraform child, never into the rendered HCL or the state object.

keytypelinedefaultrequireddescription
endpointstring2.3 + 2.4—yesCOS S3 endpoint URL.
bucketstring2.3 + 2.4—yespre-provisioned bucket.
regionstring2.3 + 2.4—yesCOS location / region.
key_prefixstring2.3 + 2.4—nodefault: the workspace name.
access_key_sourcestring2.3 + 2.4—noenv var name; default ROKSBNKCTL_COS_HMAC_ACCESS_KEY.
secret_key_sourcestring2.3 + 2.4—noenv var name; default ROKSBNKCTL_COS_HMAC_SECRET_KEY.

TFSourceCfg

TFSourceCfg picks where Terraform’s source tree comes from. Type drives which other fields apply: - embedded — uses the HCL bundled into the roksbnkctl binary via Go’s embed directive. No other fields needed. This is the default and what most users want; install one binary, get CLI + matched TF together. - github — downloads a tarball release from a GitHub repo. Repo (“owner/name”) and Ref (release tag) required. For testing forks or pinning to a specific upstream tag. - local — points Terraform at a directory on disk. Path required. For active development on the HCL itself. An empty Type (legacy / forgot-to-set) is treated as embedded.

keytypelinedefaultrequireddescription
typestring2.3 + 2.4—yesType selects where the Terraform comes from: “embedded” (the tree compiled into this binary — the default, and the only one guaranteed to match it), “github” (a released tree), or “local” (a path on disk, for testing a fork).
repostring2.3 + 2.4—noRepo is the owner/name to fetch from when Type is “github”.
refstring2.3 + 2.4—noRef is the tag, branch or commit to fetch when Type is “github”.
pathstring2.3 + 2.4—noPath is the local directory holding the Terraform tree when Type is “local”.

TargetCfg

TargetCfg is the on-disk shape of one entry under targets: in the workspace config. Lives in this package (rather than internal/remote) to avoid an import cycle: workspace.go needs to (de)serialise it, internal/remote needs to consume it. Keeping the wire shape here and the runtime Target type in internal/remote keeps the dep direction clean (remote → config, never the reverse).

keytypelinedefaultrequireddescription
hoststring2.3 + 2.4—yesHost is the target’s address, reached over SSH.
portint2.3 + 2.422noPort is its SSH port.
userstring2.3 + 2.4—yesUser is the SSH login.
key_pathstring2.3 + 2.4—nofile path (PEM).
key_sourcestring2.3 + 2.4—no“agent” | “tf-output:<name>”.

TestCfg

keytypelinedefaultrequireddescription
throughputThroughputCfg2.3 + 2.4—noThroughput configures the iperf3 bandwidth probe.
connectivityConnectivityCfg2.3 + 2.4—noConnectivity configures the reachability probes — the hosts roksbnkctl test tries to reach, and from where.
dnsDNSCfg2.3 + 2.4—noDNS configures the name-resolution probes, including which resolvers to ask.

ThroughputCfg

keytypelinedefaultrequireddescription
imagestring2.3 + 2.4networkstatic/iperf3:latestnodefault: networkstatic/iperf3:latest.
durationint2.3 + 2.430noseconds; default 30.
streamsint2.3 + 2.48noparallel; default 8.
default_modestring2.3 + 2.4north-southnonorth-south | east-west.