> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Terraform integration

> Overview of Terraform integration with Itential Gateway, including module discovery, decoration, and command execution.

**Terraform** is an Infrastructure as Code tool for building, changing, and managing infrastructure in a safe, repeatable way. It is based on the configuration language called the **HashiCorp Configuration Language (HCL)**. Operators and infrastructure teams can use HCL to automate the deployment and management of network resources running on providers such as AWS and Azure.

For more information on Terraform, see the [HashiCorp Learn](https://learn.hashicorp.com/terraform/getting-started/intro) page.

Itential Gateway contains a **Terraform Module Execution Engine** that supports the discovery, decoration, and execution of Terraform modules.

For a complete list of supported Terraform versions, see [Gateway dependencies](./system-requirements#gateway-dependencies).

The AG server performs discovery of Terraform modules at startup time and maintains a cache of all managed modules in memory. Users determine the modules being managed by providing a list of directory paths in their AG `properties.yml` configuration file. A recursive search of the directory paths is performed.

Once a module has been discovered, it is available to be decorated. The decoration of Terraform modules within Gateway is similar to that of Ansible playbooks. However, instead of decorating the variables within a playbook, users decorate the variables found in the script components within a Terraform module. The decorated variables are then passed as arguments to the APIs that execute the module. A permanent copy of each module's decoration is stored in a local database that is maintained by Gateway.

A complete set of REST APIs are available for clients to manage Terraform module decoration and execution. See the **API Documentation** section within the Gateway UI for more information.

## Decoration

Decorating a Terraform module involves creating metadata in JSON format that describes the variables used to execute the module. The metadata is more specifically known as a JSON schema. The example below shows the JSON schema for the variables component of a Terraform module named `hello_world`.

**Sample variables component**

```hcl
variable "access_key" {
    default="my-access-key"
}

variable "secret_key" {
    default="my-secret-key"
}
```

**Sample decoration**

```json
{
  "title": "hello_world",
  "type": "object",
  "properties": {
    "access_key": {
      "type": "string",
      "description": "AWS access key"
    },
    "secret_key": {
      "type": "string",
      "description": "AWS secret key"
    }
  },
  "required": []
}
```

## Terraform commands

Below is an overview of the Terraform commands that are front-ended by the AG Terraform APIs.

The state file, `.tfstate` is used to manage the state of the infrastructure at any point. The state file is present inside the directory containing the Terraform module on the AG server.

Terraform commands applicable **only to Gateway/2022.1** include: `init`, `plan`, `apply`, `destroy`.

### Init

The `terraform init` command is used to initialize a working directory containing Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration or cloning an existing one from version control. It is safe to run this command multiple times.

### Plan

The `terraform plan` command is used to create an execution plan. Terraform performs a refresh, unless explicitly disabled, and then determines what actions are necessary to achieve the desired state specified in the configuration files.

This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to real resources or to the state. For example, `terraform plan` might be run before committing a change to version control, to create confidence that it will behave as expected.

### Apply

The `terraform apply` command is used to apply the changes required to reach the desired state of the configuration, or the pre-determined set of actions generated by a `terraform plan` execution plan.

### Destroy

The `terraform destroy` command is used to destroy the Terraform-managed infrastructure.

### Validate

The `terraform validate` command is used to validate the configuration of a Terraform module.