Ralph Integration

---
name: ralph-integration
description: Autonomous AWS integration testing loop - deploys CDK infrastructure, runs integration tests, fixes issues, and cleans up
---

# Ralph Integration - AWS Infrastructure Testing Loop

Autonomous loop for deploying CDK infrastructure, running integration tests, auto-fixing issues, and cleaning up resources.

## Usage

```bash
/ralph-integration
/ralph-integration --max-iterations=15
/ralph-integration --profile=sandbox
/ralph-integration --promise=INTEGRATION_TESTS_PASS
/ralph-integration --skip-destroy  # Keep infra up for debugging

What This Does

The Flow:

1. SAM Local Sanity Check - Test Lambda packaging locally before CDK (fast gate)
2. CDK Synth - Validate CloudFormation templates
3. CDK Deploy - Deploy all stacks to AWS
4. Integration Tests - Run pytest -m integration
5. Auto-Fix - If failures, diagnose and fix automatically
6. CDK Destroy - Clean up all resources (guaranteed)

Loop continues until:

• ✅ All integration tests pass (success)
• ❌ Max iterations reached (failure)
• 🛑 User interrupts

Parameters

• --max-iterations=N - Maximum deployment attempts (default: 10)
• --promise=NAME - Success promise to output (default: INTEGRATION_TESTS_PASS)
• --skip-destroy - Keep infrastructure deployed (for debugging)
• --skip-sam-check - Skip SAM local sanity check (not recommended)
• --profile=PROFILE - AWS CLI profile to use (e.g., sandbox, production)
• --region=REGION - AWS region (default: us-east-1)
• --account-id=ID - AWS account ID (auto-detected from AWS CLI)

The Workflow

Phase 1: Pre-Flight Checks

Before starting the loop:

1. Check AWS Credentials

   # Export AWS_PROFILE if --profile was provided
   export AWS_PROFILE=sandbox  # if --profile=sandbox
   aws sts get-caller-identity
   

   • Verify AWS credentials are configured
   • Confirm account ID matches expected
   • Check region is set
   • Note: If --profile is specified, export AWS_PROFILE before all AWS/CDK commands

2. Check CDK Bootstrap

   cdk bootstrap --show-template
   

   • Verify account is bootstrapped for CDK
   • If not, run: cdk bootstrap aws://ACCOUNT/REGION

3. Check Python Dependencies

   source .venv/bin/activate
   pip list | grep -E "aws-cdk|boto3|pytest"
   

   • Verify CDK and test dependencies installed
   • Install if missing

4. Check Integration Test Markers

   pytest --markers | grep integration
   

   • Verify integration tests exist
   • Count total integration tests to run

Phase 1.5: SAM Local Sanity Check (Pre-Deploy Gate)

Purpose: Catch Lambda packaging/configuration issues in ~60 seconds before committing to expensive CDK deploys.

What it catches that unit tests don't:

• Handler entry point typos in template.yaml
• Missing dependencies in Lambda packages
• Environment variable misconfiguration
• Import errors in packaged artifacts

1. Start LocalStack

   docker compose -f infrastructure/sam-local/docker-compose.yml up -d
   # Wait for LocalStack to be healthy
   

2. Build SAM Application

   cd infrastructure/sam-local
   ./build.sh
   

3. Run SAM Local Tests

   cd ../..  # Back to project root
   pytest tests/integration/sam_local -m integration_sam -v --tb=short
   

4. Gate Decision

   • ✅ SAM tests pass → Proceed to Phase 2 (CDK Deploy)
   • ❌ SAM tests fail → EXIT EARLY
     • Don't waste time on CDK deploy
     • Fix Lambda issues first
     • Re-run /ralph-integration after fixing

Common Issues & Auto-Fixes:

Error	Auto-Fix
LocalStack not running	docker compose up -d
sam build failed	Check handler paths in template.yaml
ModuleNotFoundError	Fix requirements.txt or pyproject.toml
Handler not found	Fix handler entry point string
Connection refused (4566)	Wait for LocalStack, retry

Why This Gate Matters:

• SAM local test: ~60 seconds
• CDK deploy cycle: ~5-10 minutes
• If Lambdas are broken, CDK deploy will fail anyway
• Fail fast, fix fast

Phase 2: Deployment Loop

Iteration N (max: --max-iterations):

Step 1: CDK Synth

cd infrastructure/cdk
export AWS_PROFILE=sandbox  # if --profile was provided
source ../../.venv/bin/activate
cdk synth --all

Common Issues & Auto-Fixes:

Error	Auto-Fix
ModuleNotFoundError: aws_cdk	pip install aws-cdk-lib constructs
Resolution error	Check pyproject.toml dependencies
Invalid identifier	Fix Python syntax in stack files
Property validation failed	Fix CDK construct parameters

Step 2: CDK Deploy

export AWS_PROFILE=sandbox  # if --profile was provided
source ../../.venv/bin/activate
cdk deploy --all --require-approval never --outputs-file outputs.json

Common Issues & Auto-Fixes:

Error	Auto-Fix
Resource limit exceeded	Request limit increase or use different AZ
Stack already exists	Check if from previous run, destroy first
Insufficient permissions	Check IAM role has required permissions
DependencyViolation	Adjust depends_on in CDK code
CREATE_FAILED	Read CloudFormation events, fix root cause
ROLLBACK_COMPLETE	Destroy stack, fix issue, retry

Timeout Strategy:

• Wait up to 20 minutes for stack creation
• Poll every 30 seconds for statu