Calling and Sourcing Modules

You call a module with a module block, and its source argument tells Terraform where to fetch the code — a local path during development, the Terraform Registry for published modules like Google's Cloud Foundation Toolkit, a git repository for your private modules, or even a GCS bucket. The block name is the local instance name, source is the only required argument, and everything else is an input variable to the child.

terraform init is what actually downloads non-local sources into .terraform/modules/. That single fact drives most of the operational rules in this topic: where the source points decides whether your module usage is reproducible or a moving target, and a change to the source or its version means re-running init before the new code takes effect.

The module Block

A module block has a local name, a source, and the inputs you pass to the child. You reference its outputs as module.<name>.<output> — module.ingest_pipeline.topic_id — and that is the only way to read anything out of it. The local name is yours to choose and is what shows up in state addresses; the source is what Terraform resolves at init.

module "ingest_pipeline" {
  source     = "./modules/ingest-pipeline"   # local path — no download, no version
  project_id = "hatch-pipeline-prod"
  event_name = "clickstream"
}

# reference an output elsewhere in the config
resource "google_bigquery_data_transfer_config" "loader" {
  params = {
    topic = module.ingest_pipeline.topic_id
  }
}

Source Types

There are four sources you will actually use. A local path (./modules/ingest-pipeline) references a directory in the same repo — the default while you develop a module, and the one source that needs no init re-download because there is nothing to fetch. A Registry source (terraform-google-modules/network/google) pulls a published module from registry.terraform.io; this is how you consume the Cloud Foundation Toolkit, and it is the only source type where the version argument applies.

A git source pins a private module by tag — git::https://github.com/hatch-io/modules.git//ingest-pipeline?ref=v1.2.0 — and a GCS source fetches an archive from a bucket, gcs::https://www.googleapis.com/storage/v1/hatch-modules/ingest.zip. Both are how a team shares private modules without publishing them to a registry. The double-slash in the git source (//ingest-pipeline) selects a subdirectory inside the repo, which is how a monorepo of modules resolves to the right one.

module "local"    { source = "./modules/ingest-pipeline" }                                  # dev
module "registry" { source = "terraform-google-modules/network/google", version = "~> 9.0" }  # CFT
module "git"      { source = "git::https://github.com/hatch-io/modules.git//ingest-pipeline?ref=v1.2.0" }
module "gcs"      { source = "gcs::https://www.googleapis.com/storage/v1/hatch-modules/ingest.zip" }

init and the Module Cache

terraform init resolves and downloads every non-local source into .terraform/modules/, then caches it. Change a source or a registry version and you must re-run init, or Terraform happily runs the stale cached copy and your change appears to do nothing. This is the single most common confusion in the topic: a plan that ignores your edit is almost always a cache that init never refreshed.

A corollary catches people who try to debug a remote module in place: editing a file under .terraform/modules/ to "test a fix" is futile, because that directory is a cache init overwrites. The edit vanishes on the next init and was never part of your source. To change a module, change it at the source — the local directory, the git tag, or the published version — never in the cache.

Local vs Remote Sourcing

The practical workflow is to develop against a local path and consume against a versioned source. While you are iterating on the ingest-pipeline module, a local path means every edit applies immediately with no init dance. Once it stabilizes and other teams depend on it, you publish it — to git with a tag, or to a registry — and callers pin a version. Local is for the author mid-change; versioned remote is for the consumer who wants reproducibility.

Passing Providers

Most modules need no provider plumbing — a child inherits the caller's default google provider automatically. You only pass a provider explicitly when a child needs a non-default one, with a providers = { ... } argument in the module block — a second region, a different project, or google-beta. The full mechanics of that, and why a reusable child must never declare its own provider block, are the subject of Topic 46; here it is enough to know the explicit-passing escape hatch exists and is rarely needed.