# Using Helmfile

Atmos natively supports opinionated workflows for [Helmfile](https://github.com/helmfile/helmfile). Helmfile provides a declarative specification for deploying helm charts.

:::tip 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`](/cli/commands/helm/usage).
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](/cli/commands/helmfile/usage) documentation.

## Stack Configuration

The schema for configuring Helmfile components in Atmos stacks:

```yaml
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:**
  ```yaml
  vars:
    installed: true
    namespace: ingress
    replica_count: 3
  ```
- **`metadata` (optional)**

  The `metadata` section extends functionality of the component. See [Common Component Attributes](/stacks/components#metadata-attributes) for details.

  **Example:**
  ```yaml
  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:**
  ```yaml
  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:

```shell
atmos helmfile diff nginx-ingress --stack=ue2-dev
atmos helmfile apply nginx-ingress --stack=ue2-dev
```

:::note Prerequisite: the `helm-diff` plugin
`atmos helmfile diff`, `apply`, and `deploy` shell out to `helm diff`, so they require the
[`helm-diff`](https://github.com/databus23/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:

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

  See [`atmos helm plugin`](/cli/commands/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:

  ```shell
  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:

```shell
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:

```shell
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.