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

{
  "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/. The platform-test pipeline validates them against schemas/contract.schema.json.

Simple

A minimal deployment:

examples/simple.yml

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

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.