José Almeida
100 lines
5.0 KiB
Markdown
100 lines
5.0 KiB
Markdown
---
|
|
status: draft
|
|
system: executors
|
|
created: 2026-09-13
|
|
owners:
|
|
- kandev
|
|
---
|
|
|
|
# Kubernetes Docker Workloads Requirements
|
|
|
|
## Overview
|
|
|
|
Administrators need task Pods whose agents can build source, build container
|
|
images and run Docker/Compose tests against the task checkout. The executor
|
|
system owns the Pod-template, workspace and companion-container boundaries.
|
|
This capability extends the [Kubernetes foundation](../../kubernetes-executor/spec.md)
|
|
without changing existing profiles or baseline worker presets.
|
|
|
|
## Requirements
|
|
|
|
### REQ-EXECUTORS-K8S-DOCKER-001: Explicit companion workspace access
|
|
|
|
**Intent:** A selected companion can consume the same task checkout while
|
|
Kandev retains ownership of workspace storage and private runtime material.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-EXECUTORS-K8S-DOCKER-001.1:** An administrator shall be able to explicitly
|
|
grant an ordinary non-main container access to the task workspace at the same
|
|
path as the main container, with either read-only or read-write access.
|
|
- **AC-EXECUTORS-K8S-DOCKER-001.2:** Profiles without such a grant shall retain
|
|
their current mount behavior. The template shall not redefine workspace
|
|
storage, redirect a grant, or grant companion access to Kandev runtime/auth
|
|
volumes; init and ephemeral containers shall remain ineligible.
|
|
- **AC-EXECUTORS-K8S-DOCKER-001.3:** Admission that adds, removes, duplicates,
|
|
transfers or changes a workspace grant shall fail validation before agent
|
|
bootstrap. Unrelated compatible admission defaults shall remain accepted.
|
|
- **AC-EXECUTORS-K8S-DOCKER-001.4:** A replacement Pod shall use the recorded
|
|
workload's grants and storage identity. Editing a profile shall not change a
|
|
retained session's replacement workload or authorize deletion of foreign data.
|
|
|
|
### REQ-EXECUTORS-K8S-DOCKER-002: Explicit full-toolchain Docker configuration
|
|
|
|
**Intent:** Operators can prepare a full worker without mistaking installed
|
|
client commands for functioning container execution.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-EXECUTORS-K8S-DOCKER-002.1:** A documented opt-in worker recipe shall
|
|
identify immutable image inputs, Linux architecture, installed language and
|
|
browser tools, runtime user, writable caches and Docker client/daemon versions.
|
|
It shall contain no task credentials or private repository contents.
|
|
- **AC-EXECUTORS-K8S-DOCKER-002.2:** The example shall give each task Pod its own
|
|
Docker daemon and local client connection, with no shared host Docker socket,
|
|
public Docker endpoint or implicit cluster credential in the workload.
|
|
- **AC-EXECUTORS-K8S-DOCKER-002.3:** Daemon privileges, resources and storage
|
|
shall be explicit operator configuration. The agent shall run non-root;
|
|
configuration shall not silently enable privileged workloads in existing
|
|
profiles or claim compatibility with restricted admission.
|
|
- **AC-EXECUTORS-K8S-DOCKER-002.4:** Docker-dependent preparation shall wait for
|
|
daemon readiness with a finite timeout and report failure if it cannot become
|
|
ready, rather than reporting a Docker-capable environment based on CLI presence.
|
|
|
|
### REQ-EXECUTORS-K8S-DOCKER-003: Verified execution and lifecycle
|
|
|
|
**Intent:** A Docker-capable task remains inspectable, resumable and reclaimable
|
|
through the existing Kandev lifecycle.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-EXECUTORS-K8S-DOCKER-003.1:** Verification shall exercise actual source
|
|
tests, image build/run and a Compose service that reads and writes the same
|
|
task-workspace files seen by the agent. CLI version checks alone shall not
|
|
establish compatibility.
|
|
- **AC-EXECUTORS-K8S-DOCKER-003.2:** Ordinary Stop/Resume shall preserve the Pod
|
|
and managed workspace; documentation shall disclose retained companion
|
|
compute. Replacement shall recover workspace results while permitting loss
|
|
of explicitly disposable Docker caches and test containers.
|
|
- **AC-EXECUTORS-K8S-DOCKER-003.3:** Terminal cleanup shall remove exactly the
|
|
owned Pod and managed workspace, leave existing claims untouched, and leave
|
|
no nested compute belonging to the removed Pod. Agent results and diagnostics
|
|
shall be checked through Kandev before destructive cleanup.
|
|
- **AC-EXECUTORS-K8S-DOCKER-003.4:** Published evidence shall distinguish tested
|
|
architecture/runtime versions from untested combinations and verify resource
|
|
accounting for the agent, daemon and nested test containers. One task with a
|
|
companion shall remain one Kubernetes Pod for workload inventory purposes.
|
|
|
|
## Out of scope
|
|
|
|
- New control-plane deployments, operators, CRDs, Helm charts or release channels.
|
|
- A Docker security sandbox guarantee, automatic permission grants or a new UI.
|
|
- Cross-node migration of local PVCs, automatic suspend-to-zero or a capacity queue.
|
|
- Support for arbitrary host-path mounts, shared Docker daemons or all Docker plugins.
|
|
- Changing the security contract of the existing minimal, Node/pnpm or Python presets.
|
|
|
|
## Delivery
|
|
|
|
See the [system design](../system-design/kubernetes-docker-workloads.md) and
|
|
[implementation plan](../../../plans/kubernetes-docker-workloads/plan.md).
|