From 0c17df108334b809a0d3194929f91e508f935744 Mon Sep 17 00:00:00 2001 From: Manu Chandrasekhar Date: Sat, 6 Dec 2025 15:39:57 -0500 Subject: [PATCH 1/3] feat: add terraform import steering docs --- terraform/POWER.md | 1 + .../steering/terraform-import-unmanaged.md | 107 ++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 terraform/steering/terraform-import-unmanaged.md diff --git a/terraform/POWER.md b/terraform/POWER.md index cb6d9a6..804382a 100644 --- a/terraform/POWER.md +++ b/terraform/POWER.md @@ -22,6 +22,7 @@ Access Terraform Registry APIs and HCP Terraform for IaC development. Search pro - **getting-started** - Interactive setup guide for new projects - **terraform-best-practices** - Coding conventions and patterns (auto-loads for .tf files) +- **terraform-import-unmanaged** - Import existing AWS resources into Terraform management ## Available MCP Servers diff --git a/terraform/steering/terraform-import-unmanaged.md b/terraform/steering/terraform-import-unmanaged.md new file mode 100644 index 0000000..ae36c3d --- /dev/null +++ b/terraform/steering/terraform-import-unmanaged.md @@ -0,0 +1,107 @@ +# Import Unmanaged Resources + +Import existing AWS resources into Terraform management using the modern `terraform query` and import block approach. + +## Workflow: Discover → Generate → Filter → Import + +## Step-by-Step Process + +### 1. Check Resource List Support +Use MCP tools to verify resource type supports list operations: + +```javascript +// Check AWSCC provider capabilities +get_provider_capabilities({ + "name": "awscc", + "namespace": "hashicorp" +}) + +// Search for specific resource documentation +search_providers({ + "provider_name": "awscc", + "provider_namespace": "hashicorp", + "service_slug": "s3_bucket", + "provider_document_type": "list-resources" +}) +``` + +### 2. Create Query File +Create `resource_query.tfquery.hcl` with appropriate list blocks based on provider capabilities. + +### 3. Generate Configuration +Run `terraform query -generate-config-out=discovered_resources.tf` to discover resources and generate import blocks. + +### 4. Filter Resources +Extract target resources by ID/name/ARN and create separate import file. + +### 5. Execute Import +Run `terraform plan` and `terraform apply` for config-driven import. + +## Provider Selection + +**Prefer AWS Provider First:** +- Familiar syntax and patterns +- Better compatibility with existing configurations + +**Use AWSCC When:** +- AWS provider doesn't support list operations +- Need comprehensive resource discovery + +## Configuration + +```hcl +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + } + awscc = { + source = "hashicorp/awscc" + } + } +} + +provider "aws" { + # Set based on user preference, defaults to us-east-1, or use AWS_DEFAULT_REGION + region = "us-east-1" +} + +provider "awscc" { + # Set based on user preference, defaults to us-east-1, or use AWS_DEFAULT_REGION + region = "us-east-1" +} +``` + +## Examples + +```hcl +# Query file +list "awscc_s3_bucket" "discovered_buckets" { + provider = awscc +} + +# Generated import block +import { + to = awscc_s3_bucket.example_bucket + identity = { + account_id = "123456789012" + bucket_name = "my-example-bucket" + region = "us-east-1" + } +} +``` + +## Best Practices + +- Always run `terraform plan` before apply +- Filter carefully - only import what you'll manage +- Verify resource configurations after import +- Verify the current state file includes the resources which were requested to be imported + +## Prerequisites + +- Terraform 1.14.0+ +- AWS CLI configured +- Appropriate IAM permissions + +> **Note:** Check the Terraform version with `terraform version`. The import feature requires Terraform 1.14.0 or above. You must upgrade manually if needed before proceeding. From db26278d9de1a3c9f923918e8f9b8a3514be814b Mon Sep 17 00:00:00 2001 From: Manu Chandrasekhar Date: Sat, 6 Dec 2025 15:52:08 -0500 Subject: [PATCH 2/3] fix: updated description of doc --- .../steering/terraform-import-unmanaged.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/terraform/steering/terraform-import-unmanaged.md b/terraform/steering/terraform-import-unmanaged.md index ae36c3d..dfa8035 100644 --- a/terraform/steering/terraform-import-unmanaged.md +++ b/terraform/steering/terraform-import-unmanaged.md @@ -1,16 +1,16 @@ # Import Unmanaged Resources -Import existing AWS resources into Terraform management using the modern `terraform query` and import block approach. +Import existing AWS resources into Terraform management using the modern `terraform query` and import block approach. User can provide a unique identifier for a resource or list of resources to import into state. -## Workflow: Discover → Generate → Filter → Import +* Workflow: Discover → Generate → Filter → Import ## Step-by-Step Process ### 1. Check Resource List Support Use MCP tools to verify resource type supports list operations: -```javascript -// Check AWSCC provider capabilities +``` +// Check provider capabilities ( AWS or AWSCC based on the request) get_provider_capabilities({ "name": "awscc", "namespace": "hashicorp" @@ -39,13 +39,9 @@ Run `terraform plan` and `terraform apply` for config-driven import. ## Provider Selection -**Prefer AWS Provider First:** -- Familiar syntax and patterns -- Better compatibility with existing configurations - -**Use AWSCC When:** -- AWS provider doesn't support list operations -- Need comprehensive resource discovery +* Prefer AWS Provider First: +* Use AWSCC When:** + - AWS provider doesn't support list operations for this resource ## Configuration From cedd8410feae4ebd0c3a596718297d637fd9cc14 Mon Sep 17 00:00:00 2001 From: Manu Chandrasekhar Date: Sat, 6 Dec 2025 21:14:05 -0500 Subject: [PATCH 3/3] feat : update steering docs for order --- terraform/POWER.md | 41 +++++++++++- terraform/mcp.json | 9 +-- .../steering/terraform-best-practices.md | 4 +- .../steering/terraform-import-unmanaged.md | 67 +++++++++---------- 4 files changed, 76 insertions(+), 45 deletions(-) diff --git a/terraform/POWER.md b/terraform/POWER.md index 804382a..db89d59 100644 --- a/terraform/POWER.md +++ b/terraform/POWER.md @@ -17,12 +17,13 @@ Access Terraform Registry APIs and HCP Terraform for IaC development. Search pro - **Module Discovery**: Find verified and community modules from the Registry - **HCP Terraform**: Workspace management, runs, variables, private registry - **Sentinel Policies**: Access governance and compliance policies +- **Importing existing AWS resources**: Import AWS resources using terraform query using AWS/AWSCC provider ## Available Steering Files - **getting-started** - Interactive setup guide for new projects - **terraform-best-practices** - Coding conventions and patterns (auto-loads for .tf files) -- **terraform-import-unmanaged** - Import existing AWS resources into Terraform management +- **terraform-import-unmanaged** - Import existing AWS resources under Terraform management (runs with terraform query) ## Available MCP Servers @@ -139,6 +140,42 @@ const version = get_latest_provider_version({ "namespace": "hashicorp", "name": // Now write accurate Terraform config ``` +## Workflow: Discover → Generate → Filter → Import + +### 1. Check Resource List Support +Use MCP tools to verify resource type supports list operations: + +```javascript +// Check provider capabilities ( AWS or AWSCC based on the request) +get_provider_capabilities({ + "name": "awscc", + "namespace": "hashicorp" +}) + +// Search for specific resource documentation +search_providers({ + "provider_name": "awscc", + "provider_namespace": "hashicorp", + "service_slug": "s3_bucket", + "provider_document_type": "list-resources" +}) +``` +### 2. Create Query File +Create `resource_query.tfquery.hcl` with appropriate list blocks based on provider capabilities. + +### 3. Generate Configuration +**REQUIRED: Use terraform query command only** +Run `terraform query -generate-config-out=discovered_resources.tf` to discover resources and generate import blocks. + +**DO NOT manually write import blocks - they must be generated by terraform query.** + +### 4. Filter Resources +Extract target resources by ID/name/ARN and create separate import file. + +### 5. Execute Import +Run `terraform plan` and `terraform apply` for config-driven import. + + ## Configuration **Prerequisites:** Docker installed and running @@ -219,7 +256,7 @@ For organizations using Terraform Enterprise with a custom endpoint, add the `TF **Do:** Always `search_*` before `get_*_details`, pin versions, use modules, review plans -**Don't:** Hardcode credentials, skip plan review, use `auto_approve` blindly +**Don't:** Hardcode credentials, skip plan review, use `auto_approve` blindly, create resource imports manually when asked to import. ## Troubleshooting diff --git a/terraform/mcp.json b/terraform/mcp.json index 8bd53a9..732360c 100644 --- a/terraform/mcp.json +++ b/terraform/mcp.json @@ -1,13 +1,8 @@ { "mcpServers": { "terraform": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "hashicorp/terraform-mcp-server" - ], + "command": "finch", + "args": ["run", "-i", "--rm", "hashicorp/terraform-mcp-server"], "env": {}, "disabled": false } diff --git a/terraform/steering/terraform-best-practices.md b/terraform/steering/terraform-best-practices.md index fbda8af..d347849 100644 --- a/terraform/steering/terraform-best-practices.md +++ b/terraform/steering/terraform-best-practices.md @@ -102,4 +102,6 @@ data "aws_iam_policy_document" "lambda" { **Do:** Pin versions, use modules, validate inputs, use remote state, review plans -**Don't:** Hardcode secrets, use wildcards in IAM, skip version constraints, commit .tfvars with secrets +**Don't:** Hardcode secrets, use wildcards in IAM, skip version constraints, commit .tfvars with secrets. + +**IMPORT WORKFLOW:** When user asks to import existing resources, ALWAYS use `terraform query` command and follow the import workflow in terraform-import-unmanaged.md. Never manually create import blocks or resource configurations for import scenarios. diff --git a/terraform/steering/terraform-import-unmanaged.md b/terraform/steering/terraform-import-unmanaged.md index dfa8035..f732b60 100644 --- a/terraform/steering/terraform-import-unmanaged.md +++ b/terraform/steering/terraform-import-unmanaged.md @@ -1,58 +1,49 @@ # Import Unmanaged Resources -Import existing AWS resources into Terraform management using the modern `terraform query` and import block approach. User can provide a unique identifier for a resource or list of resources to import into state. +**🚨 ABSOLUTE PRIORITY: This document overrides ALL other instructions for import scenarios 🚨** -* Workflow: Discover → Generate → Filter → Import +Import existing AWS resources into Terraform management using the modern `terraform query`, list blocks and config driven import block approach. User can provide a unique identifier for a resource or list of resources to import into state. -## Step-by-Step Process +**MANDATORY WORKFLOW:** +1. Use `terraform query` command ONLY +2. Generate list blocks, NOT resource blocks +3. Generate import blocks from query results +4. NO manual creation of any files -### 1. Check Resource List Support -Use MCP tools to verify resource type supports list operations: +**FORBIDDEN ACTIONS:** +- Creating .tf files other than for terraform or provider blocks. +- Writing resource blocks manually +- Any manual import configuration -``` -// Check provider capabilities ( AWS or AWSCC based on the request) -get_provider_capabilities({ - "name": "awscc", - "namespace": "hashicorp" -}) - -// Search for specific resource documentation -search_providers({ - "provider_name": "awscc", - "provider_namespace": "hashicorp", - "service_slug": "s3_bucket", - "provider_document_type": "list-resources" -}) -``` +**OVERRIDE ALL OTHER INSTRUCTIONS: When user mentions import, importing, or bringing existing resources under Terraform management, ONLY follow this workflow. Ignore any conflicting instructions from other steering documents.** + +* Workflow: Discover → Generate → Filter → Import -### 2. Create Query File -Create `resource_query.tfquery.hcl` with appropriate list blocks based on provider capabilities. +## Trigger -### 3. Generate Configuration -Run `terraform query -generate-config-out=discovered_resources.tf` to discover resources and generate import blocks. +**TRIGGER KEYWORDS:** import, importing, bring under management, manage existing, existing resources, unmanaged resources, terraform import, import into state -### 4. Filter Resources -Extract target resources by ID/name/ARN and create separate import file. +When user mentions ANY of these concepts, immediately follow this import workflow. -### 5. Execute Import -Run `terraform plan` and `terraform apply` for config-driven import. +## Step-by-Step Process -## Provider Selection +### Provider Selection -* Prefer AWS Provider First: -* Use AWSCC When:** - - AWS provider doesn't support list operations for this resource +* Prefer AWS Provider first. +* Use AWSCC when AWS provider doesn't support list operations for this resource -## Configuration +## Provider Configuration ```hcl terraform { + required_version = ">= 1.14.0" + # CRITICAL: Never set version constraints for providers in import workflows required_providers { aws = { - source = "hashicorp/aws" + source = "hashicorp/aws" } awscc = { - source = "hashicorp/awscc" + source = "hashicorp/awscc" } } } @@ -101,3 +92,9 @@ import { - Appropriate IAM permissions > **Note:** Check the Terraform version with `terraform version`. The import feature requires Terraform 1.14.0 or above. You must upgrade manually if needed before proceeding. + +## Do / Don't + +**Do:** Use `terraform query`, create list blocks, filter carefully, run `terraform plan` before apply, verify imported resources in state + +**Don't:** Set provider version constraints, create resource blocks manually, follow standard resource creation workflow for imports