AWS Network Diagram Generation Prompt

Objective: Generate a mermaid diagram of an AWS VPC network architecture

Requirements:

CLI Tools: AWS CLI installed available for use

MCPs: AWS API MCP, https://awslabs.github.io/mcp/servers/aws-api-mcp-server/

{
  "mcpServers": {
    "awslabs.aws-api-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-api-mcp-server@latest"],
      "env": {
        "AWS_REGION": "us-east-1",
        "READ_OPERATIONS_ONLY": "true",
        "REQUIRE_MUTATION_CONSENT": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Step 0: Network Discovery Survey

Before creating your diagram, provide this information to help determine the best approach:

1. AWS Configuration

AWS Profile Name: _________________
Primary Region: _________________
Additional Regions (if any): _________________

2. Scope Definition

What do you want to diagram?

Entire AWS account network
Single VPC and its subnets
Specific environment (dev/staging/prod): _________________
Multi-VPC connectivity (peering, Transit Gateway)
Hybrid connectivity (on-premises connections)
Other: _________________

3. Network Description

Describe your current network infrastructure:

Number of VPCs: _________________

Connectivity patterns (check all that apply):

Special considerations:

_________________________________________________
_________________________________________________
_________________________________________________

Current pain points or confusion areas:

_________________________________________________
_________________________________________________

Complexity Assessment (AI-Assisted)

Instructions for AI: Based on the user's survey responses above, analyze their network and categorize it using these guidelines:

Simple Network Indicators ✅

1 VPC mentioned
Only standard public/private subnets checked
No peering, Transit Gateway, or hybrid connectivity
Single region deployment
Straightforward scope (single VPC or environment)

→ Recommend: Use the basic template with minimal modifications

Medium Network Indicators 🔄

2-5 VPCs mentioned
3-tier architecture or VPC Endpoints checked
Some peering or VPN connectivity
Multiple environments but manageable scope
Some hybrid elements but not extensive

→ Recommend: Extend the basic template with additional components

Complex Network Indicators 📊

6+ VPCs mentioned
Transit Gateway, multi-region, or shared services checked
Extensive hybrid connectivity
Scope includes entire account or multi-region
User mentions pain points around network complexity

→ Recommend: Create multiple focused diagrams (overview + detailed views)

AI Analysis Process:

Count complexity indicators from the survey responses
Assess scope - broader scope often means higher complexity
Consider pain points - confusion often indicates complexity
Recommend approach and explain reasoning
Suggest specific AWS CLI commands based on scope and complexity
Provide tailored template modifications if needed

Step 1: Gather AWS Infrastructure Information

Use these AWS CLI commands to collect network details:

Core Network Components

# Get VPC information
aws ec2 describe-vpcs --profile <YOUR_PROFILE>

# Get subnet information
aws ec2 describe-subnets --profile <YOUR_PROFILE>

# Get Internet Gateway information
aws ec2 describe-internet-gateways --profile <YOUR_PROFILE>

# Get NAT Gateway/Instance information
aws ec2 describe-nat-gateways --profile <YOUR_PROFILE>
# OR for NAT instances:
aws ec2 describe-instances --filters "Name=tag:Name,Values=*nat*" "Name=instance-state-name,Values=running" --profile <YOUR_PROFILE>

# Get route tables
aws ec2 describe-route-tables --profile <YOUR_PROFILE>

Extended Components (for Medium/Complex networks)

# VPC Peering connections
aws ec2 describe-vpc-peering-connections --profile <YOUR_PROFILE>

# Transit Gateway information
aws ec2 describe-transit-gateways --profile <YOUR_PROFILE>
aws ec2 describe-transit-gateway-attachments --profile <YOUR_PROFILE>

# VPN connections
aws ec2 describe-vpn-connections --profile <YOUR_PROFILE>

# VPC Endpoints
aws ec2 describe-vpc-endpoints --profile <YOUR_PROFILE>

# Egress-only Internet Gateways (IPv6)
aws ec2 describe-egress-only-internet-gateways --profile <YOUR_PROFILE>

# Network ACLs (optional)
aws ec2 describe-network-acls --profile <YOUR_PROFILE>

# Security Groups (for reference)
aws ec2 describe-security-groups --profile <YOUR_PROFILE>

Filtering for Large Environments

# Filter by specific VPC
aws ec2 describe-subnets --filters "Name=vpc-id,Values=vpc-xxxxxxxxx" --profile <YOUR_PROFILE>

# Filter by environment tag
aws ec2 describe-vpcs --filters "Name=tag:Environment,Values=prod" --profile <YOUR_PROFILE>

# Filter by region (if using multiple regions)
aws ec2 describe-vpcs --region us-west-2 --profile <YOUR_PROFILE>

Step 2: Create Mermaid Diagram

Create a mermaid diagram with the following structure and styling requirements:

Layout: Use a top-to-bottom graph (graph TB)
Hierarchy: Internet → IGW → VPC → Availability Zones → Subnets
Color scheme: Use solid colors (not transparent) with black text for readability:
- Public subnets: Light blue (#81d4fa)
- Private subnets: Orange (#ffb74d)
- NAT components: Light purple (#ce93d8)
- Internet Gateway: Light green (#a5d6a7)
- Internet: Light red (#ef9a9a)
- VPC background: Light gray (#e0e0e0)
Generic naming: Make the diagram environment-agnostic by:
- Using "AWS Region" instead of specific regions
- Using "Availability Zone A/B" instead of specific AZ names
- Removing specific resource IDs
- Showing CIDR blocks but not specific IPs
Essential elements to include:
- VPC with IPv4 and IPv6 CIDR blocks
- Public and private subnets per AZ
- Internet Gateway connection
- NAT Gateway/Instance placement and routing
- Clear connectivity arrows

Example Mermaid Template

graph TB
    subgraph "AWS Region"
        subgraph "VPC"
            subgraph "CIDR: [YOUR_VPC_CIDR]"
                subgraph "IPv6: Auto-assigned /56"

                    subgraph "Availability Zone A"
                        PubA["Public Subnet<br/>[CIDR]<br/>IPv6: /64"]
                        PrivA["Private Subnet<br/>[CIDR]<br/>IPv6: /64"]
                        NAT["NAT Gateway/Instance<br/>[TYPE]"]
                    end

                    subgraph "Availability Zone B"
                        PubB["Public Subnet<br/>[CIDR]<br/>IPv6: /64"]
                        PrivB["Private Subnet<br/>[CIDR]<br/>IPv6: /64"]
                    end
                end
            end
        end

        IGW["Internet Gateway"]
        Internet["Internet"]
    end

    %% Connections
    Internet --> IGW
    IGW --> PubA
    IGW --> PubB
    PubA --> NAT
    NAT --> PrivA
    NAT --> PrivB

    %% Styling with solid colors and black text
    classDef publicSubnet fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000000
    classDef privateSubnet fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000000
    classDef natInstance fill:#ce93d8,stroke:#7b1fa2,stroke-width:2px,color:#000000
    classDef gateway fill:#a5d6a7,stroke:#2e7d32,stroke-width:2px,color:#000000
    classDef internet fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000000

    class PubA,PubB publicSubnet
    class PrivA,PrivB privateSubnet
    class NAT natInstance
    class IGW gateway
    class Internet internet

Common AWS Network Patterns

3-Tier Architecture Pattern

graph TB
    subgraph "VPC"
        subgraph "Availability Zone A"
            WebA["Web Subnet<br/>10.0.0.0/24"]
            AppA["App Subnet<br/>10.0.16.0/24"]
            DBA["DB Subnet<br/>10.0.32.0/24"]
        end

        subgraph "Availability Zone B"
            WebB["Web Subnet<br/>10.0.1.0/24"]
            AppB["App Subnet<br/>10.0.17.0/24"]
            DBB["DB Subnet<br/>10.0.33.0/24"]
        end
    end

    Internet --> ALB["Application Load Balancer"]
    ALB --> WebA
    ALB --> WebB
    WebA --> AppA
    WebB --> AppB
    AppA --> DBA
    AppB --> DBB

    classDef webTier fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000000
    classDef appTier fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000000
    classDef dbTier fill:#a5d6a7,stroke:#2e7d32,stroke-width:2px,color:#000000

    class WebA,WebB webTier
    class AppA,AppB appTier
    class DBA,DBB dbTier

Hub-and-Spoke with Transit Gateway

graph TB
    subgraph "Shared Services VPC"
        TGW["Transit Gateway"]
        SharedServices["Shared Services<br/>DNS, Logging, etc."]
    end

    subgraph "Production VPC"
        ProdSubnet["Production Workloads"]
    end

    subgraph "Development VPC"
        DevSubnet["Development Workloads"]
    end

    subgraph "On-Premises"
        OnPrem["Corporate Network"]
    end

    TGW --> ProdSubnet
    TGW --> DevSubnet
    TGW --> SharedServices
    TGW --> OnPrem

    classDef hub fill:#ce93d8,stroke:#7b1fa2,stroke-width:2px,color:#000000
    classDef spoke fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000000

    class TGW hub
    class ProdSubnet,DevSubnet,SharedServices,OnPrem spoke

Step 3: Add Documentation

Include a summary section below the diagram with:

VPC: Dual-stack IPv4/IPv6 VPC configuration
Subnets: Distribution across multiple availability zones
NAT Solution: Type of NAT implementation (Gateway vs Instance)
High Availability: Multi-AZ design considerations
Connectivity: Internet access patterns for public/private resources

Troubleshooting Guide

No Results from AWS CLI?

Issue: Commands return empty results or permission errors

Solutions:

# Check AWS credentials and profile
aws sts get-caller-identity --profile <YOUR_PROFILE>

# Verify region settings
aws configure get region --profile <YOUR_PROFILE>

# Test basic EC2 permissions
aws ec2 describe-regions --profile <YOUR_PROFILE>

Required IAM Permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:Describe*"
            ],
            "Resource": "*"
        }
    ]
}

Too Many Resources to Diagram?

Problem: Hundreds of subnets or dozens of VPCs make diagrams unreadable

Solutions:

Filter by environment:

aws ec2 describe-vpcs --filters "Name=tag:Environment,Values=prod" --profile <YOUR_PROFILE>

Focus on one VPC at a time:

aws ec2 describe-subnets --filters "Name=vpc-id,Values=vpc-xxxxxxxxx" --profile <YOUR_PROFILE>

Create multiple diagrams:
- Overview diagram (just VPCs and connections)
- Detailed per-VPC diagrams
- Connectivity-focused diagrams

Common Network Scenarios

IPv4-Only Networks:

Remove all IPv6 references from templates
Remove the IPv6 subgraph layer

No Public Subnets:

Remove Internet Gateway connections
Focus on private connectivity (VPC Endpoints, Transit Gateway)

Default VPC Usage:

Add note about default VPC characteristics
May have different CIDR (172.31.0.0/16)

Legacy/Messy Networks:

Document exceptions and non-standard configurations
Consider cleanup recommendations alongside diagrams
Use comments in mermaid for context

Tips for Success

Readability: Always use color:#000000 in your styling to ensure black text on colored backgrounds
Consistency: Use the same color scheme across all diagrams in your organization
Scalability: Keep the diagram generic so it applies to all environments (dev, staging, prod)
Maintenance: Update the diagram when infrastructure changes are made
Documentation: Include the diagram in your infrastructure documentation and README files

Flexible Template Components

For IPv4-Only Networks

Remove the IPv6 subgraph wrapper:

subgraph "VPC"
    subgraph "CIDR: 10.0.0.0/16"
        subgraph "Availability Zone A"
            PubA["Public Subnet<br/>10.0.96.0/20"]
            PrivA["Private Subnet<br/>10.0.0.0/20"]
        end
    end
end

For Multiple NAT Gateways (HA setup)

Place one NAT per AZ:

subgraph "Availability Zone A"
    PubA["Public Subnet"]
    PrivA["Private Subnet"]
    NATA["NAT Gateway A"]
    PubA --> NATA
    NATA --> PrivA
end

subgraph "Availability Zone B"
    PubB["Public Subnet"]
    PrivB["Private Subnet"]
    NATB["NAT Gateway B"]
    PubB --> NATB
    NATB --> PrivB
end

For VPC Endpoints

Add as separate components with dotted connections:

subgraph "VPC"
    PrivateSubnet["Private Subnet"]
    VPCE["VPC Endpoint<br/>S3/DynamoDB"]
end

PrivateSubnet -.-> VPCE
VPCE -.-> AWSService["AWS Service"]

classDef endpoint fill:#f8bbd9,stroke:#e91e63,stroke-width:2px,color:#000000,stroke-dasharray: 5 5
class VPCE endpoint

For Transit Gateway Architecture

Add TGW as central hub:

graph TB
    subgraph "Region"
        TGW["Transit Gateway"]

        subgraph "VPC-A"
            VPCASubnet["Subnets"]
        end

        subgraph "VPC-B"
            VPCBSubnet["Subnets"]
        end

        OnPrem["On-Premises"]
    end

    TGW --> VPCASubnet
    TGW --> VPCBSubnet
    TGW --> OnPrem

For Database/Cache Subnets

Add third tier for data layer:

subgraph "Availability Zone A"
    WebA["Web Subnet<br/>DMZ"]
    AppA["App Subnet<br/>Application Layer"]
    DBA["DB Subnet<br/>Data Layer"]
    CacheA["Cache Subnet<br/>ElastiCache"]
end

WebA --> AppA
AppA --> DBA
AppA --> CacheA

classDef webTier fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000000
classDef appTier fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000000
classDef dataTier fill:#a5d6a7,stroke:#2e7d32,stroke-width:2px,color:#000000

class WebA webTier
class AppA appTier
class DBA,CacheA dataTier

Scale Guidance

When to Split Diagrams

Single Diagram (✅ Recommended for):

1-3 VPCs
Under 20 subnets total
Simple connectivity patterns

Multiple Diagrams (🔄 Consider for):

4-10 VPCs
20-50 subnets
Hub-and-spoke architectures
Mix of simple and complex VPCs

Diagram Hierarchy (📊 Required for):

10+ VPCs
50+ subnets
Multi-region deployments
Complex enterprise networks

Suggested Diagram Types

Overview Diagram: High-level VPC relationships
Per-VPC Detailed: Individual VPC subnet layouts
Connectivity Map: Focus on peering, TGW, VPN connections
Security Boundaries: NACLs, Security Groups, isolation
Data Flow: Application traffic patterns

Diagram Naming Convention

network-overview.md           # High-level view
network-prod-vpc.md          # Production VPC details
network-connectivity.md       # Inter-VPC connections
network-security-zones.md     # Security boundaries

Sample AI Prompts

Basic Usage (after completing survey)

"I've completed the network survey above. Please analyze my responses, determine the appropriate complexity level, and create a mermaid diagram of my AWS network architecture. Use the profile and scope I specified, with solid fill colors and black text for readability."

Detailed Usage Example

"Based on my survey responses:

AWS Profile: my-prod-profile

Scope: Single VPC in production environment

Network: 1 VPC with standard public/private subnets, 3 AZs, single NAT Gateway

Special considerations: Using fck-nat for cost optimization

Please determine this is a Simple network, gather the infrastructure details using AWS CLI, and create a generic mermaid diagram suitable for documentation."

For Complex Networks

"My survey indicates a Complex network (multiple VPCs, Transit Gateway, hybrid connectivity). Please:

Analyze my network complexity

Recommend which diagrams to create (overview vs detailed)

Start with an overview diagram showing VPC relationships

Use the AWS CLI with my profile enterprise-network-readonly

Make diagrams generic for sharing with stakeholders"

Quick Start Template

Copy this template and fill in your details:

I want to create a network diagram with these details:

**AWS Configuration:**
- Profile: [YOUR_PROFILE]
- Region: [YOUR_REGION]

**Scope:**
- [ ] What I want to diagram: ________________

**Network Description:**
- Number of VPCs: ________________
- Connectivity: [LIST_PATTERNS]
- Special considerations: ________________

Please analyze this information, determine complexity level, and create appropriate mermaid diagrams with solid colors and black text.

westonplatter/ai_prompts_diagram_my_aws_network.md