feat: add kubernetes deployment support

[kaiitunnz]

Purpose

Adds Kubernetes as a deployment target, in two parts. A kubernetes worker provider lets the supervisor create and delete worker Pods through the cluster API instead of placing containers on its own host. A --backend k8s mode for flowmesh stack up/down/restart/logs/ps/clean renders the server, both Redis instances, Services, and RBAC from the same env schema that drives compose, then applies them with kubectl.

One namespace is one FlowMesh node: a single server Deployment runs NODE_ROLE=root with its supervisor, and the cluster scheduler does the machine placement that bare-metal worker nodes do today. A cluster can still join an external root node by setting NODE_ROLE=worker and pointing at that node's Redis, in which case the Redis workloads are not deployed.

This sits alongside the external provider from #128 rather than replacing it: external admits workers whose lifecycle you own, while kubernetes gives FlowMesh the ability to create and destroy them on demand. docs/KUBERNETES.md contrasts the two.

Changes

• src/server/supervisor/adapters/kubernetes.py — the new provider: pod and secret construction, start/stop lifecycle, orphan reaping, and a node-derived hardware probe.
• src/server/supervisor/manager.py, adapters/base.py, adapters/docker.py — register the provider in the node's guarded provider list, and move the shared WorkerType enum onto the adapter base so the provider does not import it through the Docker adapter.
• src/server/env.py — K8S_* settings the adapter reads for Service names, namespaces, and the GPU resource name.
• sdk/stack/src/flowmesh_stack/manifests.py, kubernetes.py — manifest rendering and the kubectl wrapper, mirroring the existing compose wrapper.
• cli/stack/src/flowmesh_cli_stack/assets/k8s/ — the shipped manifests (namespace, RBAC, Redis, server) and an example worker config.
• cli/stack/src/flowmesh_cli_stack/k8s.py, stack.py, utils.py, env_schema.py — the backend implementation, --backend dispatch on the lifecycle commands, the shared worker-drain helper, and the new STACK_BACKEND / K8S_* schema section.
• docs/KUBERNETES.md plus ARCHITECTURE.md, CLI.md, ENV.md, AGENTS.md — deployment guide and routing.
• Tests — the adapter against a mocked Kubernetes API, manifest rendering including every directive and each shipped asset, and CLI backend dispatch.

Design

The server Deployment is pinned to replicas: 1 with the Recreate strategy. A worker's token lives in the in-memory registry of the supervisor that minted it, so a second replica behind the Service would reject registrations from workers the other replica started. Restarting the pod is still safe, since scheduling state is persisted to Redis and rebuilt on startup.

The provider registers in the node's guarded provider list alongside docker and vastai, and resolves cluster access in its factory's initializer. That placement is load-bearing: a provider that constructs successfully is advertised by GET /stack/workers/providers, so deferring cluster resolution to first use would make a node claim kubernetes with no kubeconfig at all and turn #129's 409 into a late failure.

Manifests are ordinary YAML assets carrying compose-compatible ${VAR} substitution plus a small set of directives for what substitution alone cannot express: conditional inclusion, integers for fields the API rejects as strings, file contents for configuration compose bind-mounts, and the env file's own values for what compose passes through env_file. One .env therefore drives both backends, and no templating dependency is added to a published wheel. Values handed to the cluster come from the env file rather than the process environment, so nothing else in the operator's shell reaches the namespace.

Worker credentials go into a per-worker Secret consumed through envFrom rather than inline in the pod spec, and the secret set is derived from the SecretStr fields on WorkerConfig so a credential added later cannot silently land in a manifest. GPUs are requested as extended resources and left to the device plugin to assign; the server never pins device indices. Worker pods carry no owner reference to the server pod, so a server rollout does not take running workers with it, while pods orphaned by an unclean exit are reaped at supervisor startup because their tokens died with the previous registry.

Two limitations are deliberate and documented. A kubernetes worker is a bare Pod: it restarts in place but is not rescheduled if its node is lost, so pools on preemptible or frequently drained nodes are better served by external. And SSH tasks are unavailable on Kubernetes workers — without a Docker socket the executor never loads, so the task type is never advertised and the dispatcher will not route to it.

Test Plan

uv run pre-commit run --all-files
uv run pytest tests/ --ignore=tests/worker/test_mp_executor_cleanup_gpu.py
uvx bandit -c pyproject.toml -r src/
uv run scripts/dev/check_env_examples.py
uv build --package flowmesh-cli-stack --wheel

Test Result

1789 passed; pre-commit (gitleaks, isort, black, ruff, mypy, codespell, requirements sync) clean; bandit reports no issues on src/; env examples in sync. The flowmesh-cli-stack wheel builds with assets/k8s/*.yaml included, so the manifests ship with the CLI.

No live cluster was involved. The provider is covered against a mocked Kubernetes API and the manifests are covered by rendering assertions over every shipped asset, so the deployment path itself is unexercised end to end and wants a real cluster before this leaves draft.

---

Pre-submission Checklist

• I have read the contribution guidelines.
• I have run pre-commit run --all-files and fixed any issues.
• I have added or updated tests covering my changes (if applicable).
• I have verified that uv run pytest tests/ passes locally.
• If I changed shared schemas or proto definitions, I have checked downstream compatibility across Server and Worker. — n/a, no schema or proto changes.
• If I changed the SDK or CLI, I have verified the affected packages work (uv sync --all-packages --group ci --frozen).
• If this is a breaking change, I have prefixed the PR title with [BREAKING] and described migration steps above. — n/a, no breaking changes.
• I have updated documentation or config examples if user-facing behavior changed.

🤖 Generated with Claude Code