cdk-factory 0.7.30__tar.gz → 0.8.0__tar.gz

cdk_factory-0.8.0/.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.7.30 → cdk_factory-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdk_factory
-Version: 0.7.30
+Version: 0.8.0
 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.0/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.0/examples/separate-api-gateway/api-gateway-stack.json

@@ -0,0 +1,83 @@
+{
+  "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,
+      "workload": "{{WORKLOAD_NAME}}",
+      "environment": "{{ENVIRONMENT}}",
+      "exports": {
+        "enabled": true
+      },
+      "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"]
+        }
+      }
+    ]
+  }
+}

cdk_factory-0.8.0/examples/separate-api-gateway/config.json

@@ -0,0 +1,74 @@
+{
+  "cdk": {
+    "parameters": [
+      {
+        "placeholder": "{{ENVIRONMENT}}",
+        "env_var_name": "ENVIRONMENT",
+        "cdk_parameter_name": "Environment"
+      },
+      {
+        "placeholder": "{{WORKLOAD_NAME}}",
+        "env_var_name": "WORKLOAD_NAME",
+        "cdk_parameter_name": "WorkloadName"
+      },
+      {
+        "placeholder": "{{AWS_ACCOUNT}}",
+        "env_var_name": "AWS_ACCOUNT",
+        "cdk_parameter_name": "AccountNumber"
+      },
+      {
+        "placeholder": "{{AWS_REGION}}",
+        "env_var_name": "AWS_REGION",
+        "cdk_parameter_name": "AccountRegion"
+      },
+      {
+        "placeholder": "{{DYNAMODB_TABLE_NAME}}",
+        "env_var_name": "DYNAMODB_TABLE_NAME",
+        "cdk_parameter_name": "DynamoDbTableName"
+      },
+      {
+        "placeholder": "{{COGNITO_USER_POOL_ARN}}",
+        "env_var_name": "COGNITO_USER_POOL_ARN",
+        "cdk_parameter_name": "CognitoUserPoolArn"
+      }
+    ]
+  },
+  "workload": {
+    "name": "{{WORKLOAD_NAME}}",
+    "description": "Example application with separate Lambda and API Gateway stacks",
+    "deployments": [
+      {
+        "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-pipeline",
+        "environment": "{{ENVIRONMENT}}",
+        "account": "{{AWS_ACCOUNT}}",
+        "region": "{{AWS_REGION}}",
+        "mode": "pipeline",
+        "pipeline": {
+          "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-pipeline",
+          "enabled": true,
+          "stages": [
+            {
+              "name": "deploy-lambdas",
+              "description": "Deploy Lambda functions and export ARNs to SSM",
+              "stacks": [
+                {
+                  "__inherits__": "./lambda-stack.json"
+                }
+              ]
+            },
+            {
+              "name": "deploy-api-gateway",
+              "description": "Deploy API Gateway and wire Lambda integrations",
+              "stacks": [
+                {
+                  "__inherits__": "./api-gateway-stack.json"
+                }
+              ]
+            }
+          ]
+        },
+        "enabled": true
+      }
+    ]
+  }
+}

cdk_factory-0.8.0/examples/separate-api-gateway/lambda-stack.json

@@ -0,0 +1,62 @@
+{
+  "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-lambdas",
+  "module": "lambda_stack",
+  "enabled": true,
+  "ssm": {
+    "enabled": true,
+    "workload": "{{WORKLOAD_NAME}}",
+    "environment": "{{ENVIRONMENT}}"
+  },
+  "resources": [
+    {
+      "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-health-check",
+      "src": "./src/handlers/health",
+      "handler": "app.lambda_handler",
+      "description": "Health check endpoint",
+      "runtime": "python3.12",
+      "timeout": 10,
+      "memory_size": 128,
+      "environment_variables": {
+        "LOG_LEVEL": "INFO",
+        "ENVIRONMENT": "{{ENVIRONMENT}}"
+      }
+    },
+    {
+      "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-user-api",
+      "src": "./src/handlers/user",
+      "handler": "app.lambda_handler",
+      "description": "User API operations",
+      "runtime": "python3.12",
+      "timeout": 30,
+      "memory_size": 512,
+      "environment_variables": {
+        "LOG_LEVEL": "INFO",
+        "ENVIRONMENT": "{{ENVIRONMENT}}",
+        "TABLE_NAME": "{{DYNAMODB_TABLE_NAME}}"
+      },
+      "permissions": [
+        "dynamodb_read",
+        "dynamodb_write"
+      ]
+    },
+    {
+      "name": "{{WORKLOAD_NAME}}-{{ENVIRONMENT}}-admin-api",
+      "src": "./src/handlers/admin",
+      "handler": "app.lambda_handler",
+      "description": "Admin API operations",
+      "runtime": "python3.12",
+      "timeout": 30,
+      "memory_size": 512,
+      "environment_variables": {
+        "LOG_LEVEL": "INFO",
+        "ENVIRONMENT": "{{ENVIRONMENT}}",
+        "TABLE_NAME": "{{DYNAMODB_TABLE_NAME}}"
+      },
+      "permissions": [
+        "dynamodb_read",
+        "dynamodb_write",
+        "s3_read"
+      ]
+    }
+  ]
+}

{cdk_factory-0.7.30 → cdk_factory-0.8.0}/pyproject.toml

@@ -33,7 +33,7 @@ markers = [
 [project]
 
 name = "cdk_factory"
-version = "0.7.30"
+version = "0.8.0"
 authors = [
   { name="Eric Wilson", email="eric.wilson@geekcafe.com" }
 ]