# K8s EOS Auto-Upgrade System

## Modules

- `pkg/service/k8scalendar` — syncs EKS lifecycles via `DescribeClusterVersions`, scrapes GKE release schedule, persists lifecycles, publishes `K8sCalendarEvent`.
- `pkg/service/k8supgradeplan` — maintains planned upgrades. Calendar creates `draft` plans; cron triggers approval, then `scheduled` after approve. Manual plans start as `scheduled`. Cron creates k8s upgrade tasks when `trigger_time` is due and notifies admins.
- `pkg/service/k8supgrade/task` — notice templates, task notification (extends existing upgrade execution).

## Configuration (`services` in runtime config)

```yaml
k8sCalendar:
  dummy: false
  syncInterval: 24h
  eosLeadDays: 90

k8sUpgradePlan:
  dummy: false
  scanInterval: 1m
  defaultDeadlineBuffer: 336h
  defaultTriggerOffset: 168h
  approvers: ["admin@example.com"]
  adminEmailTemplateID: "<sendgrid-template-id>"

k8sUpgrade:
  detailLinkBaseURL: "https://ops.example.com/k8sUpgradeTask/%d"
  notify:
    larkChatMap:
      emea: "<chat_id>"
    defaultChatID: "<chat_id>"
    pageURLBase: "https://ops.example.com/k8sUpgradeTask/%d"
    emailTemplateID: "<sendgrid-template-id>"
    # Optional: per business region fixed email recipients (ignores sales owner / TAM on matching targets).
    regionEmailMap:
      us:
        - "team-us@pingcap.com"
      emea:
        - "team-emea@pingcap.com"
    noticeTemplate:
      title: "K8s Cluster Upgrade Notice"
      content: |
        ## Terminology
        ...
```

## HTTP APIs

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/devops/k8sCalendar/lifecycles` | List version lifecycles |
| POST | `/api/v1/devops/k8sCalendar/syncNow` | Force calendar sync (`fail_on_provider_error` optional) |
| GET/POST | `/api/v1/devops/k8sUpgradePlans` | Plan CRUD / list |
| POST | `/api/v1/devops/k8sUpgradePlans/:id/schedule` | Schedule plan |
| POST | `/api/v1/devops/k8sUpgradePlans/:id/triggerNow` | Draft: start approval; scheduled: create task immediately |
| POST | `/api/v1/devops/cluster/k8sUpgradeTasks/:task_id/notify` | Notify Sales Owner / TAM for one task |
| GET/PUT | `/api/v1/devops/cluster/k8sUpgradeTasks/:id/notice` | Per-task notice (default template from `k8sUpgrade.notify.noticeTemplate` config) |

## Database

Migrations create:

- `k8s_version_lifecycles` (includes per-event notification ack columns), `k8s_version_lifecycle_snapshots`
- `k8s_upgrade_plans`
- `k8s_upgrade_notice_templates`, `k8s_upgrade_notify_logs`