Skip to main content

Examples & Use Cases

Real-world scenarios demonstrating the AWS Orchestrator's end-to-end pipeline — from natural language request through research, generation, validation, HITL approval, and GitHub commit.

Each scenario shows the actual conversation flow, including gap detection, self-healing validation, and approval gates.

🏗️ New Module Generation​

Scenario 1: VPC Module with Gap Detection​

Objective: Generate a production-ready VPC module. The planner detects underspecified requirements and asks for clarification.

The Request​

User: "Create a VPC module with public and private subnets across 3 AZs."

1. Planning (Gap Detection)​

The tf-planner runs requirements analysis and detects missing details:

Agent: "I'll build this VPC module for you. Before I start, I need a couple of clarifications:

  1. NAT Gateway topology — Should I deploy one NAT Gateway per AZ (high availability, ~$100/mo) or a single shared NAT Gateway (cost-effective, ~$35/mo)?
  2. CIDR block — Do you have a preferred VPC CIDR, or should I use 10.0.0.0/16 with auto-calculated subnet CIDRs?"

User: "Single NAT to save money. Use 10.0.0.0/16."

2. Research & Skill Writing​

The planner queries the Terraform Registry MCP for the latest AWS VPC provider docs, then runs:

  • Requirements Analysis → VPC, subnets (public × 3, private × 3), NAT Gateway, Internet Gateway, route tables
  • Security & Best Practices → VPC flow logs, DNS hostname/support enabled, map_public_ip_on_launch=false for private subnets
  • Execution Planning → Writes SKILL.md with file set: main.tf, variables.tf, outputs.tf, versions.tf, locals.tf

3. Generation​

The tf-generator reads the skill blueprint and writes 6 files to /workspace/terraform_modules/vpc/.

4. Validation (Self-Healing)​

The tf-validator runs the triple-check:

Issue Detected:

Status: INVALID
Error: variables.tf:45: variable "vpc_cidr" — default value "10.0.0.0/16"
       does not match validation rule: can_cidr_host(var.vpc_cidr, 0)

Self-Healing: The coordinator re-dispatches the generator with the error. The generator fixes the validation rule, writes corrected files, and validation passes on retry.

5. Commit Gate (HITL)​

Agent: "✅ Module 'vpc' Validated

Generated 6 files at workspace/terraform_modules/vpc/: main.tf, variables.tf, outputs.tf, versions.tf, locals.tf, README.md

Key decisions: Single NAT Gateway, 3 AZs, VPC flow logs enabled, DNS support enabled.

🚀 Push to GitHub | 📁 Keep Local

Repository: ____________________ Branch: main"

User: Clicks Push to GitHub, enters acme/infra-modules.

6. GitHub Commit​

The github-agent commits all 6 files via GitHub MCP:

Agent: "Committed 6 files. Commit URL: https://github.com/acme/infra-modules/commit/abc123"

Scenario 2: S3 Bucket with Complex Security​

Objective: Generate an S3 module with encryption, versioning, lifecycle rules, and cross-region replication.

The Request​

User: "Generate Terraform for an S3 bucket with server-side encryption, versioning, lifecycle rules, and cross-region replication to us-west-2."

Research Phase​

The planner identifies 4 resource types needed:

  • aws_s3_bucket (primary + replica)
  • aws_s3_bucket_versioning
  • aws_s3_bucket_lifecycle_configuration
  • aws_s3_bucket_replication_configuration

Security & Best Practices phase adds:

  • KMS encryption (not just AES-256)
  • Block public access on both buckets
  • SSL-only bucket policy

Generated File Set​

workspace/terraform_modules/s3/
├── main.tf              # Primary bucket + versioning + encryption
├── variables.tf         # Bucket name, KMS key ARN, lifecycle rules, replication config
├── outputs.tf           # Bucket ARN, ID, domain, replication bucket ARN
├── versions.tf          # AWS provider >= 5.40.0
├── locals.tf            # Tag merging, lifecycle rule computation
├── policies.tf          # SSL-only bucket policy + replication policy
├── iam.tf               # Replication IAM role with least-privilege policy
└── README.md            # Full usage example with cross-region setup

Agent: "Generated 8 files. Key decisions:

  • KMS encryption (not AES-256) per CIS benchmark
  • Separate IAM role for replication with s3:ReplicateObject only
  • Block public access enabled on both primary and replica buckets
  • Lifecycle rules use for_each for flexible rule configuration"

