Well-Architected IaC (Infrastructure as Code) Analyzer

Description

Well-Architected Infrastructure as Code (IaC) Analyzer is a sample project that demonstrates how generative AI can be used to evaluate infrastructure code for alignment with best practices.

It features a modern web application built with React and AWS Cloudscape Design System, allowing users to upload IaC documents (e.g., AWS CloudFormation, Terraform, or AWS CDK templates), complete IaC projects (multiple files or zip archives), or architecture diagrams for assessment. The application leverages Amazon Bedrock to analyze the infrastructure against AWS Well-Architected best practices. These best practices are sourced from AWS Well-Architected whitepapers and synchronized with the Amazon Bedrock knowledge base.

This tool provides users with insights into how well their infrastructure code aligns with or deviates from established AWS best practices, offering suggestions for improving cloud architecture designs. Users can also upload supporting documents to provide additional context for more accurate analysis results. For architecture diagrams, it can even generate corresponding IaC templates following AWS best practices.

Additionally, an interactive Analyzer Assistant chatbot enables users to ask questions, seek clarification, and receive personalized guidance about analysis results and Well-Architected best practices.

Note: This is a sample project, for non-production usage. You should work with your security and legal teams to meet your organizational security, regulatory and compliance requirements before deployment

Features

• NEW 🎯 Prioritization Framework with Eisenhower Matrix:
• Each Not Applied best practice is scored with Criticality (from Knowledge Base Risk Level), Complexity (remediation effort), and Priority (Immediate | Short-term | Long-term) derived via the Eisenhower Matrix
• New Priorities tab visualizes every relevant, Not Applied best practice on an interactive Eisenhower-style matrix, plotted by Risk criticality (impact) and Implementation effort (complexity) across four quadrants: Quick wins, Major initiatives, Delegate, and Reconsider
• Click any point on the matrix to open a details panel with the best practice's status reason, recommendation, and Criticality/Complexity/Priority reasons, or ask the Analyzer Assistant about it in one click

• Filter the analysis by Criticality, Complexity, or Priority to focus remediation planning, and export all fields to CSV

• NEW 🧠 Enhanced AI Capabilities with Latest Anthropic Models:

• Full support for Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 4.6, and Claude Opus 4.6 models
• Supported Claude models leverage Adaptive Thinking for complex reasoning and analysis

• 1M token context window natively supported by Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6 models, enabling analysis of much larger IaC projects and architectural documentation in a single pass

• 🚀 Accelerated Analysis with Parallel Processing:

• Configurable batch size controls how many Well-Architected (or selected Lens) questions are processed in parallel
• Complete full framework review up to 80% faster compared per-question sequential processing

• Default adjustable batch size configuration (between 1-12) balances speed and API throttling risk

• 💰 Cost-Optimized Vector Storage with Amazon S3 Vectors:

• S3 Vectors is the default vector store for the Bedrock Knowledge Base
• Achieve up to 80% cost reduction compared to OpenSearch Serverless while maintaining sub-second query performance
• OpenSearch Serverless remains available as an option for deployment

• Upload and analyze Infrastructure as Code templates:
• CloudFormation (YAML/JSON)
• Terraform (.tf)
• AWS CDK (in any supported language)
• Upload and analyze architecture diagrams:
• PNG format
• JPEG/JPG format
• Analyze complete IaC projects:
• Multiple files at once
• ZIP archives containing infrastructure code
• Upload and analyze architectural documentation in PDF format:
• PDF documents (up to 5 files, max 4.5MB each)
• With the recent "Citations API and PDF support for Claude models", the analyzer is now able to analyze text, charts and visuals (e.g. embedded images and diagrams) from the PDF documents.
• Interactive Analyzer Assistant chatbot:
• Ask questions about analysis results
• Get detailed explanations of Well-Architected best practices
• Receive personalized guidance for implementation
• View conversation history with markdown support
• Download or delete chat histories for each analysis
• Add supporting documents (PDF, TXT, PNG, JPEG) to provide additional context for analysis
• Generate IaC templates from architecture diagrams
• Real-time analysis against Well-Architected best practices
• Integration with AWS Well-Architected Tool
• Export analysis results and recommendations
• Language Localization Support:
• Select your preferred language from the Output Language in Optional Settings menu
• Support for English, Japanese, Korean, Brazilian Portuguese, Spanish and French
• Language selection affects analysis results, recommendations, and detailed explanations
• Consistent localization across all file types (CloudFormation, Terraform, CDK, PDF documents, and architecture diagrams)
• Multi-lens support:
• Analyze infrastructure against specialized Well-Architected lenses
• Support for domain-specific lenses including Serverless, IoT, SaaS, Machine Learning, and more
• Get tailored recommendations specific to your workload type
• Switch between different lenses for comprehensive analysis
• Custom Lenses support:
• Extend analysis beyond AWS Official Lenses with your organization's own Custom Lenses
• Define custom pillars, questions, and best practices specific to your security policies, compliance requirements, or internal standards
• Integrate custom lens documentation (PDF) with the Amazon Bedrock Knowledge Base for AI-powered analysis
• See the Custom Lenses Guide for step-by-step instructions

Expand to see the list of supported AWS Official Lenses:

