Ryan Wilson
68684df471
Jenkins shared library and CDK constructs for AWS infrastructure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
109 lines
4.1 KiB
Plaintext
109 lines
4.1 KiB
Plaintext
# Spicy Automation
|
|
|
|
## Project Overview
|
|
|
|
AWS CDK infrastructure and Jenkins shared library for deploying VPCs, ECS clusters, and ECS services on AWS. Provides type-safe TypeScript CDK constructs and Jenkins pipeline functions for automated infrastructure deployment with blue/green deployments, mixed capacity strategies (EC2 + Fargate), and persistent ALB patterns.
|
|
|
|
## Architecture Principles
|
|
|
|
### Language & Stack
|
|
|
|
- **TypeScript** for CDK constructs (AWS CDK v2)
|
|
- **Groovy** for Jenkins shared library pipelines
|
|
- **AWS CDK** for infrastructure as code
|
|
- **Jest** for testing
|
|
- **pnpm** for package management
|
|
|
|
### Code Organization
|
|
|
|
```text
|
|
spicy-automation/
|
|
├── bin/spicy-cdk.ts # CDK app entry point
|
|
├── lib/
|
|
│ ├── constructs/ # Reusable CDK constructs
|
|
│ │ ├── spicy-vpc.ts # VPC construct
|
|
│ │ ├── spicy-ecs-cluster.ts # ECS cluster construct
|
|
│ │ ├── spicy-ecs-service.ts # ECS service construct
|
|
│ │ └── spicy-alb.ts # Persistent ALB construct
|
|
│ └── stacks/ # CDK stacks (fromContext factories)
|
|
│ ├── spicy-vpc-stack.ts
|
|
│ ├── spicy-ecs-cluster-stack.ts
|
|
│ ├── spicy-ecs-service-stack.ts
|
|
│ └── spicy-alb-stack.ts
|
|
├── vars/ # Jenkins shared library
|
|
│ ├── spicyVPC.groovy # VPC pipeline
|
|
│ ├── spicyECSCluster.groovy # ECS cluster pipeline
|
|
│ ├── spicyECSService.groovy # ECS service pipeline
|
|
│ ├── spicyRollback.groovy # Blue/green rollback
|
|
│ ├── cdkUtils.groovy # CDK command utilities
|
|
│ ├── dockerUtils.groovy # Docker/Nexus utilities
|
|
│ ├── gitUtils.groovy # Git utilities
|
|
│ └── accounts.groovy # Account configurations
|
|
├── docs/ # Documentation
|
|
├── test/ # Jest tests
|
|
└── Dockerfile # Jenkins agent image
|
|
```
|
|
|
|
**Directory Rules:**
|
|
|
|
- `lib/constructs/` - Reusable CDK constructs (no stack logic)
|
|
- `lib/stacks/` - Stack factories that read from CDK context
|
|
- `vars/` - Jenkins shared library functions (Groovy)
|
|
- `docs/` - User-facing documentation (keep minimal, avoid duplication)
|
|
- `test/` - Unit tests for constructs
|
|
|
|
## Coding Standards
|
|
|
|
### TypeScript Conventions
|
|
|
|
- Use interfaces for all public APIs
|
|
- Document exported functions and types with JSDoc
|
|
- Prefer readonly properties where possible
|
|
- Use strict TypeScript settings
|
|
- One construct per file, named exports only
|
|
- Use CDK best practices (overrideLogicalId for stability)
|
|
|
|
### Error Handling
|
|
|
|
- Validate required parameters early in constructors
|
|
- Throw descriptive errors with usage examples
|
|
- Use CDK's built-in validation where possible
|
|
- Don't swallow errors silently
|
|
|
|
### Concurrency
|
|
|
|
- CDK constructs are synchronous (no async/await needed)
|
|
- Jenkins pipelines handle concurrency at the stage level
|
|
- No shared mutable state in constructs
|
|
|
|
## Documentation
|
|
|
|
- Keep README.md updated
|
|
- Code comments for complex logic
|
|
|
|
## Minimal Viable Product (MVP)
|
|
|
|
1. **Keep it minimal**: Code should be the smallest implementation that works correctly
|
|
2. **Avoid over-engineering**: Don't add features "just in case" - add them when needed
|
|
3. **Simple solutions first**: Prefer simple, straightforward code over complex abstractions
|
|
4. **One thing at a time**: Each function/type should do one thing well
|
|
|
|
## When Making Changes
|
|
|
|
1. **Write tests first**: Define all expectations and error cases in tests BEFORE any implementation
|
|
2. **Mock third-party dependencies**: Use mocks for external libraries, don't test their internals
|
|
3. **Implement minimal code**: Write only what's needed to pass the tests
|
|
4. **Follow patterns**: Use existing code patterns
|
|
5. **Keep it simple**: Prefer simple, readable code over clever solutions
|
|
|
|
## Questions to Ask
|
|
|
|
If unsure about implementation:
|
|
|
|
1. Does it follow existing patterns?
|
|
2. Is it testable?
|
|
3. Does it maintain thread safety?
|
|
4. Is it documented?
|
|
5. Does it validate inputs?
|
|
6. Does it handle errors properly?
|