acdl/modules/l1/uptime/README.md

# uptime — Uptime Kuma monitoring service

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

Uptime-kuma is a self-hosted monitoring tool deployed as an ECS Fargate
container. It supports HTTP, DNS, and TCP health checks and can notify
on-call via Teams, email, SMS, or GitHub issues. The module is deployed
by default after any L2 module with a separate terraform state and can
be disabled via the `feature_flag_enabled` input.

## Resources

| Resource | Type | Purpose |
|----------|------|---------|
| uptime | `aws:ecs:uptime-service` | ECS Fargate task + service + ALB + EFS volume |

## Inputs

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container_image` | string | no | `louislam/uptime-kuma:1` | Docker image for uptime-kuma |
| `region` | string | yes | — | AWS region |
| `uptime_url` | string | no | — | Custom domain for the uptime dashboard (optional; if absent, the ALB DNS is used) |
| `monitored_endpoints` | array | no | `[]` | Array of endpoints to monitor. Each entry: {name, url, type (http\|dns\|tcp), interval_seconds, timeout_seconds} |
| `static_checks` | array | no | `[]` | Pre-defined health checks (hardcoded monitors that don't depend on L2 outputs). Same shape as monitored_endpoints. |
| `alert_channels` | object | no | `{}` | Alert notification channels. Keys: teams_webhook (string), email_addresses (array of strings), sms_numbers (array of strings), github_issue_repo (string, org/repo format) |
| `feature_flag_enabled` | boolean | no | `true` | Feature flag: when false, no resources are emitted (the uptime deployment is skipped entirely) |
| `cpu` | number | no | `256` | CPU units for the ECS task (256 = 0.25 vCPU) |
| `memory` | number | no | `512` | Memory for the ECS task in MB |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `uptime_url` | string | The URL of the uptime-kuma dashboard (ALB DNS or custom domain) |
| `service_arn` | arn | The ARN of the ECS service |
| `task_definition_arn` | arn | The ARN of the ECS task definition |

## NFRs

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `deletion_protection` | boolean | true | Prevent resource destruction via Terraform lifecycle prevent_destroy |
| `encryption_enabled` | boolean | true | Enable CloudWatch log group encryption with KMS |

## Usage

```json
{
  "id": "uptime",
  "type": "aws:ecs:uptime-service",
  "module": "uptime@1.0.0",
  "inputs": {
    "container_image": "louislam/uptime-kuma:1",
    "region": "us-east-1",
    "feature_flag_enabled": true,
    "cpu": 256,
    "memory": 512,
    "monitored_endpoints": [
      {"name": "example", "url": "https://example.com", "type": "http", "interval_seconds": 60, "timeout_seconds": 30}
    ],
    "alert_channels": {
      "teams_webhook": "https://hooks.example.com/webhook",
      "email_addresses": ["oncall@example.com"]
    }
  }
}
```

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

## Compliance extension points

- **KMS encryption for EFS** — encrypt the EFS volume that persists uptime-kuma state with a customer-managed KMS key (SOC2 CC6.1, GDPR Art.32).
- **HTTPS/TLS for the ALB** — attach an ACM certificate and HTTPS listener to the ALB so the dashboard is served over TLS (SOC2 CC6.1, GDPR Art.32).
- **WAF in front of uptime dashboard** — place a WAF web ACL in front of the ALB to protect the dashboard from common exploits (SOC2 CC7.2).
- **Secrets Manager for alert webhook URLs** — store Teams webhook URLs and other credentials in AWS Secrets Manager rather than plaintext inputs (SOC2 CC6.1, GDPR Art.32).
- **CloudWatch alarms for uptime-kuma health** — add CloudWatch alarms on ECS task health and ALB 5xx rates to alert when the monitoring tool itself is degraded (SOC2 CC7.2, DORA Art.11).

## 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: up1
infrastructure:
  uptime:
    inputs:
      feature_flag_enabled: true
      region: us-east-1
    version: 1.0.0
name: uptime-monitor
```

### Complex

A production deployment with monitored endpoints, static checks, and
multiple alert channels:

[`examples/complex.yml`](examples/complex.yml)
```yaml
environment: dev
id: up1
infrastructure:
  uptime:
    inputs:
      alert_channels:
        email_addresses:
        - oncall@example.com
        - sre@example.com
        github_issue_repo: acdl/acdl
        sms_numbers:
        - '+1234567890'
        teams_webhook: https://hooks.example.com/teams/webhook
      cpu: 512
      feature_flag_enabled: true
      memory: 1024
      monitored_endpoints:
      - interval_seconds: 30
        name: api-health
        timeout_seconds: 10
        type: http
        url: https://api.example.com/health
      - interval_seconds: 60
        name: dns-check
        timeout_seconds: 10
        type: dns
        url: example.com
      - interval_seconds: 60
        name: tcp-check
        timeout_seconds: 10
        type: tcp
        url: db.example.com:5432
      region: us-east-1
      static_checks:
      - interval_seconds: 60
        name: google
        timeout_seconds: 10
        type: http
        url: https://google.com
    version: 1.0.0
name: uptime-monitor
```

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