Manage Terraform actions

This topic describes how to find, view, invoke, and track Terraform actions, including their invocation history, in HCP Terraform. Use the Actions page to help you find potential issues related to adhoc operations performed by an invoked action.

Note

An IBM HCP Terraform Standard plan or higher is required to use this feature. Refer to the pricing page for details.

Introduction

Actions are preset operations built into providers that you can invoke with Terraform. Actions can trigger automations outside of Terraform, such as running Ansible playbooks and Lambda jobs. Actions do not affect resource state. Refer to Invoke an action in the configuration language documentation for more information. HCP Terraform includes a dedicated Actions page for viewing and invoking actions declared in your workspace configuration. The Actions page helps users gain insight about any ad hoc operations that have been performed.

Requirements

Terraform version 1.14 or newer. Refer to Terraform version settings for more information.
You must be on an IBM HCP Terraform standard plan to access the Actions page. Refer to the pricing page for more information.

Browse actions

Navigate to your workspace and click Actions in the sidebar. Use the search bar and filters to find specific actions. You can also view actions in the Runs tab. Refer to Action runs for more information.

Use the search and filtering mechanisms to determine which actions were most recently invoked and how.

Search and filter invocations

The search bar returns actions with matching values in the Name column. You can also open the Filters menu and choose filters for narrowing down your search. You can apply the following types of filters:

Providers. Choose one or more providers to filter actions according to their parent provider.
Last invocation method. Choose one or more invocation methods. A direct invocation is when a team member uses the -invoke flag in a terraform apply or invokes the action from the UI. A lifecycle invocation is when the action_trigger lifecycle argument triggers the action during a terraform apply operation.
Last invoked. Choose a time range to filter by.

Click on an action to view its invocation history. You can also open the ellipses menu to invoke an action.

View invocation history

Navigate to your workspace and click Actions in the sidebar. Click on an action in the Name column to view its details and invocation history by run ID.

The Summary tile presents the following information from the registry:

A description of the action
The provider used to define the action
A link to the action documentation

The Summary tile also shows how many times the action has been invoked in the workspace.

Search and filter action invocations

You can sort the invocation history by last invocation. Use the search bar to find a specific run ID or choose filters from the Filters menu to narrow down search results. You can apply the following types of filters:

Action status. Choose one or more statuses. Because an action may execute successfully even if the run fails, the action status may not match the state of the associated run. HCP Terraform tracks the action status for each invocation, which may execute multiple times per run or across runs. As a result, HCP Terraform reports the status as Run in progress when one instance is still in progress or Not successful when one instance ran unsuccessfully.
Invocation method. A direct invocation is when a team member uses the -invoke flag in a terraform apply or invokes the action from the UI. A lifecycle invocation is when the action_trigger lifecycle argument triggers the action during a terraform apply operation.
Source. Choose one or more interfaces used to invoke the action.
Invoked by. Only team members who have invoked the action appear in this filter.
Invoked. Choose a time range.

Either click on a run ID or choose Go to associated run from the ellipses menu to view the run on the Run page.

Choose View action status details from the ellipses menu to open a tray that shows action status details. For actions invoked directly, the tray shows status for each instance of the action invoked during the run. For actions invoked as part of a resource lifecycle, the tray includes information about each resource where the action was invoked and the lifecycle rule that triggered the invocation.

Invoke an action

You can either invoke an action directly from the Actions page or from the invocation history page for an action. Invoking an action starts a new run. Refer to Manage and view runs for more information.

Complete the following steps to invoke an action from the Actions page:

Navigate to your workspace and click the Actions tab.
Choose Invoke action from the ellipses menu.
When prompted, choose a run type for invoking the action. Refer to Run modes and options for more information about run types.
If the action block provisions multiple instances, you can enable the Invoke a specific instance key option and choose a specific action instance to invoke.
Depending on your configuration, you can either choose an instance name from the Select an instance drop-down or specify the address of the action instance in the Manual input field. You can't invoke an action called from a module block when the module is configured with multiple instances. Refer to Multiple action instances for more information.
Click Invoke. If you chose the Preview with plan-only run option, then HCP Terraform models the outcome in a Terraform plan but does not perform the operation.

Complete the following steps to invoke an action from the invocation history page:

Navigate to your workspace and click the Actions tab.
Click on an action in the Name column.
Click Invoke.
When prompted, choose the run type for invoking the action. Refer to Run modes and options for more information about run types.
Click Invoke. If you chose the Preview with plan-only run option, then HCP Terraform models the outcome in a Terraform plan but does not perform the operation.

Multiple action instances

You can invoke a specific instance of an action from the Actions page. To provision multiple instances, you can configure the action block with a count or for_each meta-argument. Refer to the action block reference for more information.

When the action configuration uses literal values or expressions that reference input values directly, such as count = 3 or for_each = var.my-action-instances, the platform can evaulate the expression and render instance names so that you can choose the instance to invoke directly in the UI. The platform may not be able to evaluate expressions and render instance names for the following expressions:

Complex expressions
Literal expressions wrapped in a function
Expressions defined in a locals block

In these cases, you must specify the address of the specific instance you want to invoke. Refer to your configuration to retrieve the instance address.

You can't invoke a specific instance from the Actions page, however, when all of the following conditions are true:

the action is defined in a child module
the child module is called from a module block in the root module
the module block in the root module contains a count or for_each argument

The actions won't appear in the run history. Instead, you must invoke them directly from the CLI or API.

You can't invoke actions that are nested more than 20 module calls deep from the Actions page. Instead, you must invoke them directly from the CLI or API.

The UI does not show drop-down instance options when a resolved for_each action has more than 100 keys. You can manually enter the full action instance address, invoke the action through CLI or API, or choose Re-invoke action from a previous direct invocation when available.