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

tfcapi-lint CLI

tfcapi-lint checks a Terraform/OpenTofu module, or the image built from it, against the CAPTF module contract. See tfcapi-lint for how to install and run it.

Global flags

FlagTypeDefaultDescription
--versionversionfalse–version, –version=raw prints version information and quits; –version=vX.Y.Z… sets the reported version

image <image-ref>

Lint a built source image against the image contract.

FlagTypeDefaultDescription
--all-platformsboolfalsecheck every platform of a multi-platform image
--allow-warningstringSlice[]downgrade this check ID’s warnings to info (repeatable); errors cannot be allowed
--contractstringv1alpha1contract version
--insecureboolfalseallow a plain-HTTP registry
--jsonboolfalseprint JSON instead of text
--platformstringlinux/amd64the platform to check in a multi-platform image
--rolestringmodule role: cluster, machine or machinepool (required)
--strictboolfalsetreat warnings as errors for the exit code

module <module-dir>

Lint a module directory against the contract.

FlagTypeDefaultDescription
--allow-warningstringSlice[]downgrade this check ID’s warnings to info (repeatable); errors cannot be allowed
--contractstringv1alpha1contract version
--jsonboolfalseprint JSON instead of text
--rolestringmodule role: cluster, machine or machinepool (required)
--strictboolfalsetreat warnings as errors for the exit code

version

Print the version and supported contract versions.

FlagTypeDefaultDescription
--jsonboolfalseprint JSON instead of text

Exit codes

CodeNameMeaning
0ExitOKno errors (and, with –strict, no warnings).
1ExitFindingsat least one error, or a warning under –strict.
2ExitUnparsablethe module could not be read or parsed, or the image could not be pulled or extracted.
3ExitUsagebad command line.

Checks

IDSeverityRolesDescription
input/defaultwarningcluster, machine, machinepoola contract input the controller always sets to a non-null value nonetheless carries a default, which would mask a controller mistake.
input/requirederrorcluster, machine, machinepoola contract input is not declared as a variable.
input/reservederrorcluster, machine, machinepoola variable uses the reserved captf_ prefix but is not itself a contract input.
input/sensitivewarningcluster, machine, machinepoolbootstrap_data is declared but not sensitive = true, though it carries the bootstrap payload.
input/tags-declarederrorcluster, machine, machinepoolthe module does not declare captf_tags, the mandatory common input every module must accept.
input/tags-unusedwarningcluster, machine, machinepoolcaptf_tags is declared but never referenced, directly or forwarded into a nested local module that references it.
input/typeerrorcluster, machine, machinepoola contract input’s declared type does not accept what the generated root passes, is missing, or could not be read.
input/user-variable-defaultwarningcluster, machine, machinepoola variable outside the contract (a user variable) has no default, so an object that does not set it in spec.variables or variablesFrom fails to apply.
module/backenderrorcluster, machine, machinepoolthe root or a nested module declares a terraform { backend } block; the generated root owns the backend.
module/clouderrorcluster, machine, machinepoolthe root or a nested module declares a terraform { cloud } block; the generated root owns it, the same as module/backend.
module/provider-configwarningcluster, machine, machinepoolthe root or a nested module declares its own provider configuration; the generated root owns provider configuration.
module/tofu-shadowwarningcluster, machine, machinepoola .tofu file shadows a .tf file, and the declarations OpenTofu loads from it differ from Terraform’s.
module/versioninfocluster, machine, machinepoolinformational; reports the module’s declared required_version constraint, or its absence.
output/endpoint-never-setwarningclusterthe control_plane_endpoint output is a literal null, so a KubeadmControlPlane cluster with no user-set endpoint would wait forever.
output/healtherrorcluster, machine, machinepoolthe health output is declared with the wrong shape for the contract’s health check.
output/provider-id-list-shapeerror (the output is missing or not a list), warning (the expression is not sorted and deduplicated)machinepoolthe machinepool role’s provider_id_list output is missing, or its expression does not look like it forwards one ID per instance.
output/requirederrorcluster, machine, machinepoola contract output is not declared.
output/reservedwarningcluster, machine, machinepoolan output uses a name reserved for a future contract output.
pool/autoscaling-ignore-changeswarningmachinepoolthe module uses var.autoscaling but no resource ignores changes to its desired capacity, so every apply resets the cloud autoscaler’s decision.