Copilot instructions

1---
2applyTo: "**/cdk.json, **/cdk/**/*.ts, **/*.tf, **/*.tfvars, **/terraform/**/*.tf, **/infra/**/*.ts, **/infra/**/*.tf"
3description: "IaC standards for AWS CDK (TypeScript) and Terraform HCL: module structure, remote state, least-privilege, naming conventions, and environment management."
4---
5 
6## Context
7 
8This instruction file applies to all Infrastructure as Code: AWS CDK TypeScript stacks and Terraform HCL modules. IaC is production code and must meet the same quality bar: code review, testing, version control, and documentation.
9 
10---
11 
12## CDK TypeScript Standards
13 
14### Project Structure
15 
16```
17infrastructure/
18├── bin/
19│   └── app.ts                  # CDK app entry point
20├── lib/
21│   ├── stacks/
22│   │   ├── network-stack.ts    # VPC, subnets, security groups
23│   │   ├── database-stack.ts   # RDS, ElastiCache
24│   │   └── app-stack.ts        # ECS, ALB, IAM
25│   └── constructs/
26│       └── fargate-service.ts  # Reusable custom construct
27├── test/
28│   └── stacks/
29│       └── app-stack.test.ts   # CDK assertions tests
30├── cdk.json
31└── tsconfig.json
32```
33 
34### CDK Code Rules
35 
36- **L2/L3 constructs preferred** over L1 (`CfnXxx`) — less code, more defaults, fewer mistakes
37- **Stack props typed** — every stack has a typed `interface XxxStackProps extends cdk.StackProps`
38- **No hardcoded account/region** — use `this.account`, `this.region`, or context
39- **Secrets via `SecretValue.ssmSecure()` or `Secret.fromSecretNameV2()`**
40- **`RemovalPolicy.RETAIN`** for production databases, S3 buckets with data, DynamoDB tables
41- **CDK Aspects** for organisation-wide cross-cutting concerns (tagging, compliance)
42- **CDK Assertions** (`@aws-cdk/assertions`) for unit tests on stack templates
43 
44```typescript
45// CORRECT: Environment-aware removal policy
46const isProd = props.env === 'prod';
47new dynamodb.Table(this, 'OrdersTable', {
48  removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
49});
50```
51 
52### CDK Testing
53 
54CDK stacks must have unit tests using `@aws-cdk/assertions`:
55 
56```typescript
57import { Template } from 'aws-cdk-lib/assertions';
58 
59test('ECS service has correct CPU and memory', () => {
60  const template = Template.fromStack(stack);
61  template.hasResourceProperties('AWS::ECS::TaskDefinition', {
62    Cpu: '512',
63    Memory: '1024',
64  });
65});
66```
67 
68---
69 
70## Terraform Standards
71 
72### Module Structure
73 
74```
75modules/
76└── ecs-fargate-service/
77    ├── main.tf           # Resources
78    ├── variables.tf      # Input variables with descriptions and types
79    ├── outputs.tf        # Output values
80    ├── versions.tf       # Required providers and versions
81    └── README.md         # Module documentation
82```
83 
84### Remote State (Required)
85 
86```hcl
87terraform {
88  backend "s3" {
89    bucket         = "{project}-terraform-state-{account_id}"
90    key            = "{env}/{component}/terraform.tfstate"
91    region         = "eu-west-1"
92    encrypt        = true
93    dynamodb_table = "{project}-terraform-locks"
94  }
95}
96```
97 
98### Provider Configuration
99 
100```hcl
101terraform {
102  required_version = ">= 1.6.0"
103  required_providers {
104    aws = {
105      source  = "hashicorp/aws"
106      version = "~> 5.0"
107    }
108  }
109}
110 
111provider "aws" {
112  region = var.aws_region
113  default_tags {
114    tags = {
115      Project     = var.project_name
116      Environment = var.environment
117      ManagedBy   = "Terraform"
118      Owner       = var.team_name
119      CostCentre  = var.cost_centre
120    }
121  }
122}
123```
124 
125### Variables
126 
127```hcl
128variable "environment" {
129  description = "Deployment environment: dev, staging, or prod"
130  type        = string
131  validation {
132    condition     = contains(["dev", "staging", "prod"], var.environment)
133    error_message = "Environment must be dev, staging, or prod."
134  }
135}
136```
137 
138---
139 
140## Naming Conventions
141 
142| Resource | Convention | Example |
143|----------|-----------|---------|
144| S3 bucket | `{project}-{env}-{purpose}` | `smart-retail-prod-assets` |
145| ECR repository | `{project}/{service}` | `smart-retail/order-service` |
146| ECS cluster | `{project}-{env}` | `smart-retail-prod` |
147| Lambda function | `{project}-{env}-{function}` | `smart-retail-prod-order-processor` |
148| IAM role | `{project}-{env}-{service}-role` | `smart-retail-prod-order-service-role` |
149 
150---
151 
152## Anti-Patterns to Avoid
153 
154- ❌ Hardcoded account IDs, region names, or ARNs
155- ❌ Secrets in plain text in variables or environment blocks
156- ❌ `terraform apply` without `terraform plan` review
157- ❌ Shared state file across environments
158- ❌ `force_destroy = true` on production S3 buckets
159- ❌ Unversioned provider dependencies (`version = "*"`)
160