# 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[Read more](/stacks/components/helm)

## Usage

```shell
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.

```shell
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](/stacks/components/helm#release-lifecycle),
[`helm apply`](/cli/commands/helm/apply), and
[`helm delete`](/cli/commands/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.

```yaml
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:

```shell
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:

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

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

## Subcommands

- **[`template`](/cli/commands/helm/template)**
  Render the chart to Kubernetes manifests (stdout, files, or a provision target).
- **[`diff`](/cli/commands/helm/diff) / [`plan`](/cli/commands/helm/plan)**
  Show a unified diff against a baseline — the deployed release, a local manifest, or a GitOps deployment repository.
- **[`values`](/cli/commands/helm/values)**
  Print final component values as formatted, masked YAML.
- **[`apply`](/cli/commands/helm/apply) / [`deploy`](/cli/commands/helm/deploy)**
  Install or upgrade the release, or deliver rendered manifests to a target.
- **[`delete`](/cli/commands/helm/delete)**
  Uninstall the release.
- **[`plugin`](/cli/commands/helm/plugin)**
  Install and list Helm CLI plugins (e.g. 
  `helm-secrets`
  ) used by 
  `helmfile`
   components.