Skip to content

Run a factory deployment locally

This guide covers planning and applying a change to a single deployment in one of our IaC factories. For why our factories are built this way, and how Terragrunt and Terraform divide the work between them, read Understanding the Platforms Team's IaC factory pattern first.

To apply a change across every deployment in a factory, see Apply a factory change to every deployment instead.

Prerequisites

  • A local checkout of the factory repository you want to run.
  • poe installed, which every factory uses as its entrypoint.
  • Docker, if you are working in gcp-product-factory or gitlab-project-factory. Those two run Terragrunt through a docker-compose.yaml service so that everyone uses the same pinned version. The other factories run Terragrunt directly.
  • Cloud credentials for the platform the factory targets.

Authenticate before running anything. For the Google factories, Terragrunt reads your application default credentials, which the Compose service mounts read-only from your home directory.

gcloud auth application-default login

For the Azure factories, sign in with the Azure CLI.

az login

Find the deployment you want

Each deployment is a Terragrunt unit. List the units a factory contains, optionally narrowing with a glob.

poe tg list
poe tg list --filter "*test*"

How you address a unit depends on the factory's layout, so check which form applies before filtering.

Factory Deployments live in Filter syntax
gcp-product-factory product-vars/<product> --filter "example"
gitlab-project-factory product-vars/<product> --filter "example"
ais-api-factory product-vars/<environment>/<product> --filter "example"
azure-product-factory products/<product> --filter "./products/example/**"

azure-product-factory uses Terragrunt Stacks, so a deployment is a directory path rather than a bare unit name, and the glob selects every unit within that stack.

ais-api-factory nests its deployments under an environment, so the same product name exists in more than one place. Run poe tg list first to see which units exist before you filter.

Plan a change

Run a plan to see what your change would do, without altering anything.

poe run --filter "example" plan

Terragrunt resolves the state location, the input values and the module for you, so there is nothing else to pass.

A plan produces a lot of output when several units match. The -tf-forward-stdout option suppresses some of Terragrunt's own logging when you are working on a single unit.

Apply the change

Once the plan looks right, apply it.

poe run --filter "example" apply

This shows the plan again and prompts you to type yes before making any change. Our factories set TG_NO_AUTO_APPROVE so that this confirmation is always required, which is why applying one deployment is safe to do interactively.

See also