Runtask Terraform Plan Analyzer

Overview

Enhance your HashiCorp Cloud Platform Terraform (Terraform Cloud) workflows with AI-powered analysis using Amazon Bedrock. This module integrates seamlessly as a Run Task to provide:

• Intelligent Terraform plan analysis with concise, human-friendly summaries
• Advanced function calling capabilities for extended analysis (e.g., AMI evaluation)
• Responsible AI implementation with customizable guardrails

Key Features

1. AI-Powered Plan Summaries

   • Generate clear, natural language summaries of Terraform plan outputs
   • Quickly understand the impact of infrastructure changes

2. Extensible Analysis with Function Calling

   • Leverage AI to perform additional analyses, such as AMI evaluation
   • Easily extend to other API-based tools and services

3. Responsible AI Integration

   • Implement Amazon Bedrock guardrails tailored to your organization's policies
   • Ensure ethical and compliant AI usage in your infrastructure workflows

4. Secure Architecture

   • Designed for deployment in a dedicated AWS account
   • Optional AWS WAF integration for enhanced endpoint protection
   • Adherence to AWS security best practices

5. Seamless Terraform Cloud Integration

   • Operates as a native Run Task within your Terraform Cloud workflow
   • Provides insights without disrupting existing processes

6. Flexible and Customizable

   • Adapt the module to fit your specific organizational needs
   • Easily configure and extend guardrails and analysis capabilities

Architecture

This module leverages a hub-spoke model, designed for deployment in a dedicated AWS account with Amazon Bedrock access. It utilizes AWS Lambda, CloudFront, and other AWS services to provide a scalable and secure solution.

Prerequisites

To implement this module, you'll need:

1. An AWS account with appropriate credentials
2. Access to Amazon Bedrock (default model: Claude 3 Sonnet)
3. A HashiCorp Cloud Platform (HCP) Terraform account

Getting Started

For detailed setup instructions and best practices, please refer to the sections below:

• Usage
• Best Practices

Enhance your Terraform workflows with AI-powered insights while maintaining security and responsible AI practices.

Usage

• Build and package the Lambda files

  make all
  

• Enable Bedrock model access for Claude 3 Sonnet. Refer to this guide for more info.

• Reference the examples/basic folder on how to use this module

  cd examples/basic
  terraform init
  terraform plan
  terraform apply

Best practice

• Do not re-use the Run Tasks URL across different trust-boundary (organizations, accounts, team). We recommend you to deploy separate Run Task deployment per trust-boundary.

• Do not use Run Tasks URL from untrusted party, remember that Run Tasks execution sent Terraform plan output to the Run Task endpoint. Only use trusted Run Tasks URL.

• Enable the AWS WAF setup by setting variable deploy_waf to true (additional cost will apply). This will add WAF protection to the Run Tasks URL endpoint.

• We recommend you to setup additional CloudWatch alarm to monitor Lambda concurrency and WAF rules.

• We recommend to add additional topic to the Bedrock Guardrail to fit your organization requirements.

Requirements

Name	Version
terraform	>= 1.5.0
archive	~>2.2.0
aws	>= 5.72.0
random	>=3.4.0

Providers

Name	Version
archive	~>2.2.0
aws	>= 5.72.0
aws.cloudfront_waf	>= 5.72.0
random	>=3.4.0
terraform	n/a
time	n/a

Modules

Name	Source	Version
runtask_cloudfront	terraform-aws-modules/cloudfront/aws	3.4.0

Resources

