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, HIPAA §164.312(a)(2)(iv), 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.yaml`](examples/simple.yaml)
```yaml
uses: acdl/pipelines/deploy.yaml@v1.8
module: uptime
environment: dev
inputs:
  region: us-east-1
  feature_flag_enabled: true
```

### Complex

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

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

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