feat(P33): uptime-kuma primitive + deploy-uptime pipeline stage (REQ-88..91)

---ci--- project: acdl phase: 33 milestone: v1.8 status: execute ---/ci--- - New uptime L1 primitive (aws:ecs:uptime-service) deploying uptime-kuma on ECS Fargate with feature_flag_enabled, monitored_endpoints, static_checks, alert_channels (Teams/email/SMS/GitHub issues). - Adapter emits ECS Fargate task + service when feature_flag_enabled=true; emits nothing when false. Container image louislam/uptime-kuma:1. - New deploy-uptime pipeline stage in pipelines/deploy.yaml (after publish-outputs, before comment-outputs). Now 9 stages. - run_platform.sh --deploy-uptime flag + automatic uptime deployment after L2 module (separate state $WORK/uptime-tf). Endpoints from L2 outputs passed as monitored_endpoints. Feature flag from inputs.uptime_enabled (default true). - scripts/seed_uptime_monitors.py for post-deploy monitor seeding via uptime-kuma API. - Registered in registry.json (14 modules total). Tests: +6 (312 -> 318). All pass.
2026-07-22 22:15:35 +00:00
parent 8145eee8fc
commit 491ba78768
12 changed files with 591 additions and 6 deletions
@@ -0,0 +1,151 @@
+# 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.
@@ -0,0 +1,38 @@
+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"
@@ -0,0 +1,6 @@
+uses: acdl/pipelines/deploy.yaml@v1.8
+module: uptime
+environment: dev
+inputs:
+  region: us-east-1
+  feature_flag_enabled: true
@@ -0,0 +1,38 @@
+{
+  "version": "1.0.0",
+  "stack": {
+    "name": "uptime",
+    "kind": "l1",
+    "depth": 1
+  },
+  "resources": [
+    {
+      "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"]
+        }
+      },
+      "outputs": {
+        "uptime_url": {"type": "string"},
+        "service_arn": {"type": "arn"},
+        "task_definition_arn": {"type": "arn"}
+      },
+      "nfrs": {
+        "deletion_protection": true,
+        "encryption_enabled": true
+      }
+    }
+  ]
+}
@@ -0,0 +1,87 @@
+{
+  "name": "uptime",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:ecs:uptime-service",
+  "description": "Deploys uptime-kuma as an ECS Fargate container for self-hosted uptime monitoring. Supports HTTP, DNS, and TCP health checks. Includes alert channels (Teams, email, SMS, GitHub issues). Deployed by default after any L2 module with a separate terraform state. Can be disabled via the feature_flag_enabled input.",
+  "inputs": {
+    "container_image": {
+      "type": "string",
+      "description": "Docker image for uptime-kuma",
+      "required": false,
+      "default": "louislam/uptime-kuma:1"
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region",
+      "required": true
+    },
+    "uptime_url": {
+      "type": "string",
+      "description": "Custom domain for the uptime dashboard (optional; if absent, the ALB DNS is used)",
+      "required": false
+    },
+    "monitored_endpoints": {
+      "type": "array",
+      "description": "Array of endpoints to monitor. Each entry: {name, url, type (http|dns|tcp), interval_seconds, timeout_seconds}",
+      "required": false,
+      "default": []
+    },
+    "static_checks": {
+      "type": "array",
+      "description": "Pre-defined health checks (hardcoded monitors that don't depend on L2 outputs). Same shape as monitored_endpoints.",
+      "required": false,
+      "default": []
+    },
+    "alert_channels": {
+      "type": "object",
+      "description": "Alert notification channels. Keys: teams_webhook (string), email_addresses (array of strings), sms_numbers (array of strings), github_issue_repo (string, org/repo format)",
+      "required": false,
+      "default": {}
+    },
+    "feature_flag_enabled": {
+      "type": "boolean",
+      "description": "Feature flag: when false, no resources are emitted (the uptime deployment is skipped entirely)",
+      "required": false,
+      "default": true
+    },
+    "cpu": {
+      "type": "number",
+      "description": "CPU units for the ECS task (256 = 0.25 vCPU)",
+      "required": false,
+      "default": 256
+    },
+    "memory": {
+      "type": "number",
+      "description": "Memory for the ECS task in MB",
+      "required": false,
+      "default": 512
+    }
+  },
+  "outputs": {
+    "uptime_url": {
+      "type": "string",
+      "description": "The URL of the uptime-kuma dashboard (ALB DNS or custom domain)"
+    },
+    "service_arn": {
+      "type": "arn",
+      "description": "The ARN of the ECS service"
+    },
+    "task_definition_arn": {
+      "type": "arn",
+      "description": "The ARN of the ECS task definition"
+    }
+  },
+  "nfrs": {
+    "deletion_protection": {
+      "type": "boolean",
+      "description": "Prevent resource destruction via Terraform lifecycle prevent_destroy",
+      "default": true
+    },
+    "encryption_enabled": {
+      "type": "boolean",
+      "description": "Enable CloudWatch log group encryption with KMS",
+      "default": true
+    }
+  }
+}