Skip to content

Filters

The --filter flag provides a sophisticated querying syntax for targeting specific units and stacks in Terragrunt commands. This unified approach offers powerful filtering capabilities using a flexible query language.

The filter syntax allows you to target units and stacks using several different approaches. Usage of the filter flag in a command can look like this:

Terminal window
$ terragrunt find --filter './prod/** | name=web'
prod/services/web

Where the result of find above might have been:

Terminal window
$ terragrunt find
prod/services/web
prod/services/api
prod/data/db
dev/services/web
dev/services/api
dev/data/db

For the following file tree:

  • Directoryprod
    • Directoryservices
      • Directoryweb <— Matched by the filter
        • terragrunt.hcl
      • Directoryapi
        • terragrunt.hcl
    • Directorydata
      • Directorydb
        • terragrunt.hcl
  • Directorydev
    • Directoryservices
      • Directoryweb
        • terragrunt.hcl
      • Directoryapi
        • terragrunt.hcl
    • Directorydata
      • Directorydb
        • terragrunt.hcl

There are several different types of filters, and particular ways in which they can be combined to achieve different results. You can learn more about that below.

Match units and stacks by their name. This is the simplest form of filtering.

Terminal window
# Exact match
terragrunt find --filter app1
# Glob pattern
terragrunt find --filter 'app*'
  • Directoryapps
    • Directoryapp1 <— Matched by the first and second filter
      • terragrunt.hcl
    • Directoryapp2 <— Matched only by the second filter
      • terragrunt.hcl
    • Directoryother
      • terragrunt.hcl

Match units and stacks by their file system path.

Terminal window
# Relative paths
terragrunt find --filter './envs/prod/apps/app1'
terragrunt find --filter './envs/stage/**'
# Absolute paths
terragrunt find --filter '/absolute/path/to/envs/dev/apps/*'
# Wrapped paths (useful for explicitly indicating that an expression is for a path if ambiguous)
terragrunt find --filter '{./envs/prod/apps/app2}'
  • Directoryenvs
    • Directoryprod
      • Directoryapps
        • Directoryapp1 <— Matched by the first filter
          • terragrunt.hcl
        • Directoryapp2 <— Matched by the fourth filter
          • terragrunt.hcl
    • Directorystage
      • Directoryapps
        • Directoryapp1 <— Matched by the second filter
          • terragrunt.hcl
        • Directoryapp2 <— Also matched by the second filter
          • terragrunt.hcl
    • Directorydev
      • Directoryapps
        • Directoryapp1 <— Matched by the third filter
          • terragrunt.hcl
        • Directoryapp2 <— Also matched by the third filter
          • terragrunt.hcl

Match units and stacks by their configuration attributes.

Terminal window
# Filter by component type
terragrunt find --filter 'type=unit'
terragrunt find --filter 'type=stack'
# Filter by external dependency status
terragrunt find --dependencies --external --filter 'external=false'
terragrunt find --dependencies --external --filter 'external=true'
# Explicitly filter by name (useful for explicitly indicating that an expression is for a name if ambiguous)
terragrunt find --filter 'name=stack*'
  • Directory.
    • Directoryunit1 <— Selected by the first filter
      • terragrunt.hcl
    • Directorystack1 <— Selected by the second and fifth filter
      • terragrunt.stack.hcl
  • Directory..
    • Directorydependencies <— Note that this directory is sibling to the current working directory
      • Directorydependency-of-app1 <— Matched by the fourth filter, but not the third filter
        • terragrunt.hcl

Exclude units and stacks using the ! prefix.

