Feature/runtime kata

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added — Kata Containers Runtime Support
+
+- `runtime` field on `deploy_app` and `deploy_with_configs` agent commands — values: `runc` (default), `kata`
+- Server-side validation rejects unknown runtime values with HTTP 422
+- Kata capability gating: agent `/capabilities` response checked before scheduling Kata deployments; agents without `kata` feature receive 422 rejection
+- `--runtime kata|runc` flag on `stacker deploy` and `stacker agent deploy-app` CLI commands
+- Database migration `20260406170000`: `runtime` column added to `deployment` table, persisted across redeploys
+- Vault integration: per-deployment runtime preference (`store_runtime_preference` / `fetch_runtime_preference`) and org-level runtime policy (`fetch_org_runtime_policy`)
+- Compose template support: `runtime:` field conditionally emitted in generated `docker-compose.yml` when runtime is not `runc` (both Tera and CLI generators)
+- Enhanced tracing: `runtime` field added to `Agent enqueue command` span for structured log filtering
+- Documentation: `docs/kata/` — setup guide, network constraints, monitoring/observability reference
+- Provisioning: Ansible role and Terraform module for Hetzner dedicated-CPU (CCX) servers with KVM/Kata pre-configured (integrated into TFA)
+
 ### Fixed — Casbin ACL for marketplace compose access
 - Added Casbin policy granting `group_admin` role GET access to `/admin/project/:id/compose`.
 - This allows the User Service OAuth client (which authenticates as `root` → `group_admin`) to fetch compose definitions for marketplace templates.

README.md

@@ -134,7 +134,7 @@ The end-user tool. No server required for local deploys.
 | Command | Description |
 |---------|-------------|
 | `stacker init` | Detect project type, generate `stacker.yml` + `.stacker/` artifacts |
-| `stacker deploy` | Build & deploy the stack (local, cloud, or server) |
+| `stacker deploy` | Build & deploy the stack (local, cloud, or server). `--runtime kata\|runc` selects container runtime |
 | `stacker status` | Show running containers and health |
 | `stacker logs` | View container logs (`--follow`, `--service`, `--tail`) |
 | `stacker list deployments` | List deployments on the Stacker server |
@@ -155,7 +155,7 @@ The end-user tool. No server required for local deploys.
 | `stacker agent status` | Display agent snapshot — containers, versions, uptime |
 | `stacker agent logs <app>` | Retrieve container logs from the remote agent |
 | `stacker agent restart <app>` | Restart a container via the agent |
-| `stacker agent deploy-app` | Deploy or update an app container on the target server |
+| `stacker agent deploy-app` | Deploy or update an app container on the target server. `--runtime kata\|runc` selects container runtime |
 | `stacker agent remove-app` | Remove an app container (with optional volume/image cleanup) |
 | `stacker agent configure-proxy` | Configure Nginx Proxy Manager via the agent |
 | `stacker agent history` | Show recent command execution history |
@@ -338,11 +338,27 @@ cargo test deployment_validator    # Deployment validation
 
 ---
 
+## Kata Containers (Hardware Isolation)
+
+Stacker supports [Kata Containers](https://katacontainers.io/) as an alternative runtime, providing VM-level isolation for each container using hardware virtualization (KVM).
+
+**KVM requirement** — Kata needs nested or bare-metal KVM. Hetzner dedicated-CPU servers (CCX line) expose `/dev/kvm` out of the box, making them an ideal deployment target.
+
+```bash
+stacker deploy --runtime kata          # deploy the current stack with Kata isolation
+stacker agent deploy-app --runtime kata  # deploy a single app container with Kata
+```
+
+See [docs/kata/](docs/kata/README.md) for the full setup guide, network constraints, and monitoring reference. Automated provisioning (Ansible + Terraform for Hetzner CCX) is available via the TFA infrastructure toolkit.
+
+---
+
 ## Documentation
 
 - [stacker.yml reference](docs/STACKER_YML_REFERENCE.md) — full configuration schema
 - [CLI implementation plan](docs/STACKER_CLI_PLAN.md) — architecture and design decisions
 - [Changelog](CHANGELOG.md) — release history
+- [Kata Containers guide](docs/kata/README.md) — hardware-isolated containers with KVM
 
 ---