Name	Type
aws_bedrock_guardrail.runtask_fulfillment	resource
aws_bedrock_guardrail_version.runtask_fulfillment	resource
aws_cloudfront_origin_request_policy.runtask_cloudfront	resource
aws_cloudwatch_event_rule.runtask_rule	resource
aws_cloudwatch_event_target.runtask_target	resource
aws_cloudwatch_log_group.runtask_callback	resource
aws_cloudwatch_log_group.runtask_eventbridge	resource
aws_cloudwatch_log_group.runtask_fulfillment	resource
aws_cloudwatch_log_group.runtask_fulfillment_output	resource
aws_cloudwatch_log_group.runtask_request	resource
aws_cloudwatch_log_group.runtask_states	resource
aws_cloudwatch_log_group.runtask_waf	resource
aws_cloudwatch_log_resource_policy.runtask_waf	resource
aws_iam_role.runtask_callback	resource
aws_iam_role.runtask_edge	resource
aws_iam_role.runtask_eventbridge	resource
aws_iam_role.runtask_fulfillment	resource
aws_iam_role.runtask_request	resource
aws_iam_role.runtask_rule	resource
aws_iam_role.runtask_states	resource
aws_iam_role_policy.runtask_eventbridge	resource
aws_iam_role_policy.runtask_fulfillment	resource
aws_iam_role_policy.runtask_rule	resource
aws_iam_role_policy.runtask_states	resource
aws_iam_role_policy_attachment.runtask_callback	resource
aws_iam_role_policy_attachment.runtask_edge	resource
aws_iam_role_policy_attachment.runtask_eventbridge	resource
aws_iam_role_policy_attachment.runtask_fulfillment_additional_attachment	resource
aws_iam_role_policy_attachment.runtask_fulfillment_basic_attachment	resource
aws_iam_role_policy_attachment.runtask_fulfillment_bedrock_attachment	resource
aws_iam_role_policy_attachment.runtask_request	resource
aws_kms_alias.runtask_key	resource
aws_kms_alias.runtask_waf	resource
aws_kms_key.runtask_key	resource
aws_kms_key.runtask_waf	resource
aws_lambda_function.runtask_callback	resource
aws_lambda_function.runtask_edge	resource
aws_lambda_function.runtask_eventbridge	resource
aws_lambda_function.runtask_fulfillment	resource
aws_lambda_function.runtask_request	resource
aws_lambda_function_url.runtask_eventbridge	resource
aws_lambda_permission.runtask_eventbridge	resource
aws_secretsmanager_secret.runtask_cloudfront	resource
aws_secretsmanager_secret.runtask_hmac	resource
aws_secretsmanager_secret_version.runtask_cloudfront	resource
aws_secretsmanager_secret_version.runtask_hmac	resource
aws_sfn_state_machine.runtask_states	resource
aws_wafv2_web_acl.runtask_waf	resource
aws_wafv2_web_acl_logging_configuration.runtask_waf	resource
random_string.solution_prefix	resource
random_uuid.runtask_cloudfront	resource
random_uuid.runtask_hmac	resource
terraform_data.bootstrap	resource
time_sleep.wait_1800_seconds	resource
archive_file.runtask_callback	data source
archive_file.runtask_edge	data source
archive_file.runtask_eventbridge	data source
archive_file.runtask_fulfillment	data source
archive_file.runtask_request	data source
aws_caller_identity.current_account	data source
aws_iam_policy.bedrock_full_access_managed_policy	data source
aws_iam_policy.ec2_readonly_managed_policy	data source
aws_iam_policy.lambda_basic_execution_managed_policy	data source
aws_iam_policy_document.runtask_key	data source
aws_iam_policy_document.runtask_waf	data source
aws_iam_policy_document.runtask_waf_log	data source
aws_partition.current_partition	data source
aws_region.cloudfront_region	data source
aws_region.current_region	data source

Inputs

Name	Description	Type	Default	Required
aws_region	The region from which this module will be executed.	string	n/a	yes
hcp_tf_org	HCP Terraform Organization name	string	n/a	yes
bedrock_llm_model	Bedrock LLM model to use (supports cross-region inference profiles)	string	"global.anthropic.claude-sonnet-4-20250514-v1:0"	no
cloudwatch_log_group_name	RunTask CloudWatch log group name	string	"/hashicorp/terraform/runtask/"	no
cloudwatch_log_group_retention	Lambda CloudWatch log group retention period	string	"365"	no
deploy_waf	Set to true to deploy CloudFront and WAF in front of the Lambda function URL	string	false	no
event_bus_name	EventBridge event bus name	string	"default"	no
event_source	EventBridge source name	string	"app.terraform.io"	no
lambda_architecture	Lambda architecture (arm64 or x86_64)	string	"x86_64"	no
lambda_default_timeout	Lambda default timeout in seconds	number	300	no
lambda_python_runtime	Lambda Python runtime	string	"python3.11"	no
lambda_reserved_concurrency	Maximum Lambda reserved concurrency, make sure your AWS quota is sufficient	number	10	no
name_prefix	Name to be used on all the resources as identifier.	string	"runtask-tf-plan-analyzer"	no
recovery_window	Number of days that AWS Secrets Manager waits before it can delete the secret	number	0	no
run_task_iam_roles	List of IAM roles to be attached to the Lambda function	list(string)	null	no
runtask_stages	List of all supported run task stages	list(string)	[ "pre_plan", "post_plan", "pre_apply" ]	no
tags	Map of tags to apply to resources deployed by this solution.	map(any)	null	no
waf_managed_rule_set	List of AWS Managed rules to use inside the WAF ACL	list(map(string))	[ { "metric_suffix": "common", "name": "AWSManagedRulesCommonRuleSet", "priority": 10, "vendor_name": "AWS" }, { "metric_suffix": "bad_input", "name": "AWSManagedRulesKnownBadInputsRuleSet", "priority": 20, "vendor_name": "AWS" } ]	no
waf_rate_limit	Rate limit for request coming to WAF	number	100	no
workspace_prefix	HCP Terraform workspace name prefix that allowed to run this run task	string	""	no

Outputs

Name	Description
runtask_hmac	HMAC key value, keep this sensitive data safe
runtask_url	The Run Tasks URL endpoint, you can use this to configure the run task setup in HCP Terraform