Selectors

Overview

Selectors provide a powerful mechanism to target and customize specific environment variables within Environment Templates and Resource Templates. They address scenarios where multiple variables with the same name exist, enabling precise overrides and better variable management.

Key benefits of selectors include:

• Variable Differentiation: Distinguish between variables with the same name and assign different override values
• Descriptive Aliases: Allow to define a display name or alias for variables, enhancing clarity and usability
• Dynamic Behavior: Use selectors for both overriding existing variables and creating new ones based on the configuration

When defined, selectors act as an alias in the Environment Template, Resource Template, and environment publishing pages, while the actual variable name used in activities is specified within the selector. Selectors also support wildcard matching for more dynamic targeting.

How Selectors Work

• Upsert Behavior: If a selector matches an existing variable, its value is overridden. If no match is found, a new variable is created with the same name
• Logical Matching: Selectors use an “OR” condition, meaning that if at least one selector matches a variable, it is overridden
• Scopes: Selectors can only be used for variables defined in Resource Templates and Environment Templates. Wildcards (*) can be used for dynamic matching across levels

Examples of Selector Usage

Below are some of the significant examples that can help users effectively target and manage variables within Resource Templates and Environment Templates.

Selectors Valid at Resource Template Level

• Target a variable in a specific resource hook:

hook.<oninit/onsuccess/onfailure/oncompletion>.<hook_name>.<variable_name>

• Target a variable in all resource hooks with a matching name:

hook.*.<hook_name>.<variable_name>

• Target all variables in hooks for a specific lifecycle, such as "oninit":

hook.oninit.*.<variable_name>

• Target a variable in provider hooks for Terraform, OpenTofu, HCP, or System:

provider.hook.<deploy/destroy>.<init/plan/apply/output/destroy>.<before/after>.<hook_name>.<var_name>

• Target a variable in the artifact fetch operation:

artifact.<variable_name>

• Target a variable in the provider lifecycle, such as the Terraform output activity:

provider.lifecycle.<init/plan/apply/output/destroy>.<var_name>

• Target a variable in a custom task for custom provider Resource Templates:

provider.task.<task-name>.<var-name>

Selectors Valid at Environment Template Level

• Target a variable in a specific resource (applies to all activities of the associated Resource Template):

resource.<resource_name>.<variable_or_alias_name>

• Target a variable across all Resource Templates:

resource.*.<variable_or_alias_name>

• Target a variable in an Environment Template hook:

environment.hook.<oninit/onsuccess/onfailure/oncompletion>.<hook_name>.<variable_name>

• All selectors valid at the Resource Template level are also valid at the Environment Template level when prefixed with resource:

resource.<resource_name>.[any-selector-that's-valid-at-RT-level]

Back to top