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