Copilot instructions

1---
2applyTo: "**/deploy/**, **/scripts/deploy*, **/appspec.yml, **/appspec.yaml, **/scripts/smoke*, **/deployment/**"
3description: "Deployment standards: blue/green and canary patterns, pre-deploy checklist, rollback procedures, AWS CDK/SAM deploy commands, and local Docker Compose startup."
4---
5 
6## Context
7 
8This instruction file applies to deployment scripts, appspec files, and deployment configuration. All deployments must be observable, reversible, and gated by a pre-deploy checklist. "Works in dev" is not a deployment strategy.
9 
10---
11 
12## Deployment Patterns
13 
14### Blue/Green Deployment (Production Default)
15 
16- Route 100% traffic to Green (current) while Blue (new) is provisioned
17- Smoke test Blue fully before any traffic shift
18- Shift 100% traffic to Blue atomically
19- Keep Green available for 30 minutes for instant rollback
20- AWS services: CodeDeploy `AllAtOnce` on ECS with `BlueGreenDeploymentConfig`
21 
22### Canary Deployment (Progressive Rollout)
23 
24- Shift traffic incrementally: 10% → 25% → 50% → 100%
25- Monitor error rate and latency at each stage before proceeding
26- Automatic rollback if error rate exceeds threshold at any stage
27- AWS services: CodeDeploy Linear/Canary deployment configuration
28 
29### Rolling Update (Non-Production)
30 
31- Replace instances/tasks one at a time while maintaining minimum healthy percent
32- ECS: `minimumHealthyPercent: 100`, `maximumPercent: 200`
33 
34---
35 
36## Pre-Deploy Checklist
37 
38This checklist must be completed before any production deployment:
39 
40- [ ] `cdk diff` / `terraform plan` reviewed and approved by two engineers
41- [ ] Database migration scripts are idempotent and tested in staging
42- [ ] Secrets exist in Secrets Manager for target environment
43- [ ] CloudWatch alarms are armed and baseline metrics recorded
44- [ ] Rollback procedure tested and documented in runbook
45- [ ] On-call engineer notified and standing by
46- [ ] Deployment window agreed (prefer off-peak hours for P1 risk changes)
47- [ ] Customer communication drafted (if user-visible change)
48- [ ] Post-deploy smoke test script prepared
49 
50---
51 
52## AWS CDK Deploy Commands
53 
54```bash
55# Mandatory: review changes before deploy
56npx cdk diff \
57  --profile ${AWS_PROFILE} \
58  --context env=${ENV}
59 
60# Deploy a specific stack
61npx cdk deploy ${STACK_NAME} \
62  --profile ${AWS_PROFILE} \
63  --context env=${ENV} \
64  --require-approval never \
65  --outputs-file cdk-outputs.json
66 
67# Destroy (non-production only — CAUTION)
68npx cdk destroy ${STACK_NAME} \
69  --profile ${AWS_PROFILE} \
70  --context env=${ENV} \
71  --force
72```
73 
74## SAM Deploy Commands
75 
76```bash
77sam build
78
79sam deploy \
80  --stack-name ${STACK_NAME} \
81  --s3-bucket ${DEPLOY_BUCKET} \
82  --parameter-overrides Env=${ENV} \
83  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
84  --no-confirm-changeset \
85  --region ${AWS_REGION}
86```
87 
88---
89 
90## Smoke Test Template
91 
92```bash
93#!/usr/bin/env bash
94set -euo pipefail
95 
96BASE_URL="${BASE_URL:-http://localhost:8080}"
97PASS=0; FAIL=0
98 
99check() {
100  local name=$1; local cmd=$2
101  if eval "$cmd" > /dev/null 2>&1; then
102    echo "✅ PASS: $name"; ((PASS++))
103  else
104    echo "❌ FAIL: $name"; ((FAIL++))
105  fi
106}
107
108check "Health endpoint UP"      "curl -sf ${BASE_URL}/actuator/health | grep -q '\"status\":\"UP\"'"
109check "API v1 ping"             "curl -sf ${BASE_URL}/api/v1/ping | grep -q 'pong'"
110check "No 500s in CloudWatch"   "aws cloudwatch get-metric-statistics --namespace AWS/ApplicationELB \
111  --metric-name HTTPCode_Target_5XX_Count --statistics Sum --period 300 \
112  --start-time $(date -u -v-5M +%FT%TZ) --end-time $(date -u +%FT%TZ) \
113  --dimensions Name=LoadBalancer,Value=${ALB_NAME} | jq '.Datapoints[0].Sum // 0 | . == 0'"
114
115echo ""
116echo "Results: ${PASS} passed, ${FAIL} failed"
117[[ $FAIL -eq 0 ]] || exit 1
118```
119 
120---
121 
122## Rollback Runbook Template
123 
124```markdown
125## Rollback Runbook: {Service Name}
126 
127### Trigger Conditions
128Initiate rollback if any of the following occur within 10 minutes of deployment:
129- Error rate > 1% (production baseline)
130- p99 latency > 2x baseline
131- Any smoke test failure
132 
133### Rollback Steps
134 
135#### ECS (CodeDeploy)
136```bash
137# Identify the failed deployment
138aws deploy list-deployments --application-name ${APP_NAME} --deployment-group-name ${GROUP_NAME}
139 
140# Rollback to previous task definition
141aws ecs update-service \
142  --cluster ${CLUSTER} \
143  --service ${SERVICE} \
144  --task-definition ${PREVIOUS_TASK_DEF_ARN} \
145  --force-new-deployment
146```
147 
148#### CDK Stack
149```bash
150# Redeploy previous version from git tag
151git checkout ${PREVIOUS_TAG}
152npx cdk deploy ${STACK_NAME} --context env=prod --require-approval never
153```
154 
155### Verification
156- Run smoke tests against rollback deployment
157- Confirm error rate returns to baseline in CloudWatch
158- Post rollback completion in #incidents channel
159```
160 
161---
162 
163## Anti-Patterns
164 
165- ❌ Deploying directly to production without staging validation
166- ❌ Skipping `cdk diff` / `terraform plan` before apply
167- ❌ Deploying during peak business hours without business sign-off
168- ❌ No rollback plan for a production deployment
169- ❌ Long-lived feature flags instead of clean deployments
170 
171```