docs: add Kubernetes deployment compatibility RFC

[mason5052]

Summary

Adds examples/proposals/kubernetes_deployment.md, an RFC-style design document responding to the Kubernetes deployment request in #324. It is docs-only and sits alongside the existing proposals in examples/proposals/ (e.g. mcp_client_integration.md, flow_concurrency.md).

Problem

#324 asks whether PentAGI can run on Kubernetes. Today PentAGI is built and documented around Docker Compose and the installer, and there is no supported Kubernetes path. The request is broad, and the hard parts (especially the Docker-socket-based flow executor) are easy to underestimate. There is no single place that records why Kubernetes is non-trivial today or what an incremental path could look like, so any implementation attempt would start without an agreed design surface.

Solution

A neutral, docs-first RFC that:

• States up front that it does not implement runtime behavior and does not claim Kubernetes is supported today (no Helm charts, manifests, operator, CRDs, compose/installer changes, or new environment variables).
• Records the current Compose/installer deployment assumptions grounded in docker-compose.yml and the backend (Docker-socket executor, root:root privilege, named volumes, .env secrets, Compose DNS, in-backend TLS on 8443, startup goose migrations, image overrides).
• Maps each assumption to candidate Kubernetes equivalents across the expected work areas: secrets/config, persistent volumes, service discovery, ingress/TLS, health checks, network policies, the flow/container execution model, observability, image overrides, and the upgrade/migration path.
• Treats the Docker-socket flow executor as the central hard problem and lays out candidate options (Kubernetes-native Pods/Jobs, DinD sidecar, sandboxed runtimes) with trade-offs, without picking one.
• Proposes an incremental, docs-first path, plus Open Questions, Security and Operational Considerations (least-privilege RBAC, dedicated namespace, no unsafe defaults), and a Test/Validation Strategy (kind/minikube, manifest/chart lint, migration safety, e2e flow, Compose parity guard).
• Carries forward the feat: queue input for running automation flows #268 review lesson explicitly: any future Kubernetes lifecycle state must be visible and manageable through standard Kubernetes objects, not hidden in process memory.

User Impact

Documentation only. No runtime, build, schema, or configuration behavior changes. Compose remains the only supported deployment path. The RFC gives maintainers a single artifact to accept, reshape, or decline before any deployment code is written, and gives users asking about Kubernetes an honest, current answer.

Test Plan

• git diff --check reports no whitespace errors
• Diff is a single new file under examples/proposals/ (360 insertions, no code/compose/env changes)
• No Helm charts, manifests, operator, CRDs, compose, installer, or environment-variable changes introduced
• Tone is neutral throughout (proposed/candidate/future/RFC); never claims Kubernetes is supported today
• Internal issue/PR links ([Enhancement]: Are you considering supporting it in Kubernetes? #324, feat: queue input for running automation flows #268) use full URLs and render correctly

Refs #324

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a docs-only RFC that outlines why PentAGI doesn’t currently run on Kubernetes and proposes an incremental path toward Kubernetes compatibility, focusing on the Docker-socket-based flow executor as the main blocker.

Changes:

• Introduces a Kubernetes deployment RFC covering current Compose assumptions and Kubernetes equivalents.
• Documents executor strategy options (Kubernetes-native Pods/Jobs vs DinD vs sandboxed runtimes) with trade-offs.
• Defines a staged, docs-first roadmap plus security/validation considerations for future implementation work.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.