Data Sources

A data source reads information about something Terraform does not manage — an existing image, the current project, your own resolved credentials — and makes it available to your config without taking ownership of it. It is a lookup, not a declaration: the read happens, the value is yours to use, and nothing in the cloud is created, changed, or deleted.

On GCP this is how you pin event-processor's base image to a real google_compute_image, discover the project number behind hatch-pipeline-dev, or list the zones in us-central1 to spread instances across. The rule is one word: read, never manage. Everything you intend to create is a resource; everything you only need to reference is a data source.

Read vs Manage

A resource block creates, updates, and destroys an object — it owns it across its whole lifecycle. A data block only reads an existing object and never owns it. The practical tell is the plan: a data source never appears as a + create or - destroy action, only as a <= read. Delete a data block from your config and nothing in the cloud changes, because Terraform never owned the thing it was reading.

data "google_compute_image" "cos" {
  family  = "cos-stable"
  project = "cos-cloud"
}

This resolves the Container-Optimized OS stable family in Google's public cos-cloud project to a concrete image, which you then reference as data.google_compute_image.cos.self_link. You did not create the image and you cannot destroy it — you are only looking it up.

The Workhorse GCP Data Sources

Four data sources cover most day-to-day needs. google_compute_image resolves an image family to a concrete image ID. google_project returns the number and labels of a project — useful because many IAM and resource references need the numeric project id, not the human-readable one. google_client_config exposes the caller's resolved access token and active project. And google_compute_zones lists the available zones in a region so you can spread instances without hardcoding zone names.

google_client_config as the Auth Smoke Test

Before you debug anything deeper, reach for google_client_config. Reading data "google_client_config" "current" and outputting its project is the trivial plan that proves Application Default Credentials are resolving and that Terraform knows which project it is pointed at. If that one-line plan succeeds, your auth works; if it fails, you have isolated the problem to credentials before touching a single real resource.

data "google_client_config" "current" {}

output "active_project" {
  value = data.google_client_config.current.project
}

The Plan-Time Read Gotcha

Data sources resolve during plan when their arguments are already known. A google_compute_image with a literal family and project reads immediately, and its result is concrete in the plan. But if a data source's arguments depend on a value that is (known after apply) from a not-yet-created resource, its read cannot happen at plan time — it is deferred to apply.

That deferral cascades. Once the read is pushed to apply, every attribute downstream of it also becomes (known after apply), which can make a small change render as a much larger-looking plan full of unknowns. The plan is not wrong; it is honestly reflecting that a chain of values cannot be computed until the upstream resource exists.

depends_on on a Data Source

Occasionally a data source must read something a managed resource produces — a just-enabled API, a freshly created project. By default the plan-time read would run before that resource exists and return stale or empty results. Adding depends_on to the data source forces its read to wait until the named resource is in place.

The cost is that depends_on defers the read to apply time, because Terraform can no longer prove the dependency is satisfied at plan time. That is the correct trade — a slightly larger plan in exchange for a read that is actually valid. Reach for it only when the ordering is genuine, not as a reflex.