action block reference

The action block specifies a provider-defined action that you can invoke using the Terraform CLI or during an apply operation. Actions are preset operations built into providers that you can invoke to trigger automations outside of Terraform, such as Ansible playbooks and Lambda jobs. Refer to Invoke an action for more information.

Configuration model

The action block supports the following configuration:

action "<TYPE>" "<LABEL>" block
- config map of arguments or nested blocks
  - PROVIDER ARGUMENTS
- for_each map or set of strings | mutually exclusive with count
- count number | mutually exclusive with for_each
- provider reference

Complete configuration

The following action block includes all supported built-in arguments:

action "<TYPE>" "<LABEL>" {
   config {
      <PROVIDER ARGUMENTS>
   }
   for_each = {          # `for_each` and `count` are mutually exclusive
      <KEY> = <VALUE>
   }
   for_each = [       # `for_each` accepts a map or a set of strings
      "<VALUE>",
      "<VALUE>"
  ]
   count = <NUMBER>      # `for_each` and `count` are mutually exclusive
   provider = <REFERENCE.TO.ALIAS> 
}

Specification

An action block supports the following configuration.

`action "<TYPE>" "<LABEL>"`

You must set the following arguments for every action block:

TYPE: Specifies the type of action to invoke. Refer to the provider documentation for information about the types of actions you can declare.
LABEL: Specifies a label for the action block. Terraform uses this label as part of the unique name for the action as configured by the block. The label does not affect the operation performed by Terraform when a user invokes the action. Refer to References to Named Values and Resource naming for expression syntax and label recommendations.

Use the action.<TYPE>.<LABEL> syntax to reference the action elsewhere in your configuration.

`config`

The config block sets values for arguments or nested blocks defined by the provider.

action "<TYPE>" "<LABEL>" {
  config { 
    <provider-specific arguments>
  }
  # . . . 
}

The config block may contain arguments, nested blocks, or a combination of both. Refer to the provider documentation for arguments you can configure in the config block for the type of action you want to invoke.

Summary

Data type: Map of arguments or nested blocks
Example: Define an action

`for_each`

The for_each meta-argument instructs Terraform to invoke the action once for each member of a list or key-value pair in a map.

action "<TYPE>" "<LABEL>" {
  for_each = [ "<VALUE>" ]
  # . . .
}

The for_each meta-argument accepts a map or a set of strings and invokes the action once for each item in that map or set. Each invocation is associated with a distinct infrastructure object.

You can use pure functions, such as toset() and tomap(), to create a map or set for use in the for_each argument. All values must be known when Terraform plans your action, whether iterating over the keys of a map or set of strings. Otherwise, Terraform prints an error message that for_each has dependencies that it cannot determine before applying the configuration.

Keys in the for_each argument cannot be the result of or rely on the result of impure functions, such as uuid, bcrypt, or timestamp, because Terraform defers evaluating impure functions during the main evaluation step.

The for_each argument does not implicitly convert lists or tuples to sets. To declare resource instances based on a nested data structure or combinations of elements from multiple data structures, you can use Terraform expressions and functions to derive a suitable value. Refer to the following examples for more information:

You cannot use sensitive values, such as sensitive input variables, sensitive outputs, or sensitive resource attributes, as arguments in for_each. Because Terraform uses the value in for_each to identify the action instance and always discloses it in UI output, sensitive values are not allowed. Terraform returns an error if you attempt to use sensitive values as for_each arguments.

If you transform a value containing sensitive data into an argument for use in for_each, be aware that most functions in Terraform will return a sensitive result if given an argument with sensitive content. In many cases, you can achieve similar results with a for expression. For example, to call keys(local.map) where local.map is an object with sensitive values, but non-sensitive keys, you can create a value to pass to for_each using toset([for k,v in local.map : k]).

Refer to Manage sensitive data for more information.

The for_each argument exposes an each object that you can reference within the same block to modify specific instances of the action. The object has the following attributes:

each.key: Map key or list member that corresponds to an instance.
each.value: Map value that corresponds to an instance.

Use the <TYPE>.<NAME>[<KEY>] syntax to access an instance of a resource created using for_each. For example, aws_lambda_invoke.server["a_group"] refers to an invocation of the aws_lambda_invoke action named server from a key named a_group.

The for_each argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

Data type: Map or set of strings.
Default: None.
Example: Invoke an action multiple times.

`count`

The count meta-argument instructs Terraform to invoke an action multiple times using the same configuration.

resource {
  count = <number>
}

The value must be a whole number. You can reference variables or local values and use expressions to compute the value, but the value must resolve to a whole number.

In blocks where count is set, Terraform exposes an additional count object. You can reference the object to modify the configuration of each invocation. The count object has an index attribute starting from 0.

To refer to an individual instance of an invocation using the count meta-argument, use the <TYPE>.<NAME>[INDEX] syntax. For example, aws_lambda_invoke.server[0] refers to the first invocation of the aws_lambda_invoke action named server.

Tip

You can use the count argument as a conditional. For example, setting a count = var.creator ? 3 : 0 instructs Terraform to invoke an action three times when a variable named creator is set to true. When creator is set to false, Terraform does not invoke the action. Refer to Conditional Expressions for more information.

The count argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

Data type: Number.
Default: None.
Example: Invoke an action multiple times.

`provider`

The provider argument instructs Terraform to use an alternate provider configuration to invoke the action.

action "<TYPE>" "<LABEL>" {
  provider = <provider>.<alias>
}

By default, Terraform automatically selects a provider based on the action type, but you can create multiple provider configurations and use a non-default configuration for specific actions.

Use the <PROVIDER>.<ALIAS> syntax to reference a provider configuration in the provider argument.

The provider argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

Data type: Reference.
Default: None.
Example: Select an alternate provider configuration.

Examples

The following examples show how to write configuration for common use cases.

Define an action

The following example adds an aws_lambda_invoke action. You can invoke an action using the CLI or configure Terraform to invoke the action during a resource lifecycle state. Refer to Invoke an action for instructions on how to invoke actions.

action "aws_lambda_invoke" "example" {
  config {
    function_name = "123456789012:function:my-function:1"
    payload = jsonencode({
      key1 = "value1"
      key2 = "value2"
    })
  }
}

The function_name argument must reference an existing AWS Lambda function by name or ARN. Refer to the aws_lambda_invoke documentation for details.

Select an alternate provider configuration

The following example configures Terraform to apply the aws.alias provider configuration when invoking the action:

action "aws_lambda_invoke" "example" {
  provider = aws.alias
  config {
    function_name = "my_function"
    payload = jsonencode({
      key1 = "value1"
      key2 = "value2"
    })
  }
}

Invoke an action multiple times

You can add a count or for_each meta-argument to invoke an action multiple times.

Terraform invokes the action three times.

action "aws_lambda_invoke" "example" {
  count = 3 
  config {
    function_name = "my_function"
    payload = jsonencode({
      key1 = "value1"
      key2 = "value2"
    })
  }
}

Terraform invokes the action once for each member of the map, resulting in two invocations.

action "aws_lambda_invoke" "example" {
  for_each = tomap({
    a_group       = "eastus"
    another_group = "westus2"
  })
  config {
    function_name = "my_function"
    payload = jsonencode({
      key1 = "value1"
      key2 = "value2"
    })
  }
}