zloeber/terraform-ingest-example

Terraform-ingest-example

This is an example full workspace for vscode for a large custom terraform module collection from a team of Terraform pros I happen to hold in the highest regards, Cloudposse. They have produced almost 200 professional quality AWS terraform modules and more for the community. Here is how you would ingest all their modules to use as a basis for further terraform work via terraform-ingest and MCP.

Installing

A handful of tools are needed to make this work properly. You can install them all with mise which can be installed for your user account using the included ./configure.sh script.

NOTE: I do recommend you read the install script over to understand what you are doing. I also highly recommend configuring mise in your user shell for automated activation in folder that include the mise.toml configuration files. Otherwise you can run mise en to enable it on-demand.

For this example you will also need the terraform-ingest tool. I purposefully left it out of automated package installation for this exercise. You can install it using uv as a tool instead:

uv tool install terraform-ingest
uvx terraform-ingest --version

NOTE To upgrade run uv tool upgrade terraform-ingest

To get the most out of this MCP server it should be paired with the terraform-mcp-server by HashiCorp and possibly even a cloud documentation MCP (in this case AWS as that is the target for all of these modules). Take a look at the included .

The Setup

We can import a target github organization directly using terraform-ingest. Because Cloudposse is really good with standardized modules and tagged releases we purposefully target only the latest tagged release and the ./src path. The following was done prior to committing this project and does not need to be run again to proceed with using this example project:

uv tool run terraform-ingest init ./.vscode/cloudposse.yaml
uv tool run terraform-ingest import github --org cloudposse-terraform-components --token '<GITHUB_TOKEN>' --terraform-only --base-path './src' --max-tags 1 --replace -c ./.vscode/cloudposse.yaml

NOTE Exclude the --token parameter if you already have it in your environment as GITHUB_TOKEN

As there are so many modules I found it best to ingest them all ahead of starting the mcp server. This is easily done with the following command:

uv tool run terraform-ingest ingest --auto-install-deps .vscode/cloudposse.yaml

IMPORTANT If you do not include --auto-install-deps then the MCP server might fail to function properly depending on your configuration. Be patient with this step the first time you run it as the libraries are pretty large.

This takes a minute or two and ends with a summary of ingested modules.

...
Ingestion complete!
Processed 167 module(s)
Summaries saved to output

Vector Database Statistics:
  Collection: terraform_modules
  Documents: 167
  Strategy: chromadb-default

Example 1 - Migration

A fictitious online applications selling tickets to heaven.

Initially generated a bunch of terraform for an AWS fictitious low cost ordering system that uses native AWS terraform. I then prompted Copilot to use terraform-ingest after ingesting the terraform-ingest configuration and starting the MCP server to create a conversion doc from the manifests to use CloudPosse modules as much as possible. Files for this are found .

Create a document of possible terraform modules to use for the terraform code in ./terraform. Use search_modules_vector to find as many relevant modules as possible for this folder. If applicable modules are found, use get_module_details to get information needed to create the terraform module blocks need to use them. Ensure you create code for the modules that use the ssh git url format and repository ref as the version. Create a CONVERSION.md of the modules you would create and how you would convert the project.

You can see the result of this where it properly found applicable modules to use and gave a phased approach to migrating to them.

Example 2 - On Demand Documentation

Probably the easiest use case for this MCP server is readily accessing your modules requirements without needing to leave your editor.

With several dozen modules spread across repositories it can be a pain to recall the inputs/output for each module when you are authoring new or existing Terraform. To get around this, you can use terraform-ingest as a means to quickly get these details and generate example module blocks to use them.

# Generate example module call for one of your custom modules
Generate an example terraform module call for aws-kms using the source format for ssh git

# Get expected inputs for one of your modules
What are the expected inputs for the aws-argocd-github-repo terraform module?

With the last prompt in copilot it will use the search_modules tool to get the module information, provide all required and optional inputs in a table, AND provide example usage. Nifty!

Example 2 - Output

This was run with the MCP server started in the agent chat window and has no files to reference, just nice output on the module

What are the expected inputs for the aws-argocd-github-repo terraform module?

Let me search for the aws-argocd-github-repo module to get its expected inputs.

Ran search_modules Completed with input: { "query": "aws-argocd-github-repo" }

Based on the search results, here are the expected inputs for the aws-argocd-github-repo Terraform module (version v2.2.0):

Required Inputs

Optional Inputs

Example Usage

module "argocd_github_repo" {
  source = "git::ssh://git@github.com/cloudposse-terraform-components/aws-argocd-github-repo.git//src?ref=v2.2.0"

  region                  = "us-east-1"
  description             = "ArgoCD desired state repository"
  github_user             = "ci-acme"
  github_user_email       = "ci@acme.com"
  github_organization     = "ACME"
  github_base_url         = "https://github.com/"
  github_codeowner_teams  = ["@ACME/cloud-admins", "@ACME/cloud-posse"]
  gitignore_entries       = [".idea/", ".vscode/", "*.tfvars"]
  
  permissions = [
    {
      team_slug  = "admins"
      permission = "admin"
    },
    {
      team_slug  = "engineering"
      permission = "push"
    }
  ]

  environments = [
    {
      tenant      = "mgmt"
      environment = "uw2"
      stage       = "sandbox"
      auto-sync   = true
    }
  ]

  deploy_keys_enabled            = true
  required_pull_request_reviews  = true
  push_restrictions_enabled      = true
  vulnerability_alerts_enabled   = false
}

Example 3 - Direct Module Insertion

Using your inline copilot you can look for and then insert an example module call directly. An example of this was done for an AWS KMS key in with this inline chat prompt:

Find the best terraform module using terraform-ingest to deploy an ec2 auto-scale group into AWS running Amazon linux and create module blocks that use them via git ssh target format and the latest tagged release.