Importing Existing Infrastructure

Plenty of GCP resources already exist before Terraform shows up — a bucket clicked into the Console, a project created by gcloud, a service account someone made by hand. The import capability brings them under Terraform without destroying and recreating them, recording the live resource into state so the next plan sees it as managed rather than missing.

The modern way to do this is the declarative import block, which you write in your config and can pair with -generate-config-out to have Terraform draft the matching HCL for you. It replaces the older terraform import CLI command for everything but quick one-offs, because a block is reviewable in a pull request and runnable in CI.

The import Block

An import block declares that a resource address maps to an existing object. You name the to address — the resource in your config — and the id of the live GCP object. On the next plan, Terraform reads that live resource into state, and the apply records it. No resource is destroyed or recreated; the object is adopted in place.

import {
  to = google_storage_bucket.raw
  id = "hatch-pipeline-dev/hatch-events-raw"   # <project>/<name> for a bucket
}

resource "google_storage_bucket" "raw" {
  name     = "hatch-events-raw"
  location = "US"
}

The block and a matching resource block work together: the import tells Terraform which live object the address refers to, and the resource describes the desired config for it going forward. After the apply records the import, the import block has done its job and can be removed.

GCP Import ID Formats

The id is provider-specific and varies per resource type. A bucket wants <project>/<name>, a project wants its project id, and an IAM-related resource may want a self-link or a projects/.../roles/... form. There is no single universal shape — the import ID for each resource is documented on that resource's Registry page, and getting it wrong is the usual first failure.

The failure is also easy to misread. Hand the provider a bucket's gs:// URL or self-link where it wants <project>/<name>, and you get an opaque "resource not found" that is really an ID-shape error, not a missing resource. Check the resource's import docs on the Registry before writing the block, and the first attempt usually works.

Generating Config

You do not have to hand-transcribe every attribute of the resource you are importing. Run terraform plan -generate-config-out=generated.tf and Terraform writes a draft HCL block for each imported resource, populated from the live object. For a bucket with a dozen settings, that draft saves real typing and avoids transcription mistakes.

# with the import block in place, generate a draft resource
terraform plan -generate-config-out=generated.tf

The output is a starting point, not finished config. It emits read-only and default attributes — fields the provider computes or that already hold their defaults — which produce plan noise or outright errors if left in. Treat generated.tf as a draft to prune: keep the attributes that define the resource, delete the computed ones, and move what remains into your real config.

Import Then Reconcile

After importing, run a plan before you apply anything further. If that plan shows changes, your HCL does not yet match the live resource, and applying would silently mutate the thing you just adopted to match your half-written config — exactly the opposite of a clean adoption. The discipline is import, read the plan, converge the config, then apply.

A successful import is one where the post-import plan shows no changes. That no-change plan is the proof your config faithfully describes the imported reality. Only once you reach it have you actually adopted the resource as it stands, rather than adopted-and-then-modified it on the first apply.

Bulk and Bootstrap Imports

Adopting a whole Console-built environment means many imports — one per resource. You can write many import blocks, or fall back to the older terraform import CLI run once per resource, but the blocks win for anything beyond a one-off. They are reviewable in a pull request, so a teammate can check the address-to-id mapping before it runs, and they execute in CI like the rest of the config.

This is the difference that matters when you are bringing a real environment under management. The imperative command does the import on one machine and leaves no record; the declarative blocks are the record, version-controlled and replayable. For the Hatch pipeline's existing Console-built buckets and accounts, a set of reviewed import blocks is how the adoption stays auditable.