Multi-Environment GitOps Engine: Trunk-Based Delivery with AWS CDK
Building an automated Dev, Staging, and Production delivery pipeline with AWS CDK (TypeScript), automated synth testing, and manual approval gates.
1. Business Problem & Context
An enterprise software team had disparate infrastructure across environments. Production had manual console tweaks that did not exist in Staging, causing deployments that passed staging tests to immediately fail in production. Deployments required multi-hour maintenance windows on weekends.
2. Requirements & Constraints
- 100% Immutable Infrastructure as Code: Zero manual changes permitted in AWS Web Console.
- Automated Pre-Flight Verification: Static security analysis (cdk-nag), unit tests, and synthetic smoke tests before staging promotion.
- Trunk-Based Promotion: Single Git repository automatically promoting to Dev, Staging, and Production with approval checkpoints.
3. Architecture Overview & Data Flow
Interactive Architecture Diagram (Use controls to zoom & pan)
4. AWS Services Used & Rationales
AWS Services Architecture Rationale
Concrete reasons why these specific services were chosen over alternatives
| Service | Category | Architectural Rationale ("Why this service?") |
|---|---|---|
| AWS CDK (Cloud Development Kit) | DevOps | Enables infrastructure definition in TypeScript with reusable custom construct libraries. |
| AWS CodePipeline | DevOps | Manages cross-account IAM role assumptions to deploy CloudFormation stacks into isolated AWS accounts. |
| cdk-nag | Security | Validates CDK stacks against HIPAA, NIST, and AWS Well-Architected security best practices during compilation. |
5. Key Design Trade-offs
Architecture Decision & Trade-Off Matrix
Evaluating alternative approaches under real-world constraints
Manual AWS Management Console Changes
- + Fast initial experimentation
- − Impossible to audit
- − Severe configuration drift
- − Fatal production surprises
Type-Safe AWS CDK GitOps Engine (Chosen)
✓ Chosen Design- + Type safety with autocomplete
- + Automated cross-account rollouts
- + 100% reproducible environments
- − Requires TypeScript and CDK learning curve
6. Implementation Highlights
TypeScript CDK AWS CDK Multi-Stage Pipeline Definition
import * as cdk from 'aws-cdk-lib';
import { CodePipeline, CodePipelineSource, ShellStep } from 'aws-cdk-lib/pipelines';
export class DeliveryPipelineStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const pipeline = new CodePipeline(this, 'Pipeline', {
pipelineName: 'EnterpriseAppPipeline',
synth: new ShellStep('Synth', {
input: CodePipelineSource.gitHub('org/repo', 'main'),
commands: ['npm ci', 'npm run build', 'npx cdk synth'],
}),
});
pipeline.addStage(new ApplicationStage(this, 'Staging', { env: { account: '111111111111', region: 'us-east-1' } }));
pipeline.addStage(new ApplicationStage(this, 'Production', { env: { account: '222222222222', region: 'us-east-1' } }), {
pre: [new cdk.pipelines.ManualApprovalStep('PromoteToProd')],
});
}
}7. Results & Key Metrics
- Lead Time: Feature release time dropped from 5 days to 18 minutes.
- Production Incidents: 98% reduction in deployment-related configuration errors.
8. Key Architectural Takeaways
GitOps Rule: If an infrastructure resource is not defined in version control (IaC), it does not exist. All changes must flow through automated Git pipelines.
