atmos helm

Deploy Helm charts as first-class Atmos components — local charts, remote repository charts, and OCI charts — using the same stack-based workflow you use for Terraform and Kubernetes. Atmos renders, previews, installs, and deletes releases through the Helm Go SDK, with values, credentials, hooks, and dependency ordering handled by your stack configuration. No helm or helmfile binary required.

Experimental

Configure Helm Components

Set the default component location in atmos.yaml, then describe what each stack should deploy with chart, version, repositories, values, values_files, namespace, env, hooks, and dependencies.

Stack Configuration

Usage

atmos helm template <component> --stack <stack>
atmos helm diff <component> --stack <stack>
atmos helm plan <component> --stack <stack>
atmos helm values <component> --stack <stack>
atmos helm apply <component> --stack <stack>
atmos helm deploy <component> --stack <stack>
atmos helm delete <component> --stack <stack>

atmos helm template --all --stack <stack>
atmos helm apply --affected --base origin/main
atmos helm deploy <component> --stack <stack> --ci

atmos helm apply --affected --tags production
atmos helm apply --all --labels cost-center=platform

# Repeat --labels to combine multiple selectors across occurrences
atmos helm apply --all --labels cost-center=platform --labels compliance=sox

The native Helm component renders charts in-process with the Helm Go SDK (equivalent to helm template), so atmos helm template works without a cluster or credentials. apply/deploy install or upgrade the release (helm upgrade --install); delete uninstalls it.

Runtime value overrides

template/render, diff/plan, values, and apply/deploy accept Helm-compatible value overrides for a single invocation. They never modify component or stack configuration. Use the same arguments across all three: values to inspect resolved values with sensitive values masked, diff to preview the release changes, and apply to deploy them.

atmos helm diff monitoring -s plat-ue2-dev \
  -f incident-values.yaml \
  --set image.tag=2026.09.09 \
  --set-string annotations.change-ticket=INC-1234

atmos helm apply monitoring -s plat-ue2-dev \
  -f incident-values.yaml \
  --set image.tag=2026.09.09 \
  --set-string annotations.change-ticket=INC-1234

Use repeatable -f/--values, --set, --set-string, --set-file, --set-json, and --set-literal flags. Local files are resolved from the invoking directory; Helm-supported remote value URLs are also accepted. Values follow Helm precedence: component values_files then inline values, followed by CLI value files (in order), --set-json, --set, --set-string, --set-file, and --set-literal.

values accepts exactly one component, but template, diff/plan, and apply/deploy also compose with --all/--affected/--tags/--labels. When combined, the same value overrides are applied identically to every matched component — there is no per-component targeting. Be deliberate with apply --all --set ... (or --affected/--tags/--labels): it broadcasts the override to every release the selection matches.

Native CI Summaries

When ci.enabled: true and CI is detected, or when CI mode is forced with --ci or ATMOS_CI, native Helm commands write a Markdown step summary through Atmos native CI. Helm CI support is summaries-only; it does not write output variables, commit statuses, PR comments, or artifacts.

Supported summaries:

Command	Summary template
template, render	ci.templates.helm.template
diff, plan	ci.templates.helm.diff
apply, deploy	ci.templates.helm.apply
delete, destroy	ci.templates.helm.delete

Summaries include component, stack, command status, a local reproduction command, and Helm metadata such as release name, namespace, chart, target, object counts, object kinds, and rendered manifest size when available. Cluster-backed release summaries also show the effective Helm lifecycle policy. External-target summaries explicitly report that release lifecycle was bypassed.

Release lifecycle

For cluster delivery, apply/deploy and delete expose Helm 4 wait and timeout behavior. Apply/deploy additionally support rollback on failure, ordinary Job waiting, failed-upgrade cleanup, history limits, chart-hook suppression, and CRD skipping. Configure defaults and inherited policy in the stack component, then use command flags only for an explicit invocation override.

See Helm stack release lifecycle, helm apply, and helm delete for the complete field and flag reference.

Chart sources

The chart field accepts three kinds of references:

Local chart

A path relative to the component directory (e.g. chart: . or chart: ./charts/app), or an absolute path.

Remote repository chart

Either repository: https://... plus chart: <name>, or a repo/name reference resolved against merged global and component repositories: entries. Declarative repositories are added/updated in Helm's local repository config before chart operations.

OCI chart

An oci:// reference (e.g. chart: oci://ghcr.io/acme/charts/app).

Values

The component values: map is the Helm chart's values, merged through Atmos inheritance (imports, base components, and overrides). Optional values_files: overlay value files (templated, layered) underneath the inline values. Secret values flow in through Atmos native secrets (the !secret YAML function) and are masked automatically — Helm has no native secrets concept, so Atmos provides it.

components:
  helm:
    monitoring:
      chart: prometheus-community/kube-prometheus-stack
      version: "65.1.1"
      repositories:
        - name: prometheus-community
          url: https://prometheus-community.github.io/helm-charts
      namespace: monitoring
      values:
        grafana:
          adminPassword: !secret grafana_admin_password

List repository associations for Helm components:

atmos helm repo list --stack=ue2-dev
atmos helm repo list monitoring --format=json

Provision targets

Like the Kubernetes component, apply/deploy can deliver the rendered manifests to a provision target instead of a cluster — for example, commit them to a Git deployment repository monitored by ArgoCD:

components:
  helm:
    monitoring:
      # ...
      provision:
        default: cluster
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments
            path: "clusters/{{ .vars.stage }}/monitoring"

atmos helm deploy monitoring -s plat-ue2-dev --target deployment-repo

Subcommands

template

Render the chart to Kubernetes manifests (stdout, files, or a provision target).

diff / plan

Show a unified diff against a baseline — the deployed release, a local manifest, or a GitOps deployment repository.

values

Print final component values as formatted, masked YAML.

apply / deploy

Install or upgrade the release, or deliver rendered manifests to a target.

delete

Uninstall the release.

plugin

Install and list Helm CLI plugins (e.g. helm-secrets) used by helmfile components.