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 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

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.

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.

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.