neutral
Phase 21 — Deployment Platform Modernization (Containers, Helm, Argo)
Modernizes Cruvero deployment packaging and delivery for the current runtime architecture: container images, Helm chart foundation, Kubernetes workload templates, and Argo CD GitOps promotion flows.
Status: Planned (refreshed 2026-02-13)
Depends on: Phase 9E baseline deployment artifacts, Phase 14 API, Phase 20 UI, and current runtime features in dev
Migrations: None (deployment/docs/infrastructure packaging only)
Branch: dev
Why This Refresh
The original Phase 21 spec is stale relative to the codebase. It still assumes missing assets and older architecture constraints. Current reality:
deploy/kubernetes/ already has raw manifests from Phase 9E.- Runtime topology now includes expanded services/features (Phase 24/25 work) that deployment packaging must account for.
- Existing CI/workflow/deploy docs are partially present but not unified into a charted, environment-aware release model.
- Phase 25E references Phase 21 manifest patterns, so Phase 21 must be brought up to date before 25E execution.
This refresh turns Phase 21 into the canonical deployment foundation track for today’s repo.
Scope
In Scope
- Build and publish production container images for core runtime services.
- Define Helm chart scaffold and environment value overlays.
- Template service workloads and migration job from existing raw manifests.
- Add Argo CD ApplicationSet delivery model (dev/staging/prod).
- Integrate ingress + ServiceMonitor templates and deployment docs.
Out of Scope
- MCP fleet-specific Kubernetes topology (
deploy/kubernetes/mcp/*) and KEDA/TLS/OTel requirements from Phase 25E.
- Runtime feature implementation (no changes to agent logic or MCP transport code).
- Database schema/runtime migrations beyond existing
cmd/migrate usage.
Deployment Targets
Core Deployable Components
| Component | Entrypoint | Deployment Form |
|---|
| Worker | cmd/worker | Deployment |
| API | cmd/api | Deployment + Service |
| UI | cmd/ui | Deployment + Service + Ingress |
| Graph Worker | cmd/graph-worker | Deployment |
| Embed Worker | cmd/embed-worker | Deployment |
| Migrator | cmd/migrate | Helm hook Job |
Infrastructure Dependencies
| Dependency | Purpose | Source |
|---|
| PostgreSQL | primary state and metadata | chart dependency (planned) |
| Dragonfly | cache + quota/rate backing | chart dependency (planned) |
| Qdrant | vector store option | chart dependency (planned) |
| NATS | events/discovery backbone | chart dependency (planned) |
| Temporal | orchestration control plane | external/cluster-managed |
Phase 21 and Phase 25E Boundary
Phase 21 provides the platform baseline used by later infrastructure phases:
- Container build strategy
- Helm chart structure
- Environment overlays
- Argo application promotion model
- Baseline ingress/monitoring templates
Phase 25E then extends this with MCP-enterprise-specific manifests and controls:
deploy/kubernetes/mcp/*- MCP TLS transport configuration and cert-manager policy
- MCP observability dashboards/metrics across gateway + MCP servers
Sub-Phases
| Sub-Phase | Name | Prompts | Depends On |
|---|
| 21A | Container Images + Build Workflow | 4 | — |
| 21B | Helm Foundation + Values Model | 4 | 21A |
| 21C | Workload Templates + Security + Migration | 4 | 21B |
| 21D | Argo GitOps + Ingress + Monitoring + Ops Docs | 4 | 21C |
Total: 4 sub-phases, 16 prompts
Dependency Graph
Expected Artifacts
docker/Dockerfile.* for all core services and migrator..github/workflows/build-images.yml image build/push pipeline.charts/cruvero/ chart with layered values and templates.deploy/argocd/{project.yaml,applicationset.yaml}.docs/manual/kubernetes-deployment.md updated for current rollout model.
Success Gates
At phase completion:
docker build succeeds for all defined images.helm dependency build charts/cruvero succeeds.helm lint charts/cruvero --strict succeeds.helm template cruvero charts/cruvero renders valid manifests for dev/staging/prod overlays.- Argo ApplicationSet renders dev/staging/prod applications with correct sync policies.
- No hardcoded credentials in chart/workflow/manifests.
Risks and Mitigation
| Risk | Mitigation |
|---|
| Drift between repo runtime and chart values | Generate/validate env coverage from current config keys and keep values overlays minimal/explicit |
| Service probe mismatch (worker/api/ui vs graph/embed) | Use service-specific probe strategy; do not force HTTP probes on non-HTTP workers |
| Overlap with Phase 25E MCP infra | Keep MCP fleet manifests/TLS/OTel enhancements explicitly out of Phase 21 scope |
| Inconsistent promotion controls | Lock Argo auto-sync policy by environment (dev/staging auto, prod manual) |
Relationship to Other Phases
| Phase | Relationship |
|---|
| Phase 9E | Provides raw Kubernetes and operational baseline templates |
| Phase 20 | Defines UI packaging constraints (frontend build + embedded assets) |
| Phase 24 | Expands runtime config surface that Helm values must support |
| Phase 25A-25D | Adds MCP runtime features that must be deployable under Phase 21 packaging |
| Phase 25E | Builds MCP-specific Kubernetes/TLS/observability on top of Phase 21 baseline |
Progress Notes
- 2026-02-13: Phase 21 spec refreshed for current architecture and deconflicted from Phase 25E scope.