Files
kandev/docs/plans/kubernetes-startup-timing/plan.md
T
2026-09-10 11:05:05 +01:00

81 lines
3.1 KiB
Markdown

---
created: 2026-09-09
status: implemented
requirements:
- REQ-EXECUTORS-K8S-TIMING-001
- REQ-EXECUTORS-K8S-TIMING-002
system_design:
- ../../specs/executors/system-design/kubernetes-startup-timing.md
legacy_specs:
- ../../specs/kubernetes-executor/spec.md
---
# Implementation Plan: Kubernetes Startup Timing
## Overview
Expose fresh environment stage durations through bounded structured logs.
This package shares the first delivery group with
[worker presets](../kubernetes-worker-presets/plan.md). Either can land first.
Timing data informs future optimization without changing the executor architecture.
## Scope
### In scope
- Per-attempt storage, Pod-readiness, bootstrap, connection, and total durations.
- Explicit failure/cancellation outcomes, correlation, privacy tests, and diagnostic documentation.
### Out of scope
- A metrics registry, new UI stages, historical storage, reconnect measurements, or runtime policy changes.
- First-response latency claims and per-image-pull attribution.
## Technical approach
Add a Kubernetes-local recorder near `KubernetesExecutor.createFresh`.
Use the existing Zap logger and monotonic elapsed time. Bind records to one
attempt ID and allowlisted lifecycle identity fields.
Keep all cluster calls, return errors, checkpoint ordering, and rollback ownership unchanged.
The summary records final return after rollback, not full manager/agent readiness.
## Tests
`executor_kubernetes_timing_test.go` contains these proposed tests:
- `TestKubernetesLaunchTimingSuccess`: TIMING-001.1, 001.2, 002.3.
- `TestKubernetesLaunchTimingFailures`: TIMING-001.3, 002.1.
- `TestKubernetesLaunchTimingFinalization`: TIMING-001.2, 002.1.
- `TestKubernetesLaunchTimingSecrets`: TIMING-002.2.
- `TestKubernetesLaunchTimingConcurrentAttempts`: TIMING-002.3.
- `TestKubernetesLaunchTimingReconnectExcluded`: TIMING-001.4, 002.1.
IDs use the `AC-EXECUTORS-K8S-` prefix. Test fake-client action counts, bounded
record counts, and original errors through the production launch path.
## E2E tests
Extend the existing kubeconfig launch case in
`tests/kubernetes/kubernetes-executor.spec.ts`, project `containers`.
Read its isolated backend file log with Info logging enabled.
Assert one correlated total and the four successful stages for its fresh instance.
The scenario still verifies a working task. It sets no duration threshold.
No UI change requires new mobile tests.
## Work orders
- [x] [Task 01: Record Kubernetes launch durations](task-01-launch-durations.md)
## Verification results
Implemented. Unit timing coverage and the real Kind kubeconfig launch both
produce one correlated summary and four stage records without changing launch
errors or adding a duration threshold.
## Risks
- Labeling this total as agent readiness creates misleading performance claims.
- Deferred rollback can change the final error. The summary must observe that result.
- Info-level stdout filtering differs from backend file logging. The test must read the correct log sink.
- A process crash can prevent the final record. The implementation cannot claim crash-durable timings.