# Helm Components

Define Helm releases in stack manifests when you want Atmos to deploy charts —
local, remote-repository, or OCI — alongside Terraform, Kubernetes, Helmfile,
Packer, and Ansible components. A Helm component describes which chart and
version to use, which values to apply, and how the result should be deployed
for each stack.

## Available Configuration Sections

Helm components use the same stack sections as other Atmos components, so the
release can inherit values, run hooks, use Auth, declare dependencies, and be
included in affected runs.

- **[`metadata`](/stacks/components/component-metadata)**
  Component behavior, inheritance, and base component selection.
- **[`vars`](/stacks/vars)**
  Variables available to stack template rendering.
- **[`env`](/stacks/env)**
  Environment variables applied before Helm runs, such as 
  KUBECONFIG
  .
- **[`settings`](/stacks/settings)**
  Integration metadata and legacy dependency settings.
- **[`dependencies`](/stacks/dependencies/components)**
  Cross-component ordering for 
  \--all
   and 
  \--affected
   runs.

## Helm-Specific Sections

- **`chart` (required)**
  The chart reference: a local path (
  .
   or 
  ./charts/app
  ), a 
  repo/name
   reference, a bare name used with 
  repository
  , or an 
  oci://
   reference.
- **`version`**
  The chart version constraint (for repository and OCI charts).
- **`repository`**
  An explicit HTTP chart repository URL used with a bare 
  chart
   name.
- **`repositories`**
  A list of chart repositories used to resolve 
  repo/name
   chart references. Entries support 
  name
  , 
  url
  , optional basic auth, TLS files, 
  pass_credentials_all
  , and 
  insecure_skip_tls_verify
  . Atmos adds/updates these repositories in Helm's local repository config before rendering or deploying.
- **`namespace`**
  The target Kubernetes namespace. Defaults to 
  default
  .
- **`create_namespace`**
  Whether Helm creates the target 
  namespace
   during install when it does not exist. Defaults to 
  true
  , preserving the existing behavior of creating the configured namespace automatically. Set to 
  false
   to install into a pre-existing namespace instead, for example when a platform component owns the namespace (its labels, quotas, or NetworkPolicies), or when the identity running 
  atmos helm apply
   is scoped to a single namespace and lacks cluster-level permission to create namespaces.
- **`name`**
  The Helm release name. Defaults to the component's last path segment.
- **`values`**
  The Helm chart values, merged through Atmos inheritance. This map 
  is
   the values passed to the chart.
- **`values_files`**
  A list of value files layered 
  underneath
   the inline 
  values
   (templated, in listed order).
- **`render`**
  Default output for 
  atmos helm template
   (
  output.path
   and 
  output.split
  ).
- **`provision`**
  Delivery targets for 
  apply
  /
  deploy
   — the cluster (default) or an external target such as a Git deployment repository.
- **`secrets`**
  Component-scoped secret declarations and providers. Helm components support the same secret processing as other component types.

## Type-Level Defaults and Overrides

The top-level `helm` section in a stack manifest can provide defaults for every
native Helm component in that stack. Use `helm.values` for shared chart values;
component and inherited `values` are merged over those defaults.

Use `helm.overrides` when a stack must enforce values after component-level
configuration is resolved. Type-level overrides are deep-merged over each
component's `overrides`, including components supplied by imported manifests.
The block accepts `values` plus the common component override sections such as
`vars`, `env`, `settings`, `auth`, `secrets`, and `retry`.

```yaml
helm:
  values:
    cluster: shared
  overrides:
    values:
      environment: production

components:
  helm:
    monitoring:
      chart: ./charts/monitoring
      values:
        replicaCount: 2
      overrides:
        values:
          image:
            tag: stable
```

In this example, every Helm component receives `cluster: shared`, while the
stack-level override enforces `environment: production` after component
inheritance and component overrides are merged.

### Helm CLI Plugin Defaults

Use top-level `helm.plugins` to declare Helm CLI plugins for every Helm component,
including components supplied by imported stack files:

```yaml
helm:
  plugins:
    - diff@v3.15.10
```

Plugins are inherited in increasing precedence: `helm.plugins`, base components
from `metadata.inherits`, then the component's own `plugins`. Lists follow the
effective `settings.list_merge_strategy` (default: `replace`). With `replace`, a
component's list replaces inherited plugins, and `plugins: []` clears the list.
Use `append` to combine lists; `merge` uses the existing element-wise list merge
behavior.

These plugins apply to commands passed through to the Helm CLI. Native Helm SDK
operations do not run CLI plugins. Defaults under `helm.plugins` and
`helmfile.plugins` apply only to their respective component types.
See [`atmos helm plugin`](/cli/commands/helm/plugin) for plugin spec syntax.

## Release Lifecycle

