cdk-factory 0.7.31__tar.gz → 0.8.1__tar.gz

cdk_factory-0.8.1/.windsurfrules

@@ -0,0 +1,268 @@
+# CDK Factory - Development Rules & Guidelines
+
+## Project Type: AWS CDK Infrastructure Framework
+
+This is a reusable AWS CDK framework for building cloud infrastructure with standardized patterns.
+
+## Architecture Principles
+
+### Stack Separation Pattern (v2.0+)
+- **Lambda Stack**: Creates Lambda functions ONLY, exports ARNs to SSM
+- **API Gateway Stack**: Imports Lambda ARNs from SSM, creates API Gateway
+- **No direct cross-stack references**: Use SSM Parameter Store for loose coupling
+- **Reason**: Enables independent deployments, avoids circular dependencies, follows AWS best practices
+
+### SSM-Based Cross-Stack Communication
+```python
+# Lambda Stack Exports
+/{organization}/{environment}/lambda/{lambda-name}/arn
+/{organization}/{environment}/lambda/{lambda-name}/function-name
+
+# API Gateway Imports
+# Auto-discovery via lambda_name
+{"lambda_name": "my-function"}  # Finds /org/env/lambda/my-function/arn
+
+# Explicit path
+{"lambda_arn_ssm_path": "/custom/path/arn"}
+```
+
+## Code Style & Standards
+
+### Python Standards
+- **Style**: PEP 8 compliant, use `black` for formatting
+- **Type Hints**: Use type annotations for all function signatures
+- **Imports**: Absolute imports from `cdk_factory`, group stdlib/third-party/local
+- **Docstrings**: Google-style docstrings for all public methods
+
+### CDK Patterns
+- Use L2 constructs when available, fall back to L1 only when necessary
+- Always validate configurations before creating resources
+- Provide clear error messages with migration guidance for breaking changes
+- Export important resource identifiers to SSM when `ssm.enabled: true`
+
+## Testing Requirements
+
+### Test Structure
+- **Unit Tests**: `tests/unit/` - Test individual components
+- **Integration Tests**: `tests/integration/` - Test multi-stack scenarios
+- **Use Fixtures**: Pytest fixtures for common test setup
+- **No Mocking CDK**: Test real CDK synthesis, not mocked behavior
+
+### Running Tests
+```bash
+./run-tests.sh  # Creates fresh venv, runs all tests
+pytest tests/unit/test_lambda_stack.py -v  # Specific test file
+```
+
+### Test Patterns
+```python
+from aws_cdk.assertions import Template
+
+def test_stack_creation(app, deployment_config, workload_config):
+    stack = MyStack(app, "TestStack")
+    stack.build(config, deployment_config, workload_config)
+    
+    template = Template.from_stack(stack)
+    template.has_resource("AWS::Lambda::Function", {...})
+```
+
+## Configuration Patterns
+
+### Workload Config Structure
+```json
+{
+  "workload": {
+    "name": "my-app",
+    "devops": {"ci_cd": {"enabled": true}},
+    "stacks": [
+      {
+        "name": "lambda-stack",
+        "module": "lambda_stack",
+        "ssm": {
+          "enabled": true,
+          "organization": "my-app",
+          "environment": "prod"
+        },
+        "resources": [...]
+      },
+      {
+        "name": "api-stack",
+        "module": "api_gateway_stack",
+        "api_gateway": {
+          "ssm": {
+            "imports": {
+              "organization": "my-app",
+              "environment": "prod"
+            }
+          },
+          "routes": [
+            {"path": "/api", "lambda_name": "my-function"}
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Deprecation & Migration Strategy
+
+### When Deprecating Features
+1. **Detect deprecated patterns** in config validation
+2. **Raise helpful errors** with clear migration instructions
+3. **Reference documentation**: Point to `docs/MIGRATION_V2.md`
+4. **Show examples**: Include before/after config snippets
+5. **Update tests**: Expect `ValueError` for deprecated patterns
+
+### Error Message Format
+```python
+error_msg = """
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ 🚨 DEPRECATED CONFIGURATION DETECTED                                         ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+
+Your configuration uses deprecated pattern X, which caused issues Y.
+
+🔧 REQUIRED MIGRATION:
+1. Remove deprecated field
+2. Add new pattern
+3. Update pipeline order
+
+📚 MIGRATION GUIDE:
+https://github.com/org/cdk-factory/blob/main/docs/MIGRATION_V2.md
+
+💡 EXAMPLES:
+See: examples/separate-api-gateway/
+"""
+```
+
+## Documentation Standards
+
+### Required Documentation
+- **README.md**: Overview, quickstart, installation
+- **docs/MIGRATION_V2.md**: Breaking changes migration guide
+- **examples/**: Working examples for each major pattern
+- **Inline Comments**: Explain "why" not "what"
+
+### Example Structure
+```
+examples/
+  separate-api-gateway/
+    lambda-stack.json          # Lambda config
+    api-gateway-stack.json     # API Gateway config
+    README.md                  # Explanation
+```
+
+## Common Patterns
+
+### Lambda Function Creation
+```python
+# Always use utility for consistent patterns
+from cdk_factory.utilities.lambda_function_utilities import LambdaFunctionUtility
+
+lambda_fn = LambdaFunctionUtility.create_function(
+    self, config, deployment, workload
+)
+
+# Export to SSM if enabled
+if ssm_enabled:
+    self._export_lambda_to_ssm(lambda_fn, config)
+```
+
+### API Gateway Lambda Integration
+```python
+# Import from SSM (auto-discovery)
+lambda_arn = self._get_lambda_arn_from_ssm(lambda_name)
+
+# OR explicit path
+lambda_arn = self._get_lambda_arn_from_explicit_path(ssm_path)
+
+# OR legacy inline creation (backward compatibility)
+lambda_fn = self._create_inline_lambda(route_config)
+```
+
+## Error Handling
+
+### Validation Before Resource Creation
+```python
+def build(self, stack_config, deployment, workload):
+    # 1. Check for deprecated patterns
+    self._check_for_deprecated_config(stack_config)
+    
+    # 2. Validate required fields
+    self._validate_config(stack_config)
+    
+    # 3. Create resources
+    self._create_resources(stack_config)
+```
+
+### Clear Error Messages
+- Use emoji for visibility: 🚨 ❌ ✅ 💡 📚
+- Provide actionable solutions
+- Include relevant config snippet
+- Reference documentation
+
+## Git Workflow
+
+### Branch Strategy
+- `main`: Production-ready code
+- `develop`: Integration branch
+- `feature/*`: New features
+- `fix/*`: Bug fixes
+- `docs/*`: Documentation updates
+
+### Commit Messages
+```
+feat: Add SSM-based Lambda import for API Gateway
+fix: Correct deprecation detection for api_gateway config
+docs: Add migration guide for v2.0 breaking changes
+test: Update tests for separated stack pattern
+```
+
+## Dependencies
+
+### Production
+- `aws-cdk-lib`: AWS CDK v2
+- `constructs`: CDK constructs
+- Python 3.11+
+
+### Development
+- `pytest`: Testing framework
+- `black`: Code formatting
+- `mypy`: Type checking
+- `aws-cdk.assertions`: CDK testing utilities
+
+## Performance Considerations
+
+- Minimize SSM parameter lookups (cache when possible)
+- Use batch operations for multiple resources
+- Avoid synthesizing stacks in tests unless necessary
+- Keep Lambda packages small (use layers for common deps)
+
+## Security Best Practices
+
+- Never hardcode credentials or API keys
+- Use SSM Parameter Store for sensitive values
+- Apply least-privilege IAM policies
+- Enable encryption for S3 buckets and DynamoDB tables
+- Validate all user input before creating resources
+
+## Monitoring & Observability
+
+- Export important metrics to CloudWatch
+- Use Lambda Powertools for structured logging
+- Create CloudWatch alarms for critical resources
+- Tag all resources with environment, workload, and purpose
+
+## When to Create New Stack Types
+
+Create a new stack module when:
+1. Resource type requires unique deployment patterns
+2. Cross-stack dependencies are minimal
+3. Reusability across projects is high
+4. Testing can be isolated
+
+Don't create a new stack for:
+1. Single-purpose resources (use existing stack)
+2. Tightly coupled resources (keep in same stack)
+3. Rarely used patterns (extend existing stack)

cdk_factory-0.8.1/GEEK_CAFE_FIX.md

@@ -0,0 +1,241 @@
+# Fix for geek-cafe Cognito Error
+
+## The Problem
+
+```
+ValueError: User pool ID is required for API Gateway authorizer.
+```
+
+Your API Gateway stack can't find the Cognito User Pool because the new separated pattern requires **SSM imports** instead of environment variables.
+
+## Quick Fix
+
+In your `/Users/eric.wilson/Projects/geek-cafe/geek-cafe-web/geek-cafe-lambdas/cdk` config:
+
+### Option 1: Add SSM Import (Recommended)
+
+**api-gateway-stack.json:**
+```json
+{
+  "name": "geek-cafe-prod-api-gateway",
+  "module": "api_gateway_stack",
+  "api_gateway": {
+    "name": "geek-cafe-prod-api",
+    "api_type": "REST",
+    "stage_name": "prod",
+    "ssm": {
+      "enabled": true,
+      "auto_export": true,
+      "workload": "geek-cafe",
+      "environment": "prod",
+      "imports": {
+        "workload": "geek-cafe",
+        "environment": "prod",
+        "user_pool_arn": "auto"  // ✅ ADD THIS - imports from Cognito stack
+      }
+    },
+    "cognito_authorizer": {
+      "authorizer_name": "geek-cafe-cognito-authorizer"
+    },
+    "routes": [...]
+  }
+}
+```
+
+This assumes your Cognito stack is configured to export:
+```json
+{
+  "name": "geek-cafe-prod-cognito",
+  "module": "cognito_stack",
+  "ssm": {
+    "enabled": true,
+    "auto_export": true,  // ✅ Must be enabled
+    "workload": "geek-cafe",
+    "environment": "prod"
+  }
+}
+```
+
+### Option 2: Use Explicit SSM Path
+
+If auto-discovery doesn't work, find the exact SSM parameter:
+
+```bash
+# Find the parameter
+aws ssm get-parameters-by-path --path "/geek-cafe/prod/cognito" --recursive
+```
+
+Then use the explicit path:
+```json
+{
+  "api_gateway": {
+    "ssm": {
+      "imports": {
+        "user_pool_arn": "/geek-cafe/prod/cognito/user-pool/user-pool-arn"
+      }
+    }
+  }
+}
+```
+
+### Option 3: Direct ARN (Quick Temporary Fix)
+
+If you just need to deploy NOW and fix properly later:
+
+```json
+{
+  "api_gateway": {
+    "cognito_authorizer": {
+      "authorizer_name": "geek-cafe-authorizer",
+      "user_pool_arn": "arn:aws:cognito-idp:us-east-1:ACCOUNT_ID:userpool/us-east-1_XXXXX"
+    }
+  }
+}
+```
+
+Get the ARN from AWS Console → Cognito → User Pools → geek-cafe-prod → ARN
+
+## Deployment Order
+
+With the new pattern, deploy in this order:
+
+```bash
+# 1. Deploy Cognito (if separate stack)
+cdk deploy geek-cafe-prod-cognito
+
+# 2. Deploy Lambdas
+cdk deploy geek-cafe-prod-lambdas
+
+# 3. Deploy API Gateway (imports from both above)
+cdk deploy geek-cafe-prod-api-gateway
+```
+
+Or set up a pipeline with stages:
+```json
+{
+  "pipeline": {
+    "stages": [
+      {"name": "infrastructure", "stacks": ["cognito-stack"]},
+      {"name": "lambdas", "stacks": ["lambda-stack"]},
+      {"name": "api-gateway", "stacks": ["api-gateway-stack"]}
+    ]
+  }
+}
+```
+
+## Verify SSM Parameters Exist
+
+```bash
+# Check what Cognito exported
+aws ssm get-parameter --name "/geek-cafe/prod/cognito/user-pool/user-pool-arn"
+
+# Check what Lambda exported
+aws ssm get-parameters-by-path --path "/geek-cafe/prod/lambda" --recursive
+
+# Check what API Gateway exported
+aws ssm get-parameters-by-path --path "/geek-cafe/prod/api-gateway" --recursive
+```
+
+## Complete Example Config
+
+**cognito-stack.json:**
+```json
+{
+  "name": "geek-cafe-prod-cognito",
+  "module": "cognito_stack",
+  "ssm": {
+    "enabled": true,
+    "auto_export": true,
+    "workload": "geek-cafe",
+    "environment": "prod"
+  },
+  "cognito": {
+    "user_pool_name": "geek-cafe-prod",
+    "exists": false
+  }
+}
+```
+
+**lambda-stack.json:**
+```json
+{
+  "name": "geek-cafe-prod-lambdas",
+  "module": "lambda_stack",
+  "ssm": {
+    "enabled": true,
+    "workload": "geek-cafe",
+    "environment": "prod"
+  },
+  "resources": [
+    {
+      "name": "geek-cafe-prod-get-cafes",
+      "src": "./src/handlers/cafes",
+      "handler": "get_cafes.lambda_handler"
+    }
+  ]
+}
+```
+
+**api-gateway-stack.json:**
+```json
+{
+  "name": "geek-cafe-prod-api-gateway",
+  "module": "api_gateway_stack",
+  "api_gateway": {
+    "name": "geek-cafe-prod-api",
+    "api_type": "REST",
+    "stage_name": "prod",
+    "ssm": {
+      "enabled": true,
+      "auto_export": true,
+      "workload": "geek-cafe",
+      "environment": "prod",
+      "imports": {
+        "workload": "geek-cafe",
+        "environment": "prod",
+        "user_pool_arn": "auto"  // ✅ This is the key fix
+      }
+    },
+    "cognito_authorizer": {
+      "authorizer_name": "geek-cafe-cognito-authorizer"
+    },
+    "routes": [
+      {
+        "path": "/cafes",
+        "method": "GET",
+        "lambda_name": "geek-cafe-prod-get-cafes",
+        "authorization_type": "COGNITO_USER_POOLS"
+      }
+    ]
+  }
+}
+```
+
+## Summary of Changes
+
+| Old Pattern (Combined) | New Pattern (Separated) |
+|------------------------|-------------------------|
+| `COGNITO_USER_POOL_ID` env var | SSM import with `user_pool_arn: "auto"` |
+| Single stack with Lambda + API | Three stacks: Cognito → Lambda → API Gateway |
+| Environment vars in CI/CD | Config-driven SSM parameters |
+| `"exports": {"enabled": true}` ❌ | `"auto_export": true` ✅ |
+
+## If Still Having Issues
+
+1. **Check CDK Factory version:**
+   ```bash
+   pip show cdk-factory
+   # Should be v0.8.0 or higher
+   ```
+
+2. **Enable debug logging:**
+   ```bash
+   export LOG_LEVEL=DEBUG
+   cdk deploy
+   ```
+
+3. **Verify workload/environment match** in all three stacks
+
+4. **Check SSM permissions** in your deployment role
+
+5. **Use explicit path** as fallback if auto-discovery fails

{cdk_factory-0.7.31 → cdk_factory-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdk_factory
-Version: 0.7.31
+Version: 0.8.1
 Summary: CDK Factory. A QuickStarter and best practices setup for CDK projects
 Author-email: Eric Wilson <eric.wilson@geekcafe.com>
 License: MIT License

cdk_factory-0.8.1/examples/separate-api-gateway/README.md

@@ -0,0 +1,94 @@
+# Example: Separate Lambda and API Gateway Stacks
+
+This example demonstrates the **recommended pattern** for deploying Lambda functions and API Gateway separately using CDK-Factory v2.0+.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Pipeline Stage 1                         │
+│                   Deploy Lambda Stacks                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Lambda Stack                                               │
+│  ┌───────────────────────────────────────────────┐         │
+│  │  Create Lambda Functions                      │         │
+│  │  ├─ Health Check Lambda                       │         │
+│  │  ├─ User API Lambda                           │         │
+│  │  └─ Admin API Lambda                          │         │
+│  │                                                │         │
+│  │  Export to SSM Parameter Store:               │         │
+│  │  ├─ /org/env/lambda/health/arn                │         │
+│  │  ├─ /org/env/lambda/user-api/arn              │         │
+│  │  └─ /org/env/lambda/admin-api/arn             │         │
+│  └───────────────────────────────────────────────┘         │
+│                          │                                  │
+│                          │ SSM Parameters                   │
+│                          ▼                                  │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│                    Pipeline Stage 2                         │
+│                Deploy API Gateway Stack                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  API Gateway Stack                                          │
+│  ┌───────────────────────────────────────────────┐         │
+│  │  Import Lambda ARNs from SSM                  │         │
+│  │  ├─ GET  /health        → health Lambda       │         │
+│  │  ├─ GET  /users         → user-api Lambda     │         │
+│  │  ├─ POST /users         → user-api Lambda     │         │
+│  │  └─ GET  /admin/stats   → admin-api Lambda    │         │
+│  │                                                │         │
+│  │  Create API Gateway                            │         │
+│  │  ├─ Stage: prod                                │         │
+│  │  ├─ CORS Configuration                         │         │
+│  │  ├─ Cognito Authorizer (optional)             │         │
+│  │  └─ Custom Domain (optional)                  │         │
+│  └───────────────────────────────────────────────┘         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Files
+
+- `lambda-stack.json` - Lambda function definitions
+- `api-gateway-stack.json` - API Gateway with route configurations
+- `config.json` - Pipeline configuration
+
+## Usage
+
+1. **Deploy Lambda Stack First:**
+   ```bash
+   cdk deploy MyApp-Lambda-Stack
+   ```
+
+2. **Verify SSM Parameters:**
+   ```bash
+   aws ssm get-parameter --name /my-app/prod/lambda/health-check/arn
+   ```
+
+3. **Deploy API Gateway Stack:**
+   ```bash
+   cdk deploy MyApp-API-Gateway-Stack
+   ```
+
+## Key Features
+
+✅ **SSM-based Cross-Stack Communication** - No CloudFormation exports
+✅ **Independent Lifecycles** - Update Lambdas without touching API Gateway
+✅ **Auto-Discovery** - Reference Lambdas by name, ARN auto-resolved
+✅ **Multiple Environments** - Easy to deploy dev/staging/prod
+✅ **Security Best Practices** - Cognito integration, CORS, authorization
+
+## Testing
+
+Test Lambda independently:
+```bash
+aws lambda invoke --function-name my-lambda output.json
+```
+
+Test API Gateway:
+```bash
+curl https://api-id.execute-api.region.amazonaws.com/prod/health
+```

cdk_factory-0.8.1/examples/separate-api-gateway/api-gateway-stack.json

@@ -0,0 +1,81 @@
+{
+  "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-api-gateway",
+  "module": "api_gateway_stack",
+  "enabled": true,
+  "api_gateway": {
+    "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-api",
+    "description": "API Gateway for {{WORKLOAD_NAME}} application",
+    "api_type": "REST",
+    "stage_name": "prod",
+    "ssm": {
+      "enabled": true,
+      "auto_export": true,
+      "workload": "{{WORKLOAD_NAME}}",
+      "environment": "{{ENVIRONMENT}}",
+      "imports": {
+        "workload": "{{WORKLOAD_NAME}}",
+        "environment": "{{ENVIRONMENT}}"
+      }
+    },
+    "deploy_options": {
+      "data_trace_enabled": false,
+      "metrics_enabled": true,
+      "tracing_enabled": true,
+      "throttling_rate_limit": 1000,
+      "throttling_burst_limit": 2000
+    },
+    "cognito_authorizer": {
+      "enabled": false,
+      "user_pool_arn": "{{COGNITO_USER_POOL_ARN}}"
+    },
+    "routes": [
+      {
+        "path": "/health",
+        "method": "GET",
+        "lambda_name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-health-check",
+        "authorization_type": "NONE",
+        "allow_public_override": true,
+        "cors": {
+          "origins": ["*"],
+          "methods": ["GET", "OPTIONS"],
+          "headers": ["Content-Type", "Authorization"]
+        }
+      },
+      {
+        "path": "/users",
+        "method": "GET",
+        "lambda_name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-user-api",
+        "authorization_type": "NONE",
+        "allow_public_override": true,
+        "cors": {
+          "origins": ["*"],
+          "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+          "headers": ["Content-Type", "Authorization"]
+        }
+      },
+      {
+        "path": "/users",
+        "method": "POST",
+        "lambda_name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-user-api",
+        "authorization_type": "NONE",
+        "allow_public_override": true,
+        "cors": {
+          "origins": ["*"],
+          "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+          "headers": ["Content-Type", "Authorization"]
+        }
+      },
+      {
+        "path": "/admin/stats",
+        "method": "GET",
+        "lambda_name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-admin-api",
+        "authorization_type": "COGNITO",
+        "cors": {
+          "origins": ["https://admin.example.com"],
+          "methods": ["GET", "OPTIONS"],
+          "headers": ["Content-Type", "Authorization"]
+        }
+      }
+    ]
+  }
+}