Atmos Native Helm Components

Use this skill for the native Helm component type (components.helm). It deploys Helm charts — local, remote-repository, or OCI — through the Helm Go SDK, in-process. No helm or helmfile binary is required. This is a different component type than components.helmfile; see Native Helm vs. Helmfile below before choosing one.

This feature is experimental (IsExperimental() == true in cmd/helm/helm.go).

Related Skills

Need	Load
Helmfile-based deployments (shells out to `helmfile`/`helm`)	atmos-helmfile
Native Kubernetes manifests/Kustomize (no Helm charts)	atmos-kubernetes
Component dependency ordering for `--all`/`--affected`	atmos-components
Secret values in `values:` (`!secret`)	atmos-secrets
GitOps delivery targets (`provision.targets`, `kind: git`)	atmos-git
EKS/cluster authentication	atmos-aws-eks, atmos-auth
Native CI job summaries	atmos-ci

Native Helm vs. Helmfile

	Native Helm (`components.helm`)	Helmfile (`components.helmfile`)
Execution	Helm Go SDK, in-process	Shells out to the `helmfile` and `helm` binaries
Binaries required	None	`helmfile`, `helm` (plus any declared `helm plugin`s)
Multiple releases per component	One chart/release per component	One or more releases per `helmfile.yaml`
Diff engine	Embedded `helm-diff` library (no plugin install)	`helmfile diff` (needs `helm-diff` plugin, installed via `atmos helm plugin`)
Values	`values:`/`values_files:` merged through Atmos inheritance	Varfile generated from stack `vars:`
Status	Experimental	Stable

Use native Helm for straightforward chart deployments where you want no external binaries and first-class GitOps delivery targets. Use Helmfile (atmos-helmfile) for existing helmfile.yaml projects, multi-release releases files, or helm-secrets/other Helm CLI plugins. atmos helm plugin manages plugins for Helmfile components (native Helm does not run Helm CLI subcommand plugins).

Component Shape

Define Helm releases under components.helm in stack manifests:

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
      dependencies:
        components:
          - cert-manager
      provision:
        default: cluster
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments
            path: "clusters/{{ .vars.stage }}/monitoring"

Helm components use the same stack sections as other component types — vars, env, auth, metadata, settings, dependencies, hooks, inheritance, and overrides — plus Helm-specific fields:

Field	Purpose
`chart` (required)	Local path (`.`, `./charts/app`), `repo/name` reference, bare name with `repository`, or `oci://` reference.
`version`	Chart version constraint (repository/OCI charts).
`repository`	Explicit HTTP chart repository URL for a bare `chart` name.
`repositories`	List of chart repositories used to resolve `repo/name` references (`name`, `url`, basic auth, TLS files, `pass_credentials_all`, `insecure_skip_tls_verify`). Merges with global `atmos.yaml` `components.helm.repositories`; component-level entries with the same `name` win.
`namespace`	Target Kubernetes namespace. Defaults to `default`.
`name`	Release name. Defaults to the component's last path segment.
`values`	The chart's values, merged through Atmos inheritance. This map is the values passed to the chart.
`values_files`	Value files layered underneath inline `values` (templated, in listed order).
`render`	Default output for `atmos helm template` (`output.path`, `output.split`).
`provision`	Delivery targets for `apply`/`deploy` — the cluster (default) or an external target such as a Git deployment repository.

Chart sources

Local chart — path relative to the component directory (chart: ., chart: ./charts/app), or absolute.
Remote repository chart — repository: https://... + chart: <name>, or a repo/name reference resolved against merged global/component repositories:. Atmos adds/updates these repositories in Helm's local repository config before chart operations.
OCI chart — an oci:// reference (e.g. chart: oci://ghcr.io/acme/charts/app).

Values and secrets

The component values: map is the Helm values, merged through the normal Atmos import/inheritance chain. values_files: overlay templated value files underneath the inline values. Helm has no native secrets concept — Atmos provides it: secret values flow in through !secret and are masked automatically wherever they'd otherwise be printed (e.g. in atmos helm diff output).

Commands

