ADR-013: Compose and Helm are supported through the Veltro CLI

Source of truth: docs/adr/013-deployment-targets-and-operator-entry-point.md (synced at build time — edit the original, not this copy). Status: Accepted (2026-09-06)

Amended on acceptance of ADR-014 (proposed 2026-09-26): once its migration step 4 lands, the four profiles below become a VELTRO_PRODUCTS selection of any subset of VectorFlow, CHAD, and Warden on an always-on core, and the Veltro repository becomes the only install path. Product repositories keep native development commands but no standalone deployment path. The single-CLI contract and Compose/Helm parity stand.

Decision owner: Danny

Context

Veltro supports single-host installations and Kubernetes installations. Docker Compose fits an appliance or homelab. Helm fits a Kubernetes cluster.

The repository previously exposed Make targets, shell scripts, Compose commands, and product-specific instructions as separate operator paths. Those paths can drift in profile selection, version pins, authentication mode, health checks, backup behavior, and upgrade order.

Decision

Docker Compose and Helm are both supported deployment targets. Neither target is a temporary bridge to the other.

Both targets must support the full, vectorflow, chad, and warden profiles. They must preserve the same version pins, product boundaries, authentication modes, health contract, and upgrade rules.

The veltro command-line interface (CLI) is the single operator entry point for Veltro installations. It owns installation, lifecycle commands, status, diagnostics, upgrades, backup, restore, support bundles, agent enrollment, demo-sandbox seeding, and Kubernetes rendering.

veltro install is the supported suite installation contract. install.sh ships at the repository root and bootstraps the CLI before calling that contract. Every release publishes veltro-cli at its own version (#1129); veltro install downloads the release from GitHub, so until the repository is public it needs a GitHub token in VELTRO_GITHUB_TOKEN for that download (#1663).

Make targets are thin aliases for the CLI. Direct Compose and Helm commands remain useful for inspection and recovery, but they do not define separate lifecycle behavior. Today that holds for every lifecycle target (init, up, down, pull, logs, ps, config, doctor, status, install, agent-up) and not yet for make verify and make manifest, which still invoke scripts/ directly, nor for the scripts/validate_identity_credentials.py prerequisite on make up and make pull; folding those into the CLI is the remaining work this decision implies.

This decision applies to installations from the Veltro platform repository. A product repository can keep native development and standalone deployment commands.

This ADR records a support decision, not release evidence. A target becomes available only when its implementation, documentation, and release proof land. Today the CLI (cli/veltro_cli), its install.sh bootstrap, and the Compose target ship; veltro k8s render already points at oci://ghcr.io/veltrosecurity/charts/veltro, but the umbrella and product charts themselves publish with veltro#955, so Kubernetes is a supported target without an available chart yet.

Consequences

• Operators learn one command surface for both deployment targets.
• Compose and Helm require parity tests for profiles, versions, authentication, health, and upgrades.
• Make, shell scripts, and documentation must call or describe the CLI contract instead of reimplementing it.
• Native Compose and Helm remain accessible when an operator must inspect or recover the underlying deployment.

Rejected alternatives

1. Support Compose only. This excludes Kubernetes operators and makes the suite unsuitable for cluster deployments.
2. Support Helm only. This adds unnecessary cluster cost for appliances, labs, and small teams.
3. Keep independent operator scripts. Their duplicated profile and upgrade logic already creates drift risk.