Scenario 3: EKS Cluster (Complex Multi-File Output)​

Objective: Generate a full EKS cluster module with managed node groups and IRSA.

The Request​

User: "Create an EKS cluster module with managed node groups and IRSA."

Research Highlights​

The planner identifies this as a complex, multi-resource module requiring:

  • EKS cluster with encryption
  • Managed node group with configurable instance types
  • OIDC provider for IRSA (IAM Roles for Service Accounts)
  • Cluster security group + node security group
  • IAM roles: cluster role, node role, IRSA

Generated File Set (10 files)​

workspace/terraform_modules/eks/
├── main.tf              # EKS cluster + OIDC provider
├── variables.tf         # Cluster version, node config, IRSA settings
├── outputs.tf           # Cluster endpoint, CA cert, OIDC issuer URL
├── versions.tf          # AWS provider + Kubernetes provider
├── locals.tf            # Tag merging, OIDC thumbprint computation
├── iam.tf               # Cluster role + node role + IRSA trust policies
├── security_groups.tf   # Cluster SG + node SG with inter-group rules
├── data.tf              # AMI lookup, availability zones
├── templates.tf         # Node group launch template
└── README.md            # Usage with IRSA example

Scenario 4: Lambda + API Gateway (Serverless)​

Objective: Generate a serverless stack with API Gateway triggering Lambda.

The Request​

User: "Plan and execute an API Gateway that triggers an AWS Lambda Python function. The IAM role must adhere to least-privilege against CloudWatch logs. Allow dynamic assignment of log retention days."

Research & Generation​

The planner maps the dependency chain: API Gateway → Lambda Permission → Lambda Function → IAM Role → CloudWatch Log Group.

Agent: "Generated 7 files. Key decisions:

  • IAM role follows least-privilege: only logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents
  • Log retention is a configurable variable (var.log_retention_days, default: 14)
  • API Gateway uses AWS_PROXY integration type
  • Lambda function runtime defaults to python3.12 (configurable via var.runtime)
  • Source code path is a variable (var.source_path) — module doesn't bundle code"

🔄 Module Updates​

Scenario 5: Surgical GitHub Update​

Objective: Add an IAM policy to an existing EKS module on GitHub without rewriting the module.

The Request​

User: "Connect to my repo talkops-ai/infra-modules. Look in the /modules/iam/eks-roles directory. We need to add an inline policy giving this worker role s3:GetObject access to the bucket arn:aws:s3:::corporate-data. Make sure not to overwrite the existing attachments."

1. Analysis (update-planner)​

The update-planner fetches the module via GitHub MCP:

  • Lists directory contents at /modules/iam/eks-roles
  • Reads main.tf, variables.tf, outputs.tf

Agent: "📋 Update Plan:

Target: talkops-ai/infra-modules → /modules/iam/eks-roles Files to modify: main.tf (add inline policy block) Files unchanged: variables.tf, outputs.tf, versions.tf Breaking changes: None — adding a new policy doesn't affect existing attachments Dependencies: Existing aws_iam_role.worker_role resource"

2. Surgical Edit (tf-updater)​

The tf-updater fetches the file, adds only the new aws_iam_role_policy resource block. It does not rewrite the file — it inserts the block at the correct location and preserves all existing formatting.

3. Validation → Commit​

After validation passes:

Agent: "Updated 1 file: main.tf (added inline policy). Committed to talkops-ai/infra-modules branch main."

🔧 Validation & Self-Healing​

Scenario 6: Validation Failure → Automatic Fix​

Objective: Demonstrate the self-healing validation loop in action.

The Setup​

The user requests an RDS module. The generator produces main.tf with an incorrect argument:

resource "aws_db_instance" "this" {
  engine               = var.engine
  engine_version       = var.engine_version
  instance_class       = var.instance_class
  storage_encrypted    = true
  kms_key_arn          = var.kms_key_arn   # ← Wrong argument name
}

Validation Result​

Status: INVALID
Error: main.tf:8 — Unsupported argument "kms_key_arn".
       Did you mean "kms_key_id"?

Self-Healing​

  1. Coordinator re-dispatches tf-generator with: "Fix these errors: main.tf:8 — Unsupported argument 'kms_key_arn'. Did you mean 'kms_key_id'?"
  2. Generator reads the error, fixes kms_key_arn → kms_key_id
  3. sync_workspace → tf-validator runs again
