acdl/modules/l1/rds/README.md

# rds — RDS database instance

> **Module kind:** primitive  |  **Version:** 1.0.0

An RDS database instance. Supports multiple database engines (postgres,
mysql, mariadb, sqlserver, oracle) via the `engine` input. The adapter
translates the engine-agnostic `aws:rds:instance` stack type to the
Terraform `aws_db_instance` resource.

## Resources

| Resource | Type | Purpose |
|----------|------|---------|
| `rds` | `aws_db_instance` | The RDS database instance |

## Inputs

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `engine` | string | yes | — | Database engine (postgres, mysql, mariadb, sqlserver-ex, sqlserver-web, sqlserver-se, oracle-se2) |
| `engine_version` | string | yes | — | Engine version (e.g. 16.4 for postgres, 8.4 for mysql) |
| `instance_class` | string | yes | `db.t3.micro` | RDS instance class (e.g. db.t3.micro, db.r6g.large) |
| `allocated_storage` | number | no | 20 | Allocated storage in GB |
| `db_name` | string | yes | — | The database name (some engines have restrictions) |
| `username` | string | yes | — | Master username |
| `multi_az` | boolean | no | false | Multi-AZ deployment |
| `storage_encrypted` | boolean | no | true | Enable storage encryption |
| `region` | string | yes | — | AWS region the RDS instance is created in |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `db_endpoint` | string | The RDS instance endpoint (host:port) |
| `db_arn` | arn | The RDS instance ARN |

## NFRs

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `backup_retention_period` | number | 7 | Backup retention period in days |
| `deletion_protection` | boolean | true | Enable deletion protection (default true for prod) |

## Usage

```json
{
  "id": "rds",
  "type": "aws:rds:instance",
  "module": "rds@1.0.0",
  "inputs": {
    "engine": "postgres",
    "engine_version": "16.4",
    "instance_class": "db.t3.micro",
    "allocated_storage": 20,
    "db_name": "acdl_db",
    "username": "acdl_admin",
    "multi_az": false,
    "storage_encrypted": true,
    "region": "us-east-1"
  },
  "nfrs": {
    "backup_retention_period": 7,
    "deletion_protection": true
  }
}
```

A concrete instance is at `instance.json` (used by the platform pipeline
as the regression baseline).

## Compliance extension points

- **KMS encryption** — add a customer-managed KMS key for storage
  encryption (`kms_key_id` argument) (SOC2 CC6.1,
  GDPR Art.32).
- **Automated backups** — the `backup_retention_period` NFR controls
  automated backup retention; extend with backup windows + copy tags to
  another region for DR (SOX ITGC, DORA operational resilience).
- **Audit logging via CloudTrail** — RDS does not emit CloudTrail events
  for data-plane access; add `aws_db_instance_automated_backups_replication`
  + CloudWatch Logs for database audit (SOX, SOC2 CC7.2).
- **IAM database authentication** — add `iam_database_authentication_enabled
  = true` so IAM users/roles can authenticate to the database without
  long-lived passwords (SOC2 CC6.1).
- **Read replicas** — add `aws_db_instance` with `replicate_source_db` for
  read scaling and DR failover (SOC2 CC9.1, DORA operational resilience).

## Examples

Validated example contracts are in [`examples/`](examples/). The platform-test
pipeline validates them against `schemas/contract.schema.json`.

### Simple

A minimal deployment:

[`examples/simple.yml`](examples/simple.yml)
```yaml
environment: dev
id: rds
infrastructure:
  rds:
    inputs:
      allocated_storage: 20
      db_name: my_app_db
      engine: postgres
      engine_version: '16.4'
      instance_class: db.t3.micro
      region: us-east-1
      username: db_admin
    version: 1.0.0
name: rds-instance
```

### Complex

A production deployment with optional inputs:

[`examples/complex.yml`](examples/complex.yml)
```yaml
environment: dev
id: rds
infrastructure:
  rds:
    inputs:
      allocated_storage: 100
      db_name: my_production_db
      engine: postgres
      engine_version: '16.4'
      instance_class: db.r6g.large
      multi_az: true
      region: us-east-1
      storage_encrypted: true
      username: db_admin
    version: 1.0.0
name: rds-instance
```

### Multi-engine variation

RDS supports multiple database engines. The `engine` input selects the engine;
the `engine_version` must match.

#### PostgreSQL

[`examples/simple.yml`](examples/simple.yml) — postgres 16.4

#### MySQL

[`examples/mysql.yml`](examples/mysql.yml) — mysql 8.4

```yaml
environment: dev
id: rds
infrastructure:
  rds:
    inputs:
      allocated_storage: 20
      db_name: my_mysql_db
      engine: mysql
      engine_version: '8.4'
      instance_class: db.t3.micro
      region: us-east-1
      username: db_admin
    version: 1.0.0
name: rds-instance
```

## Versioning

`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
require a new registry entry (immutable publication); old entries enter
a 12-month deprecation window.