• AWS Well-Architected Framework (core framework)
• Industry Lenses:
• Financial Services Industry
• Healthcare Industry
• Government
• Mergers and Acquisitions
• Technology Lenses:
• Generative AI
• Serverless Applications
• Machine Learning
• IoT (Internet of Things)
• SaaS (Software as a Service)
• Data Analytics
• Container Build
• DevOps
• Migration
• Connected Mobility
• SAP

Installation and Deployment

You have three options for deploying this solution: - Option 1: Using a CloudFormation Deployment Stack (Recommended) - Option 2: Using a Deployment Script - Option 3: Manual Deployment

Option 1: Using a CloudFormation Deployment Stack (Recommended)

This option uses AWS CloudFormation to create a temporary deployment environment to deploy the Well-Architected IaC Analyzer solution. This approach doesn't require any tools to be installed on your local machine.

Deployment Steps

1. Download the CloudFormation template: iac-analyzer-deployment-stack.yaml

2. Open the AWS CloudFormation console:

3. Make sure you are in the same AWS region where you enabled access to the LLM models

4. On the "Create stack" page:

5. Select "Upload a template file" and upload the iac-analyzer-deployment-stack.yaml template

6. Choose "Next"

7. On the "Specify stack details" page. Enter or change the stack name, then:

8. Change the stack parameters as needed. Check the CloudFormation Configuration Parameters section below for details

   • Security Note: By default, the stack deploys with a Public Application Load Balancer (internet-facing) with authentication enabled. For maximum security, we strongly recommend keeping authentication enabled for internet-facing deployments. If you disable authentication, your application will be publicly accessible without any security controls.

   • Model Selection Note: The tool currently defaults to Claude Sonnet 4.6. If you want to use a different model (E.g. Claude Fable 5, Claude Opus 4.8, or Claude Opus 4.7), you'll need to explicitly add the model ID in the stack "Amazon Bedrock Model ID" configuration parameter. Please note that not all models are available in all AWS regions, so verify availability in your region before deployment.

   • Geographic and Global Cross-Region Inference Note: The default Claude Sonnet 4.6 model ID uses a GLOBAL cross-Region inference profile (global.anthropic.claude-sonnet-4-6), which routes requests to any supported AWS commercial Region worldwide for optimal performance and cost savings. If your organization has data residency or compliance requirements, consider using a GEOGRAPHIC inference profile instead (e.g., "us." or "eu." prefix). For more information visit the documentation Choosing between Geographic and Global cross-Region inference

9. Choose "Next" until reaching the "Review" page and choose "Submit".

The deployment process typically takes 15-20 minutes.

Once complete, you'll find a new CloudFormation stack named WA-IaC-Analyzer-{region}-GenAIStack containing all the deployed resources for this solution. Find the application URL in the stack outputs: - In the CloudFormation console, navigate to the Outputs tab of the stack named WA-IaC-Analyzer-{region}-GenAIStack - Look for the FrontendURL value

Post-Deployment Steps

1. If you enabled authentication with a custom domain:

2. Create a DNS record (CNAME or Alias) pointing to the ALB domain name

3. If you created a new Cognito user pool:

4. Navigate to the Amazon Cognito console
5. Find the user pool created by the stack (named "WAAnalyzerUserPool")

6. Add users who should have access to the application

7. Access your deployed application using the URL from the CloudFormation outputs (or your CNAME or Alias pointing to the ALB)

Troubleshooting

If you encounter issues during deployment, you can check the deployment logs in CloudWatch:

• Log Group: iac-deployment-logs-<region>-<unique-id>
• This log group contains all deployment steps and actions
• Log Stream {instance_id}-user-data: Contains deployment instance initialization and setup logs
• Log Stream {instance_id}-deploy: Contains the complete Well-Architected IaC Analyzer deployment logs

You can also find a direct link to these logs in the Outputs tab of your CloudFormation deployment stack.

Option 2: Using a Deployment Script

Expand this section for instructions using the deployment script:

Prerequisites

The following tools must be installed on your local machine:

• Node.js (v18 or later) and npm
• Python (v3.11 or later) and pip
• AWS CDK CLI
• Either one of these container tools:
• Finch
• Docker
• AWS CLI configured with appropriate credentials

Note: If you would like to change the default Load Balancer scheme, AI model or authentication options, check the Configuration Options For Manual Deployments section first before deploying.

1. Clone the Repository

git clone https://github.com/aws-samples/well-architected-iac-analyzer.git
cd well-architected-iac-analyzer

1. Make the deployment script executable:

chmod +x deploy-wa-analyzer.sh

1. Deploy with required parameters:

# Deploy using Docker
./deploy-wa-analyzer.sh -r us-west-2 -c docker

# Or deploy using Finch
./deploy-wa-analyzer.sh -r us-west-2 -c finch

The script will automatically: - Check for prerequisites - Set up the Python virtual environment - Install all dependencies - Deploy the CDK stack - Provide post-deployment information

After successful deployment, you can find the Application Load Balancer (ALB) DNS name in: 1. The outputs of the deploy-wa-analyzer.sh script 2. The outputs section of the CloudFormation stack named WA-IaC-Analyzer-{region}-GenAIStack in the AWS Console

Option 3: Manual Deployment

If you prefer to manually deploy step by step, expand this section for more instructions:

Prerequi