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: Component behavior, inheritance, and base component selection.
vars: Variables available to stack template rendering.
env: Environment variables applied before Helm runs, such as KUBECONFIG.
settings: Integration metadata and legacy dependency settings.
dependencies: 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.

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:

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

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.

stacks/catalog/demo-release.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.

Diffs

atmos helm diff shows a real unified diff (via the embedded 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 component for those.

Example

stacks/catalog/monitoring.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 command reference for the full workflow.

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

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

Available Configuration Sections​

Helm-Specific Sections​

Type-Level Defaults and Overrides​

Helm CLI Plugin Defaults​

Release Lifecycle​

Example​