Cluster-backed `apply`, `deploy`, and `delete` operations can use Helm 4 release
lifecycle controls under `release`. Configure the tree at the top-level
`helm.release` section as defaults, on an abstract component for inheritance, or
on a concrete component. Atmos first deep-merges that complete tree, then
overlays the selected `install`, `upgrade`, or `delete` section. Explicit command
flags have the highest precedence.

- **`release.wait.strategy`**
  Default:
   
  hookOnly
  . 
  Operations:
   install, upgrade, delete. Select 
  hookOnly
  , 
  watcher
  , or Helm 3-compatible 
  legacy
  .
- **`release.wait.jobs`**
  Default:
   
  false
  . 
  Operations:
   install, upgrade. Wait for ordinary Jobs. Requires 
  watcher
   or 
  legacy
  ; hook Jobs are already handled by Helm hooks.
- **`release.timeout`**
  Default:
   
  0s
   during migration. 
  Operations:
   install, upgrade, delete. Set the release-wide operation timeout. Each operation can override it; explicit 
  0s
   remains unbounded.
- **`release.history.max`**
  Default:
   
  10
  . 
  Operation:
   upgrade. Set the number of revisions retained; use 
  0
   for unlimited history.
- **`release.chart_hooks`**
  Default:
   
  true
  . 
  Operations:
   install, upgrade, delete. Enable Helm chart hooks. This does not control Atmos 
  hooks:
  .
- **`release.install.crds`**
  Default:
   
  create
  . 
  Operation:
   install. Create or skip CRDs from the chart on first install.
- **`release.install.on_failure`**
  Default:
   
  keep
  . 
  Operation:
   install. 
  uninstall
   removes a failed first install; 
  keep
   preserves partial state.
- **`release.upgrade.on_failure`**
  Default:
   
  keep
  . 
  Operation:
   upgrade. 
  rollback
   restores the prior release; 
  keep
   preserves failed state.
- **`release.upgrade.cleanup_on_failure`**
  Default:
   
  false
  . 
  Operation:
   upgrade. Independently remove resources newly created by a failed upgrade.

`release.install.timeout`, `release.upgrade.timeout`, and
`release.delete.timeout` override the release-wide timeout only for that action.
The same operation sections can override `chart_hooks` and `wait`.

:::warning Timeout and history migration
For one minor release, omitting `release.timeout` and the selected operation
timeout preserves the previous unbounded `0s`
behavior and emits a warning. The following minor changes the omitted default to
`5m`. Set `release.timeout: 0s` explicitly to remain unbounded, or set a duration
such as `30m`. An omitted `release.history.max` retains ten revisions; set it to
`0` if unlimited release history is required.
:::

**File:** `stacks/catalog/demo-release.yaml`

```yaml
helm:
  release:
    wait:
      strategy: watcher
    timeout: 10m
    history:
      max: 10

components:
  helm:
    release-policy:
      metadata:
        type: abstract
      release:
        upgrade:
          on_failure: rollback
          cleanup_on_failure: true

    demo-release:
      metadata:
        inherits:
          - release-policy
      chart: ./charts/demo-release
      namespace: demo
      release:
        install:
          timeout: 60m
          on_failure: uninstall
        upgrade:
          timeout: 30m
```

With `dependencies.components`, a successful Helm DAG node means the selected
Helm action completed under this effective policy. `watcher` and `legacy` gate
dependents on resource readiness; `hookOnly` intentionally does not wait for
ordinary chart resources. A failed or rolled-back node remains failed, so its
dependents do not start.

Lifecycle policy applies only to the Kubernetes target. Stored lifecycle values
are ignored and reported as bypassed for external Git delivery; explicitly
passing lifecycle flags with an external target is an error.

Reusable repository defaults can also be configured under
`components.helm.repositories` in `atmos.yaml`. Component-level repositories
override global entries with the same `name`.

:::note Diffs
[`atmos helm diff`](/cli/commands/helm/diff) shows a real unified diff (via the
embedded [helm-diff](https://github.com/databus23/helm-diff) library — no plugin to
install) against the deployed release, a local manifest file, or the manifests in a
`provision` git deployment repository (the offline, GitOps producer-side diff).
Helm CLI **subcommand** plugins such as `helm-secrets` are not run by the native
component — use a [`helmfile`](/stacks/components/helmfile) component for those.
:::

## Example

**File:** `stacks/catalog/monitoring.yaml`

```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
      release:
        timeout: 20m
        wait:
          strategy: watcher
          jobs: true
        history:
          max: 10
        install:
          on_failure: uninstall
        upgrade:
          on_failure: rollback
      values:
        grafana:
          enabled: true
      dependencies:
        components:
          - cert-manager
      provision:
        default: cluster
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments
            path: "clusters/{{ .vars.stage }}/monitoring"
```

See the [`atmos helm`](/cli/commands/helm/usage) command reference for the full
workflow.

To inspect which repositories are associated with Helm components, run:

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