terraform · diff
git:20260110.be4dc93 to git:20260209.70d0175
38 added, 91 removed. Audit A to A.
---
name: terraform
- description: Working with Terraform configuration, CLI, modules, and providers. Use when writing or reviewing HCL configuration, managing infrastructure as code, debugging Terraform plans/applies, or working with Terraform-related tools.
+ description: >-
+ Terraform Cloud workspace management, run monitoring, and log retrieval. Use when
+ listing workspaces, checking run status, fetching plan/apply logs, or looking up
+ providers and modules in the Terraform Registry.
+ allowed-tools:
+ - mcp__terraform
+ - Bash(curl:*)
+ - Bash(jq:*)
---
+
# Terraform
- ## Version-Specific Guidance
+ ## Tool Selection
- **CRITICAL**: Before providing any language syntax or CLI advice, run `terraform version` to determine the project's Terraform version.
+ - **MCP tools** (`mcp__terraform`): workspace listing, run management, provider/module registry lookups
+ - **curl**: plan and apply log retrieval — the MCP server does not expose these endpoints
- ```bash
- terraform version
- ```
+ ## Run Monitoring
- Assume Terraform 1.12+ (current: 1.14). All standard features are available:
- - Optional object attributes with defaults
- - Built-in testing with `terraform test`
- - `import` blocks for importing resources
- - `check` blocks for runtime validation
- - `removed` blocks for lifecycle management
- - Provider functions
+ Use MCP tools to find and inspect runs:
- If the project uses Terraform < 1.12, note the version and check feature availability.
+ 1. `list_workspaces` to find the workspace by name
+ 2. `list_runs` with the workspace ID to see recent runs
+ 3. `get_run_details` with the run ID for status, relationships, and timestamps
- ## Core Principles
+ The run details include `relationships.plan.data.id` and `relationships.apply.data.id` — use these to fetch logs.
- ### Formatting
+ ## Fetching Plan/Apply Logs
- Always format before committing:
+ The MCP server does not expose log retrieval. Use the TFC API directly:
+
```bash
- terraform fmt -recursive
+ # Get the apply details (includes log-read-url)
+ curl -s \
+ -H "Authorization: Bearer $TFE_TOKEN" \
+ -H "Content-Type: application/vnd.api+json" \
+ https://app.terraform.io/api/v2/applies/{apply-id} | jq -r '.data.attributes."log-read-url"'
```
- ### File Organization
+ Then fetch the raw logs from the archivist URL (no auth needed — pre-signed):
- ```
- main.tf # Primary resources
- variables.tf # Input variable declarations
- outputs.tf # Output value declarations
- versions.tf # Terraform and provider version constraints
- terraform.tfvars # Variable values (gitignored if sensitive)
+ ```bash
+ curl -s "$(archivist_url)"
```
- For larger modules, split by logical component: `compute.tf`, `networking.tf`, `security.tf`, `data.tf`, `locals.tf`.
-
- ### Style
-
- - Use 2-space indentation (enforced by `fmt`)
- - Use snake_case for all identifiers
- - Quote string values; leave boolean/number values unquoted
- - Prefer implicit dependencies (attribute references) over explicit `depends_on`
- - Use `for_each` for resource sets; `count` only for conditional creation
- - Always declare variable types explicitly
- - Mark sensitive outputs with `sensitive = true`
-
- ### Working with Terraform
-
- - Work declaratively through configuration files (`.tf` files)
- - Never execute write operations (`apply`, `destroy`, `import`, `state mv`, etc.)
- - Provide commands as output for the user to run
- - Read-only commands (`plan`, `validate`, `fmt`, `state list`, `show`) are safe to run
- - When refactoring, use `moved` blocks instead of state manipulation
-
- ### State Management
-
- - Never edit state files manually
- - Never use `terraform state` write commands
- - Use `import` blocks to import existing resources
- - Use `removed` blocks to remove resources from state
- - Use `moved` blocks to refactor resource addresses
-
- ### Security
-
- - Never commit secrets to git
- - Use variable validation for input constraints
- - Scan configurations with `tfsec`, `checkov`, or `terrascan`
-
- ## Declarative Patterns
-
- ### Import Existing Resources
-
- ```hcl
- import {
- to = aws_instance.web
- id = "i-1234567890abcdef0"
- }
- ```
+ The same pattern works for plans via `/api/v2/plans/{plan-id}`.
- ### Remove Resources from State
+ See [references/api.md](references/api.md) for full API details.
- Without destroying infrastructure:
- ```hcl
- removed {
- from = aws_instance.old
- lifecycle {
- destroy = false
- }
- }
- ```
+ ## Authentication
- ### Refactor Resource Addresses
+ `$TFE_TOKEN` is sourced from:
+ - `terraform login` (stored at `~/.terraform.d/credentials.tfrc.json`)
+ - Or set directly as an environment variable
- ```hcl
- moved {
- from = aws_instance.old
- to = aws_instance.new
- }
- ```
+ The MCP server reads `TFE_TOKEN` from the environment. For curl calls, use it as a Bearer token.
- ## Detailed References
+ ## Registry
- - **Language Patterns**: See `language.md` for HCL configuration patterns, variables, iteration, data sources, and locals
- - **State**: See `state.md` for read-only state inspection and remote state data sources
- - **Documentation**: See `docs.md` for navigating official Terraform documentation
- - **Registry**: See `registry.md` for finding and using providers/modules
+ Provider and module searches are available via MCP tools (`search_providers`, `search_modules`, `provider_details`, `module_details`). No curl needed for registry operations.