# K8S-VERSION-MANAGER KNOWLEDGE BASE

## OVERVIEW
`k8s-version-manager` manages dataplane Kubernetes upgrade workflows through an `UpgradeOperation` CRD plus a small HTTP API server.

## STRUCTURE
- `cmd/main.go`: manager bootstrap, controller registration, API server registration.
- `internal/controllers/upgradeoperation/`: core phase/step state machine and service clients.
- `internal/server/`: Gin HTTP API (`/api/v1/...`) for k8s info and operation management.
- `api/v1/`: `UpgradeOperation` and `K8sInformation` API types.
- `test/e2e/`: Kind-based e2e tests.

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Reconcile flow | `internal/controllers/upgradeoperation/controller.go` | Finalizer, phase switch, deferred status update |
| Upgrade phase logic | `internal/controllers/upgradeoperation/phase.go` | Pending/running/completed transitions |
| Per-step logic | `internal/controllers/upgradeoperation/step.go` | Step execution and step status |
| HTTP handlers | `internal/server/handlers.go` | REST API surface and request parsing |
| Metrics | `internal/controllers/upgradeoperation/metrics/` | Timeout/step metrics and cleanup |

## COMMANDS
```bash
make build
make test
make test-e2e           # creates/deletes Kind cluster via Make targets
make lint
make manifests
make generate
```

## CONVENTIONS (LOCAL)
- Reconcile uses one deferred `Status().Update()` path; mutate `upgradeOp.Status` in memory and let deferred update persist once.
- Finalizer is `kvm.ng.tidbcloud.com/upgrade-operation-finalizer`; deletion path also cleans metrics.
- API server implements `NeedLeaderElection() == false`, so all replicas can serve HTTP traffic.
- `make test` excludes e2e packages; use `make test-e2e` explicitly for e2e.
- CRD/deepcopy files are generated via controller tools.

## ANTI-PATTERNS
- Writing multiple scattered status updates inside one reconcile path.
- Editing generated deepcopy code manually.
- Skipping finalizer/metrics cleanup logic when touching deletion flow.
- Running e2e manually without the Makefile's setup/cleanup targets.