> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform Plugin

> The official Terraform engine plugin — generates main.tf HCL and wraps the terraform CLI.

The `ubx-plugin-terraform` plugin translates IR JSON to Terraform HCL (`main.tf`) and wraps the `terraform` CLI for plan, apply, and destroy operations.

## Install

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx plugin install terraform
```

## Configure

In `workspace.xcl`:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
workspace {
  engine = "terraform"
}
```

## What the plugin generates

```
.ubx/
└── main.tf     # Complete Terraform HCL configuration
```

The generated `main.tf` contains:

1. File header comment (`# Generated by ubx-plugin-terraform — do not edit`)
2. `terraform {}` block (backend + required\_providers)
3. `provider {}` blocks (from XCL provider declarations)
4. `variable {}` blocks (from XCL input declarations)
5. `locals {}` block (from XCL locals declarations)
6. `resource {}` blocks (from XCL resource declarations)
7. `output {}` blocks (from XCL output declarations)

## Type path mapping

XCL type paths are converted to Terraform resource type names using CamelCase → snake\_case:

| XCL type path        | Terraform resource type                      |
| -------------------- | -------------------------------------------- |
| `aws.ec2.Vpc`        | `aws_vpc`                                    |
| `aws.ec2.NatGateway` | `aws_ec2_nat_gateway`                        |
| `aws.s3.Bucket`      | `aws_s3_bucket`                              |
| `aws_vpc`            | `aws_vpc` *(single-segment: passed through)* |

Multi-segment paths are lowercased with segments joined by `_` after CamelCase-to-snake\_case conversion.

## Input → variable mapping

XCL `input` fields become Terraform `variable` blocks:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
// XCL
input "networking" {
  vpc_cidr: string = "10.0.0.0/16"
}
```

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
# Generated HCL
variable "vpc_cidr" {
  type    = string
  default = "10.0.0.0/16"
}
```

## Output → output mapping

XCL `output` blocks become Terraform `output` blocks:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
// XCL
output vpc_id {
  value = vpc.id
}
```

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
# Generated HCL
output "vpc_id" {
  value = aws_vpc.networking-vpc.id
}
```

## Plugin RPCs

| RPC       | Description                                 |
| --------- | ------------------------------------------- |
| `Compile` | Generates `main.tf`, returns `artifact_uri` |
| `Plan`    | Runs `terraform plan`, returns summary      |
| `Apply`   | Runs `terraform apply`, streams events      |
| `Destroy` | Runs `terraform destroy`, streams events    |

## Prerequisites

The `terraform` binary must be on `$PATH`. Install from [developer.hashicorp.com/terraform](https://developer.hashicorp.com/terraform/install).

## Backend

Terraform backend configuration is generated from the XCL `backend {}` block:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
terraform {
  backend "s3" {
    bucket = "my-state-bucket"
    key    = "ubx/networking/state"
    region = "us-east-1"
  }
}
```

For local backend, no backend block is emitted (Terraform defaults to local).