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.

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

Declare Helmfile plugins in the component's stack configuration; Atmos ensures them before running Helmfile. See Helmfile plugin configuration for declarations and optional cache warming. Do not add a plugin installation prerequisite to native Helm commands.

When maintaining plugin support, extend the existing generic installer in pkg/helm/plugin. Let Helm run each plugin's installation hooks. Keep plugin requirements with the consuming component or engine; a built-in alias such as diff does not justify a separate downloader or shell wrapper.

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`.
`create_namespace`	Whether Helm creates the target `namespace` during install when missing. Defaults to `true` (existing behavior). Set `false` to install into a pre-existing namespace, e.g. when a platform owns the namespace or a namespace-scoped identity (CI) cannot create namespaces.
`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 values <component> -s <stack>`	Print the fully resolved chart values as formatted, masked YAML. Accepts the same Helm CLI value overrides as rendering operations.
`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.

Render and lifecycle 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).

Runtime value overrides

template/render, diff/plan, values, and apply/deploy accept repeatable Helm-compatible -f/--values, --set, --set-string, --set-file, --set-json, and --set-literal flags. They are invocation-only and override component values_files then inline values; use the same flags with values, diff, and apply to inspect, preview, and deploy identical inputs.

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