Terminal window
# Exclude by name
terragrunt find --filter '!app1'
# Exclude by path
terragrunt find --filter '!./prod/**'
# Exclude by type
terragrunt find --filter '!type=stack'
  • Directoryenvs
    • Directoryprod
      • Directoryapps
        • Directoryapp1 <— Excluded by both the first and second filter
          • terragrunt.hcl
        • Directoryapp2 <— Matched by all filters except the second filter
          • terragrunt.hcl
      • Directorystacks
        • Directorystack1 <— Excluded by both the second and third filter
          • terragrunt.stack.hcl
    • Directorystage
      • Directoryapps
        • Directoryapp1 <— Matched by all filters except the first filter
          • terragrunt.hcl
        • Directoryapp2 <— Matched by all filters
          • terragrunt.hcl
      • Directorystacks
        • Directorystack1 <— Matched by all filters except the third filter
          • terragrunt.stack.hcl

Use the | operator to refine results. The right side of the operator is applied to the results from the left side.

Terminal window
# Find all components in ./prod/** that are also units
terragrunt find --filter './prod/** | type=unit'
# Find all components in ./prod/** that are not units
terragrunt find --filter './prod/** | !type=unit'
# You can chain as many filters as you want to further refine the results
terragrunt find --filter './dev/** | type=unit | !name=unit1'
  • Directoryprod
    • Directoryunits
      • Directoryunit1 <— Matched by first filter
        • terragrunt.hcl
      • Directoryunit2 <— Matched by first filter
        • terragrunt.hcl
    • Directorystacks
      • Directorystack1 <— Matched by second filter
        • terragrunt.stack.hcl
      • Directorystack2 <— Matched by second filter
        • terragrunt.stack.hcl
  • Directorydev
    • Directoryunits
      • Directoryunit1
        • terragrunt.hcl
      • Directoryunit2 <— Matched by third filter
        • terragrunt.hcl
    • Directorystacks
      • Directorystack1
        • terragrunt.stack.hcl
      • Directorystack2
        • terragrunt.stack.hcl

Specify multiple --filter flags to combine results using OR logic.

Terminal window
# Find components named 'unit1' OR 'stack1'
terragrunt find --filter unit1 --filter stack1
# Find components in ./envs/prod/* OR ./envs/stage/*
terragrunt find --filter './envs/prod/*' --filter './envs/stage/*'
# Find components named 'stack2' _except_ those in ./envs/prod/* and ./envs/stage/*
terragrunt find --filter stack2 --filter '!./envs/prod/**' --filter '!./envs/stage/**'
  • Directoryenvs
    • Directoryprod
      • Directoryunit1 <— Matched by the first filter and the second filter
        • terragrunt.hcl
      • Directoryunit2 <— Matched by the second filter
        • terragrunt.hcl
      • Directorystack1 <— Matched by the first filter and the second filter
        • terragrunt.stack.hcl
      • Directorystack2 <— Matched by the second filter
        • terragrunt.stack.hcl
    • Directorystage
      • Directoryunit1 <— Matched by the first filter and the second filter
        • terragrunt.hcl
      • Directoryunit2 <— Matched by the second filter
        • terragrunt.hcl
      • Directorystack1 <— Matched by the first filter and the second filter
        • terragrunt.stack.hcl
      • Directorystack2 <— Matched by the second filter
        • terragrunt.stack.hcl
    • Directorydev
      • Directoryunit1 <— Matched by the first filter
        • terragrunt.hcl
      • Directoryunit2
        • terragrunt.hcl
      • Directorystack1 <— Matched by the first filter
        • terragrunt.stack.hcl
      • Directorystack2 <— Matched by the third filter
        • terragrunt.stack.hcl

The following commands all support the --filter flag, and use it to filter results in the same way:

This flag is intended to be a flexible way to target specific infrastructure that allows you to dry-run infrastructure targeting using discovery commands (like find and list) before running a command that actually affects infrastructure (like run).

The --filter flag provides a unified alternative to multiple queue control flags:

Legacy FlagFilter Equivalent
--queue-include-dir--filter './path/*'
--queue-exclude-dir--filter '!./path/*'
--queue-exclude-external--filter '!external=true'
--queue-include-external--filter 'external=true'