Command	Purpose
`atmos helm template <component> -s <stack>`	Render the chart to manifests via the Helm Go SDK (equivalent to `helm template`). No cluster or credentials needed. `render` is an alias.
`atmos helm diff <component> -s <stack>`	Real unified diff (embedded helm-diff library — no plugin install) against a baseline. `plan` is an alias.
`atmos helm apply <component> -s <stack>`	Install or upgrade the release (`helm upgrade --install`), or deliver to a `--target` provision target.
`atmos helm deploy <component> -s <stack>`	Alias for `apply`.
`atmos helm delete <component> -s <stack>`	Uninstall the release (`helm uninstall`). No-op if the release does not exist.
`atmos helm repo list [component] -s <stack>`	List declarative repository associations (global, component, or direct) and whether each is used by the resolved `chart`.
`atmos helm plugin list` / `atmos helm plugin install <plugin>...`	Manage Helm CLI plugins in the Atmos-managed `HELM_PLUGINS` directory — for Helmfile components, not native Helm.

All operation commands (template, diff, plan, apply, deploy, delete) accept --all, --affected (with --base/--ref/--sha/--repo-path/--clone-target-ref/--ssh-key/ --ssh-key-password), and --include-dependents, matching atmos describe affected semantics. --all/--affected are mutually exclusive with a positional component argument.

diff baselines

atmos helm diff (alias plan) compares the freshly rendered chart against one baseline, selected by flag precedence --from-manifest → --against → deployed release:

Baseline	Flag	Notes
Deployed release (default)	(none)	Reads the cluster; a nonexistent release shows every object as added. Only mode needing cluster access.
Local manifest	`--from-manifest=<path>`	Fully offline.
Provision target	`--against=target[:<name>]`	The manifests currently published in a non-cluster provision target (e.g. Git deployment repo) — offline, git access only. Without `:<name>` uses `provision.default`.

--context=<n> controls unified-diff context lines (default 3).

template output

atmos helm template writes multi-document YAML to stdout by default. Use --output <file> for a single file, or --output-dir <dir> (with optional --split for one file per object). --output/ --output-dir only work rendering a single component — configure render.output on the component for --all/--affected runs.

Provision Targets (GitOps delivery)

Like native Kubernetes components, apply/deploy can deliver rendered manifests to a provision target instead of the cluster — e.g. committing them to a Git deployment repository reconciled by Argo CD/Flux:

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

--target defaults to provision.default, otherwise the cluster. See atmos-git for the underlying git target mechanics (clone/fast-forward, provenance trailers, credentials from Atmos Auth).

atmos.yaml Configuration

components:
  helm:
    base_path: components/helm          # default: components/helm
    auto_generate_files: false          # render component `generate:` before operations
    repositories:                       # reusable chart repositories, referenced as repo-name/chart-name
      - name: prometheus-community
        url: https://prometheus-community.github.io/helm-charts
      - name: internal
        url: https://charts.example.com
        username: !env HELM_REPO_USERNAME
        password: !env HELM_REPO_PASSWORD
        pass_credentials_all: true

Repository fields: name/url (required), username/password (basic auth), pass_credentials_all, cert_file/key_file/ca_file (TLS), insecure_skip_tls_verify. Component-level repositories entries override global entries with the same name.

Native CI Summaries

When ci.enabled: true and CI is detected (or --ci/ATMOS_CI forces it), Helm commands write a Markdown step summary through Atmos native CI — summaries only (no $GITHUB_OUTPUT, commit statuses, PR comments, or artifacts):

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`

Guidance

Prefer native Helm for new chart deployments that don't need Helm CLI subcommand plugins; use Helmfile for existing helmfile.yaml projects or plugin-dependent workflows (helm-secrets, etc.).
Use atmos helm diff before apply/deploy to review the real unified diff, not just a dry-run dump; secret values are redacted automatically.
Use dependencies.components so --all/--affected runs install/upgrade releases in the right order — Helm itself has no cross-release dependency ordering.
Use !secret for chart values that are sensitive (e.g. adminPassword) instead of plaintext in stack manifests.
Use provision.targets with kind: git to publish rendered manifests to a GitOps deployment repository instead of applying directly to a cluster.
Run atmos helm repo list to confirm which repository a component's chart resolves against before debugging chart-not-found errors.

SKILL.md