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 substrate-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, HIPAA §164.312(a)(2)(iv),
  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, HIPAA
  §164.312(b)).
- **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, HIPAA §164.308(a)(4)).
- **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.yaml`](examples/simple.yaml)
```yaml
# Simple RDS postgres instance
uses: acdl/pipelines/deploy.yaml@v1.6
module: rds
environment: dev
inputs:
  engine: postgres
  engine_version: "16.4"
  instance_class: db.t3.micro
  allocated_storage: 20
  db_name: my_app_db
  username: db_admin
  region: us-east-1
```

### Complex

A production deployment with optional inputs:

[`examples/complex.yaml`](examples/complex.yaml)
```yaml
# Complex RDS postgres with multi-AZ + encryption
uses: acdl/pipelines/deploy.yaml@v1.6
module: rds
environment: dev
inputs:
  engine: postgres
  engine_version: "16.4"
  instance_class: db.r6g.large
  allocated_storage: 100
  db_name: my_production_db
  username: db_admin
  multi_az: true
  storage_encrypted: true
  region: us-east-1
```

### Multi-engine variation

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

#### PostgreSQL

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

#### MySQL

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

```yaml
# RDS mysql variation
uses: acdl/pipelines/deploy.yaml@v1.6
module: rds
environment: dev
inputs:
  engine: mysql
  engine_version: "8.4"
  instance_class: db.t3.micro
  allocated_storage: 20
  db_name: my_mysql_db
  username: db_admin
  region: us-east-1
```

## 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.