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.
Filter Syntax Overview
Section titled “Filter Syntax Overview”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:
$ terragrunt find --filter './prod/** | name=web'prod/services/web
Where the result of find
above might have been:
$ terragrunt findprod/services/webprod/services/apiprod/data/dbdev/services/webdev/services/apidev/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
Filter Types
Section titled “Filter Types”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.
Name-Based Filtering
Section titled “Name-Based Filtering”Match units and stacks by their name. This is the simplest form of filtering.
# Exact matchterragrunt find --filter app1
# Glob patternterragrunt 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
Path-Based Filtering
Section titled “Path-Based Filtering”Match units and stacks by their file system path.
# Relative pathsterragrunt find --filter './envs/prod/apps/app1'terragrunt find --filter './envs/stage/**'
# Absolute pathsterragrunt 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
Attribute-Based Filtering
Section titled “Attribute-Based Filtering”Match units and stacks by their configuration attributes.
# Filter by component typeterragrunt find --filter 'type=unit'terragrunt find --filter 'type=stack'
# Filter by external dependency statusterragrunt 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
Negation
Section titled “Negation”Exclude units and stacks using the !
prefix.
# Exclude by nameterragrunt find --filter '!app1'
# Exclude by pathterragrunt find --filter '!./prod/**'
# Exclude by typeterragrunt 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
Intersection (Refinement)
Section titled “Intersection (Refinement)”Use the |
operator to refine results. The right side of the operator is applied to the results from the left side.
# Find all components in ./prod/** that are also unitsterragrunt find --filter './prod/** | type=unit'
# Find all components in ./prod/** that are not unitsterragrunt find --filter './prod/** | !type=unit'
# You can chain as many filters as you want to further refine the resultsterragrunt 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
Union (Multiple Filters)
Section titled “Union (Multiple Filters)”Specify multiple --filter
flags to combine results using OR logic.
# 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
Usage with Commands
Section titled “Usage with Commands”The following commands all support the --filter
flag, and use it to filter results in the same way:
- find
- list
- run (planned for a future release)
- hcl fmt (planned for a future release)
- hcl validate (planned for a future release)
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
).
Comparison with Queue Control Flags
Section titled “Comparison with Queue Control Flags”The --filter
flag provides a unified alternative to multiple queue control flags:
Legacy Flag | Filter Equivalent |
---|---|
--queue-include-dir | --filter './path/*' |
--queue-exclude-dir | --filter '!./path/*' |
--queue-exclude-external | --filter '!external=true' |
--queue-include-external | --filter 'external=true' |