Status: VALID: all checks passed (init ✓, fmt ✓, validate ✓)

Agent: "Module validated after 1 retry. Fixed: kms_key_arn → kms_key_id in main.tf."

✅ HITL Approval Gates​

Scenario 7: Commit Gate → GitHub Push​

Objective: Walk through the full HITL commit gate experience.

After Validation Passes​

The coordinator presents the mandatory commit gate:

Agent: "✅ Module 's3' Validated

Generated 7 files at workspace/terraform_modules/s3/:

  • main.tf — S3 bucket, versioning, encryption, lifecycle
  • variables.tf — 12 variables (bucket name, KMS key, lifecycle rules, ...)
  • outputs.tf — Bucket ARN, ID, domain name, regional domain
  • versions.tf — AWS provider >= 5.40.0, Terraform >= 1.9.0
  • locals.tf — Tag merging, computed names
  • policies.tf — SSL-only bucket policy
  • README.md — Complete usage documentation

🚀 Push to GitHub | 📁 Keep Local

Repository: ____________________ Branch: main"

Option A: Push to GitHub​

User: Clicks Push to GitHub, enters acme/infra-modules, branch feature/s3-module.

The github-agent commits all files:

Agent: "Committed 7 files to acme/infra-modules on branch feature/s3-module. Commit URL: https://github.com/acme/infra-modules/commit/def456"

Option B: Keep Local​

User: Clicks Keep Local.

Agent: "Module kept at workspace/terraform_modules/s3/. You can find the files locally:

workspace/terraform_modules/s3/
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
├── locals.tf
├── policies.tf
└── README.md
```"

Scenario 8: Next Steps Gate → Chain Another Module​

Objective: Demonstrate the post-completion workflow gate.

After Commit (or Keep Local)​

The coordinator presents the mandatory next steps gate:

Agent: "🎉 What's Next?

Successfully generated and committed the S3 module to acme/infra-modules.

➕ Generate Another Module | 🔄 Update Existing Module | ✅ I'm Done

Details for next action: ____________________"

Chaining to a new module​

User: Clicks Generate Another Module, enters "Create a CloudFront distribution that serves from the S3 bucket."

The coordinator seamlessly starts a new module generation cycle — the full pipeline runs again for CloudFront.

Chaining to an update​

User: Clicks Update Existing Module, enters "Add a logging_bucket variable to the S3 module we just created on acme/infra-modules."

The coordinator switches to the Update Module workflow — update-planner → tf-updater → validation → commit.

🌐 Multi-Service Request (Phase 2)​

Scenario 9: Parallel Module Generation (Coming Soon)​

Objective: Preview the upcoming parallel generation capability.

The Request​

User: "Create VPC, S3, and RDS modules for our new microservices platform."

Expected Flow (Phase 2)​

  1. Planner runs for all 3 services (may parallelize)
  2. Generator dispatched for all 3 modules in one response (parallel)
  3. Validator runs for all 3 modules in one response (parallel)
  4. Single HITL commit gate covering all 3 modules
  5. Single github-agent commit for everything

Agent (expected): "Generated 3 modules (18 files total):

  • vpc/ — 6 files
  • s3/ — 7 files
  • rds/ — 5 files

All validated ✅. Push all to GitHub?"

💡 Best Practices for Prompting​

Do: Be explicit about requirements​

✅ "Generate a heavily restricted AWS VPC module named 'core-network'.
    It must span 3 AZs. Include DB subnets that are completely isolated
    without outward internet access. Use a single NAT gateway to save money."

Do: Specify constraints and file expectations​

✅ "Create an S3 bucket module with KMS encryption. Make sure the KMS key ARN
    is exposed in outputs.tf and the bucket policy enforces SSL-only access."

Do: Reference specific paths for updates​

✅ "Connect to my repo talkops-ai/infra-modules. Look in /modules/networking/vpc.
    Add a NAT gateway per AZ instead of the current shared one."

Don't: Be vague (the agent will ask for clarification)​

⚠️ "Create a VPC module"
→ Agent will ask: Which region? How many AZs? Public/private subnets?
   NAT topology? CIDR range?

Don't: Mix infrastructure with non-infrastructure requests​

❌ "Write me a Python script that deploys a VPC"
→ Supervisor will redirect: this is a Terraform module generator, not a deployment tool