Files
kandev/docs/plans/kubernetes-task-pod/task-02-shared-lifecycle.md
T
2026-09-24 07:37:17 +01:00

117 lines
5.4 KiB
Markdown

---
id: "02-shared-lifecycle"
title: "Shared pod lifecycle"
status: done
wave: 2
depends_on:
- "01-durable-inventory"
plan: "plan.md"
requirements:
- REQ-EXECUTORS-KUBERNETES-TASK-POD-001
acceptance_criteria:
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.1
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.2
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.3
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.4
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.5
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.6
- AC-EXECUTORS-KUBERNETES-TASK-POD-001.7
system_design:
- ../../specs/executors/system-design/kubernetes-task-pod.md
---
# Task 02: Shared pod lifecycle
## Summary
Wire task-owned inventory into the complete Kubernetes lifecycle. Start additional
sessions as independent agentctl instances in the canonical pod and remove all
session-level authority to destroy shared compute.
## In scope
- Fresh create, attach-only admission, per-instance configuration, secret resolution, and pinned workload snapshot.
- Generation-guarded reconnect/replacement, checkpoints, partial-failure rollback, and restart refresh.
- Session-only termination, final task cleanup, zero-session retention, legacy compatibility, and authorized status projection.
## Out of scope
Cross-task pooling, automated legacy consolidation, and UI redesign.
## Acceptance
- The two-session regression fails before the change and passes with one Pod/PVC and distinct agentctl instances; concurrent attach never creates another pod.
- Stop/delete/force/failure of one session leaves a live sibling usable; task cleanup excludes new attachment and deletes only exact owned resources.
- Restart, legacy ambiguity, foreign identity, profile edits, independent runtime env, and status projection pass targeted regressions.
## Verification
Use TDD for changed logic: run the named regression before and after implementation.
Commands run from repository root. Read scoped guidance and applicable TDD/E2E
skills before implementation.
```bash
(cd apps/backend && go test -race -tags fts5 ./internal/agent/kubernetes ./internal/agent/runtime/lifecycle ./internal/task/service ./internal/kubernetes ./internal/orchestrator/executor ./internal/backendapp -run 'Kubernetes|SharedTaskPod' -count=1)
```
## Files likely touched
- `apps/backend/internal/agent/runtime/lifecycle/executor_kubernetes.go`
- Kubernetes lifecycle bootstrap, identity, reconnect, cleanup, refresh, and checkpoint files
- New `apps/backend/internal/agent/runtime/lifecycle/executor_kubernetes_task_pod_test.go`
- `apps/backend/internal/agent/kubernetes/compose.go` and ownership/admission tests
- `apps/backend/internal/task/service/service_resources.go` and Kubernetes resource cleanup tests
- `apps/backend/internal/kubernetes/sessions.go`, `sessions_retention.go`, and new `sessions_task_pod_test.go`
- `apps/backend/internal/orchestrator/executor/` and `apps/backend/internal/backendapp/` launch/cleanup adapters
## Dependencies
01-durable-inventory.
## Risks
Do not copy sibling execution metadata wholesale, rerun pod-wide bootstrap on attach, or treat force-stop as task deletion authority.
## Parallelism
`sequential`
## Inputs
- [Requirements](../../specs/executors/requirements/kubernetes-task-pod.md).
- [System design](../../specs/executors/system-design/kubernetes-task-pod.md).
- [Plan](plan.md) regression matrix.
- Existing `executor_kubernetes_fakes_test.go`, checkpoint/restart tests, and
task environment repository tests as patterns.
## Results
Targeted Kubernetes package tests passed with `-race -tags fts5`. Added regressions
cover independent agent environments, concurrent attachment, session-only stop,
exact task cleanup, backend/container/Pod recovery, stale-token protection,
secret/inventory/connection failure rollback, legacy conflicts and adopted-resource
protection, retained zero-session status, and executor deletion guards.
Startup fences interrupted claims under the existing exclusive runtime-state lock.
Incomplete bootstrap inventory remains available for exact cleanup and blocks
unsafe attachment. Desktop and mobile retained-row component tests passed.
Kind validation additionally exposed two integration gaps that unit fixtures did
not cover: creating private HOME before credential-less session preparation, and
preserving shared ownership/version markers through execution metadata filtering.
Both have failing-before/passing-after regressions. The final targeted lifecycle,
orchestrator executor, and status packages pass with race detection; scoped
lifecycle lint reports zero issues. The live test proves three sessions in one
Pod UID and a sibling continuing after force-stopping the creator; restart and
final cleanup subsequently passed in work order 03.
The passing Kind run exposed a transient cleanup retry after execution identity
rebinding. The final regression reproduces stopping the same remote session with
a new local execution ID and verifies immediate task cleanup. Exact task/session/
environment/remote-instance matching closes its original local connection while
leaving siblings intact. Final lifecycle race tests pass (8.512s); lint is clean.
## PR remediation
PR remediation adds typed not-found errors, encrypted credential recovery across backend restart, concurrent stop/attach coverage, and bounded cancellation-detached cleanup. Targeted race coverage passes; the user accepted shared task credential trust on 2026-09-23. Different profiles and credentials remain supported; the trust ADR and public guide describe sibling access and operator revocation responsibilities.