Atmos Helm

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

Native Helm vs. Helmfile

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:

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

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:

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

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.