fmt and validate

terraform fmt and terraform validate are the two cheapest checks Terraform ships, and they belong in CI as the first gate before anything slower runs. fmt rewrites your HCL into one canonical style so diffs stop arguing about spacing. validate checks that the configuration is internally consistent — syntax parses, references resolve, argument types match — and it does this without calling a single Google Cloud API.

The catch that trips up everyone once is what validate does not do. A config can pass validate cleanly and still fail at apply because it names a bucket someone already owns, requests an API that is disabled, or sets an IAM binding the caller cannot grant. "Validates" means internally consistent, not "the apply will work." Keep that line sharp and these two commands earn their place at the front of every pipeline.

What fmt Does

terraform fmt rewrites every .tf file in a directory to canonical indentation, alignment, and spacing — two-space indents, aligned = signs within a block, consistent blank lines. It changes formatting only, never meaning. The value is that style stops being a thing humans argue about in review: there is exactly one correct layout, and a machine produces it.

In CI the relevant form is terraform fmt -check -recursive. The -check flag makes it report rather than rewrite, exiting non-zero when any file is unformatted, and -recursive walks subdirectories so modules are covered too. Wire that as a step that fails the build, and a misformatted file never reaches a reviewer.

# locally: rewrite files in place
terraform fmt -recursive

# in CI: fail if anything is unformatted, change nothing
terraform fmt -check -recursive

The first form is what you run on save or before a commit; the second is what the pipeline runs. They share an opinion about what "formatted" means, so an engineer who runs fmt locally will always pass the -check gate.

What validate Checks

terraform validate confirms the configuration is internally consistent. It checks that the HCL parses, that every reference resolves to something declared — that google_storage_bucket.raw.name points at a bucket resource that actually exists in the config — and that argument types and required fields are satisfied against the provider's schema. A required argument left out, a string where a number belongs, a reference to a resource you deleted: all caught here.

All of that happens against the provider schema, not against Google Cloud. validate reads no state and makes no API calls. It is checking the shape of your config, not the state of your project — which is exactly why it is fast and safe to run anywhere.

What validate Does NOT Check

This is the distinction worth internalizing. validate will pass a config that names a bucket someone else already owns, that requests a resource in compute.googleapis.com when that API is disabled on the project, or that sets an IAM binding the running identity has no permission to grant. None of those are inconsistencies in your config — they are facts about the real world that validate never consults.

Those failures surface only at plan or apply, when Terraform actually talks to GCP. So validate answers "is this config well-formed?" and plan answers "will this config work against my project right now?" Treating a green validate as a promise that apply will succeed is the single most common misreading of the command.

validate Needs init, Not Credentials

validate needs the provider plugins installed, because it checks your arguments against the provider's schema — and that schema ships inside the google provider. So terraform init must run first to download providers. But it needs no credentials and reads no state, because it never calls an API.

That combination is what makes validate ideal early in CI: run init with the provider cache, then validate offline, with no service account key or workload identity in scope. The credentialed steps come later, only for configs that already parse cleanly.

The Cheap-First Gate

Order a CI pipeline cheap-to-expensive so the fast checks catch the dumb errors before the slow ones spend money: fmt -check first, then validate, then tflint and security scanners, then plan against real GCP. The first two are offline and uncredentialed and finish in seconds. plan needs credentials, reads state, and calls APIs — so it runs last, only on configs that already passed everything cheaper.

The payoff is that a missing comma or an unresolved reference fails the build in seconds, not after a minute of provider negotiation and state refresh. A pipeline that runs plan first wastes credentialed time discovering errors a free offline check would have caught instantly.

# 1. offline, no credentials, seconds
terraform fmt -check -recursive
terraform init -backend=false
terraform validate

# 2. offline scanners (next topic)
tflint --recursive

# 3. credentialed, calls GCP, runs last
terraform plan -out=plan.out

Note init -backend=false in the offline stage: it installs providers so validate has schemas, without configuring the GCS backend or touching remote state. The real init with the backend happens in the credentialed stage before plan.