Invoke an action

Actions are preset operations built into providers that let Terraform perform day-two operations. Invoke actions to trigger automations outside of Terraform, such as Ansible playbooks and Lambda jobs. Actions do not affect resource state.

Overview

Declare an action block in your Terraform configuration and apply your configuration or use the Terraform CLI to invoke the action. You can configure actions that aren't directly associated with a resource. These actions don't change the state of resources managed by Terraform.

Requirements

The AWS provider is the only provider that includes actions. As a result, you can only invoke AWS actions. Refer to the AWS provider documentation for more information about available actions.

To monitor actions in HCP Terraform, you must configure a connection to HCP Terraform in your Terraform configuration. Refer to Connect to HCP Terraform for instructions.

Configure an action

Add an action block to your Terraform configuration and specify the type and a label as inline arguments. The type of action depends on your provider. Refer to your provider documentation for details about available actions.

The following example declares an aws_lambda_invoke action labeled example:

action "aws_lambda_invoke" "example" {
  # ...
}

Configure provider arguments

Use the config block to configure provider arguments. The config block may contain arguments or other blocks. Refer to your provider documentation for more information.

The following example adds an aws_lambda_invoke action that references "my_function" defined elsewhere in the configuration and passes a JSON payload into the function.

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

Refer to the AWS provider documentation for information about provisioning AWS Lambda functions.

Configure Terraform meta-arguments

You can use some Terraform meta-argments in action blocks. Meta-arguments are built into Terraform and control how Terraform creates resources. Refer to Meta-arguments for more information.

In the following example, Terraform creates three instances of the action because the count meta-argument is set to 3. It also uses the provider configuration reference with aws.alias per the provider meta-argument. Refer to the action block reference for information about all meta-arguments supported in the action block.

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

Invoke the action

You can use the Terraform CLI to run an action or configure a resource block to trigger the action during an apply operation.

Invoke an action from the CLI

When you invoke an action using the CLI, Terraform runs only the action and excludes all other configurations.

Add the -invoke flag and specify the address of an action when running the terraform plan or terraform apply command.

The following example creates a plan for invoking the aws_lambda_invocation.example action:

$ terraform plan -invoke=action.aws_lambda_invoke.example

Refer to the terraform plan command documentation for more information about creating plans.

The following example runs the aws_lambda_invocation.example action:

$ terraform apply -invoke=action.aws_lambda_invoke.example

Refer to the terraform apply command documentation for more information about applying configurations.

Trigger an action when applying a configuration

To trigger an action on resource lifecycle events, such as creating or destroying a resource, configure an action_trigger block and specify the action to run and the events that trigger the action. The action_trigger block is a member of the lifecycle block nested in a resource block. Refer to the action_trigger documentation for details about configuring the block.

In the following example, Terraform invokes the action.aws_lambda_invoke.example action after creating the aws_lambda_function.example resource. Terraform also invokes the action during a terraform apply operation if the resource block configuration changes.

resource "aws_lambda_function" "example" {
  # resource config 

  lifecycle {
    action_trigger {
      events = ["after_create", "after_update"]
      actions = [action.aws_lambda_invoke.example]
    }
  }
}

Terraform invokes the action when you run terraform apply and are creating the resource for the first time. This is because one of the event triggers is after_create.

Because the event argument includes after_update, Terraform also updates the resource on terraform apply, even without changes to the configuration, when it detects drift in the resource.

View actions in HCP Terraform

If your workspace is connected to your HCP Terraform organization, you can monitor action runs in HCP Terraform. Refer to Action runs in the HCP Terraform documentation for more information.