[PR #326] docs: add Kubernetes deployment compatibility RFC #319

New Issue

2026-06-06T22:10:12-04:00

yindo commented

2026-06-06 22:10:12 -04:00

📋 Pull Request Information

Original PR: https://github.com/vxcontrol/pentagi/pull/326
Author: @mason5052
Created: 6/1/2026
Status: 🔄 Open

Base: main ← Head: codex/issue-324-kubernetes-rfc

📝 Commits (2)

6141975 docs: add Kubernetes deployment compatibility RFC (#324)
250824a docs: fix grammar in Kubernetes RFC open question (#324)

📊 Changes

1 file changed (+360 additions, -0 deletions)

View changed files

➕ examples/proposals/kubernetes_deployment.md (+360 -0)

📄 Description

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 #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 (#324, #268) use full URLs and render correctly

Refs #324

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vxcontrol/pentagi/pull/326 **Author:** [@mason5052](https://github.com/mason5052) **Created:** 6/1/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/issue-324-kubernetes-rfc` --- ### 📝 Commits (2) - [`6141975`](https://github.com/vxcontrol/pentagi/commit/61419753389fa2e33fde2fa2b8d98553bcf562ab) docs: add Kubernetes deployment compatibility RFC (#324) - [`250824a`](https://github.com/vxcontrol/pentagi/commit/250824ae2085c207f6694c07582379da4a4b2eb9) docs: fix grammar in Kubernetes RFC open question (#324) ### 📊 Changes **1 file changed** (+360 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `examples/proposals/kubernetes_deployment.md` (+360 -0) </details> ### 📄 Description ## 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 #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 - [x] `git diff --check` reports no whitespace errors - [x] Diff is a single new file under `examples/proposals/` (360 insertions, no code/compose/env changes) - [x] No Helm charts, manifests, operator, CRDs, compose, installer, or environment-variable changes introduced - [x] Tone is neutral throughout (proposed/candidate/future/RFC); never claims Kubernetes is supported today - [x] Internal issue/PR links (#324, #268) use full URLs and render correctly Refs #324 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

yindo added the pull-request label 2026-06-06 22:10:12 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vxcontrol/pentagi#319