Skip to main content

ADR 012: Deployment Strategy for the Platform

Date: 2025-09-17

Status: Proposed

Decision Makers: Platform Architecture Team

Context​

The platform comprises multiple modular components that must be deployable in a consistent, maintainable, and flexible manner. A unified deployment strategy is needed to enable full-platform orchestration, support GitOps practices, and allow individual component deployments for testing, development, or custom rollouts.

This ADR proposes a strategy that balances operational efficiency, developer experience, and best practices in Kubernetes-native DevOps by leveraging:

  • Helmfile as the primary deployment orchestration tool
  • ArgoCD as a secondary, GitOps-compatible deployment mechanism derived from Helmfile definitions
  • Helm Charts for individual component deployment

Checked Architecture Principles​

  • [full] Model-centric data flow
  • [full] Distributed architecture with unified user experience
  • [full] Modular design
  • [full] Integration capability through defined interfaces
  • [full] Open source as the default
  • [full] Cloud-native architecture
  • [partial] Prefer standard solutions over custom development → Argo-based generation from Helmfile introduces a semi-custom process
  • [full] Self-contained deployment
  • [full] Technological consistency to ensure maintainability
  • [partial] Multi-tenancy → Strategy supports but does not enforce multi-tenancy isolation
  • [full] Security by design

Decision​

The deployment strategy will be structured as follows:

Primary Strategy: Helmfile-Based Deployment​

  • Helmfile will act as the central orchestration layer, enabling declarative definition and ordering of all Helm chart-based components.
  • Provides a single source of truth for the entire platform’s deployment configuration.
  • Supports templating, layering, and per-environment overrides.
  • Enables local and CI/CD-triggered deployments, with high developer ergonomics.

Secondary Strategy: ArgoCD GitOps Deployment​

  • ArgoCD will be supported as a GitOps-compatible option, using manifests derived from Helmfile definitions.
  • Allows teams with GitOps workflows to adopt ArgoCD without divergence from platform standards.
  • Helmfile state will serve as the configuration source of truth, from which ArgoCD manifests or AppProjects can be rendered.
  • Alignment between Helmfile and ArgoCD artifacts will be automated (e.g., via code generation or CI tooling).

Individual Deployment: Helm Charts Per Component​

  • Each component remains deployable independently via Helm Charts.
  • Enables developers to test, roll out, or scale components individually without relying on the full platform deployment.

Consequences​

Positive​

  • Enables consistent deployments of the full platform with a unified configuration model.
  • Supports both imperative and GitOps paradigms, accommodating varying team preferences.
  • Facilitates modular development and testing, enhancing velocity and flexibility.
  • Promotes technological consistency through standardized Helm-based tooling.

Negative / Trade-offs​

  • Maintaining multiple deployment paths (Helmfile + ArgoCD) introduces complexity and requires discipline to avoid drift.
  • Learning curve for teams unfamiliar with Helmfile syntax and layering logic.
  • Requires tooling or process to generate ArgoCD-compatible manifests from Helmfile.

Alternatives​

  • Use ArgoCD as the primary mechanism with raw Helm Charts per component
    Rejected due to lack of central orchestration logic and harder environment layering.

  • Use Helm CLI and shell scripts for orchestration
    Rejected due to lack of declarative state management and reproducibility.

  • Build a custom platform operator or controller
    Rejected due to high maintenance cost, limited flexibility, and overlap with existing CNCF tools.

See also​