Skip to main content

Using Helmfile

Atmos natively supports opinionated workflows for Helmfile. Helmfile provides a declarative specification for deploying helm charts.

Native Helm is the simpler default for most Atmos projects

Helmfile has been an important part of the Kubernetes ecosystem, and Atmos has long supported it because it solves real orchestration problems well. Native Helm components build on that same workflow, but bring the common case directly into Atmos: stack-based values, inheritance, secrets, dependencies, hooks, provisioning targets, and CI summaries without an additional orchestration layer.

For most new chart deployments, prefer atmos helm. Keep using Helmfile when you rely on Helmfile-specific capabilities such as advanced multi-release state files, selectors, needs, Helmfile environments, hooks, or Kustomize integration.

For a complete list of supported commands, please see the Atmos helmfile documentation.

Stack Configuration​

The schema for configuring Helmfile components in Atmos stacks:

components:
  helmfile:
    # the slug of the component
    nginx-ingress:

      # configuration specific to atmos
      metadata:
        type: real
        component: nginx-ingress

      # Settings for integrations
      settings: {}

      # Variables passed to Helmfile
      vars:
        installed: true
        namespace: ingress
        chart_version: "4.0.0"

      # Environment variables
      env:
        HELM_DEBUG: "true"

Attributes​

vars (optional)

Variables passed to Helmfile. These are deep-merged and made available to your Helmfile configuration.

Example:

vars:
  installed: true
  namespace: ingress
  replica_count: 3
metadata (optional)

The metadata section extends functionality of the component. See Common Component Attributes for details.

Example:

metadata:
  type: real
  component: nginx-ingress
  inherits:
    - ingress-defaults
settings (optional)

Free-form map for integration configuration.

env (optional)

Environment variables to set when running Helmfile commands.

Example:

env:
  HELM_DEBUG: "true"
  KUBECONFIG: "/path/to/kubeconfig"

Example: Provision Helmfile Component​

To provision a helmfile component using the atmos CLI, run the following commands in the container shell:

atmos helmfile diff nginx-ingress --stack=ue2-dev
atmos helmfile apply nginx-ingress --stack=ue2-dev
Prerequisite: the helm-diff plugin

atmos helmfile diff, apply, and deploy shell out to helm diff, so they require the helm-diff plugin. (atmos helmfile sync does not.) You can satisfy it in either of two ways:

  • Let Atmos manage it — declare the plugin on the component and Atmos installs it into a managed HELM_PLUGINS directory before running helmfile:

    components:
      helmfile:
        nginx-ingress:
          plugins:
            - diff@v3.9.14

    See atmos helm plugin for the full plugin spec syntax.

  • Manage it yourself — if you aren't using the Atmos toolchain, install the plugin with Helm directly:

    helm plugin install https://github.com/databus23/helm-diff

    When a component declares no plugins:, Atmos leaves your HELM_PLUGINS untouched and uses the plugins already installed in your Helm environment.

where:

  • nginx-ingress is the helmfile component to provision (from the components/helmfile folder)
  • --stack=ue2-dev is the stack to provision the component into

Short versions of the command-line arguments can be used:

atmos helmfile diff nginx-ingress -s ue2-dev
atmos helmfile apply nginx-ingress -s ue2-dev

Example: Helmfile Diff​

To execute diff and apply in one step, use helmfile deploy command:

atmos helmfile deploy nginx-ingress -s ue2-dev

Try It​

Explore a complete, working example that deploys Kubernetes resources using Helmfile, against a local Kubernetes emulator.

demo-helmfileView full example
atmos helmfile lifecycle
00:00.0 / 00:00.0

Example: Demo Helmfile

Deploy Kubernetes resources using Helmfile with Atmos stack patterns, against a local Kubernetes emulator (k3s).

Learn more about Helmfile Components.

What You'll See

  • Helmfile component configuration
  • Stack inheritance for Kubernetes deployments
  • A local k3s cluster managed by the native emulator feature (no Docker Compose)
  • The !emulator YAML function wiring KUBECONFIG to the running emulator
  • Toolchain dependencies — Atmos installs helmfile, helm, and kubectl for you

Try It

cd examples/demo-helmfile

# Start the local Kubernetes emulator (k3s)
atmos emulator up kubernetes -s dev

# Deploy to dev (Atmos installs helmfile/helm/kubectl on first run)
atmos helmfile apply demo -s dev

# Check status
atmos emulator ps kubernetes -s dev

# Clean up
atmos emulator down kubernetes -s dev          # stop (ephemeral: cluster is discarded)

Or run the whole round trip in one step:

atmos test

Key Files

FilePurpose
atmos.yamlHelmfile component config + toolchain (Aqua registry, tool aliases)
stacks/catalog/emulator/kubernetes.yamlThe local Kubernetes emulator component (driver: k3s, ephemeral)
stacks/catalog/demo.yamlHelmfile demo component + its helmfile/helm/kubectl tool dependencies
stacks/deploy/dev/demo.yamldev stack — sets KUBECONFIG via !emulator kubernetes kubeconfig
components/helmfile/nginx/Helmfile component with manifests

How the cluster connection works

Helmfile does not integrate with Atmos Auth, so instead of an identity this example consumes the emulator declaratively. The dev stack sets, on the demo component:

env:
  KUBECONFIG: !emulator kubernetes kubeconfig

The !emulator kubernetes kubeconfig function harvests the running emulator's admin kubeconfig to a file and returns its path; Helmfile (and the release's kubectl hooks) pick it up via KUBECONFIG. It resolves at apply time, so the emulator must be up first — atmos emulator up kubernetes -s dev.

The function is scoped to the demo component rather than the stack-global env. atmos emulator up processes the stack with YAML functions enabled, and a stack-global !emulator would deadlock up on the very emulator it is starting.

Toolchain

atmos.yaml declares the Aqua public registry, and the demo component declares helmfile, helm, and kubectl as tool dependencies. On the first atmos helmfile * run, Atmos installs them under .tools/ and puts them on PATH for Helmfile and its hooks — no manual installation required.

Browse all files