Atmos Helmfile Orchestration

Atmos wraps the Helmfile CLI to provide stack-aware orchestration of Kubernetes deployments. Instead of manually managing kubeconfig, variable files, and authentication for each Helmfile component, Atmos resolves the full configuration from stack manifests and handles all of these concerns automatically.

How Atmos Orchestrates Helmfile

When you run any atmos helmfile command, Atmos performs the following sequence:

Resolves stack configuration -- Reads and deep-merges all stack manifests to produce the fully resolved configuration for the target component in the target stack.
Generates variable file -- Writes a varfile containing all vars defined for the component in the stack.
Configures EKS authentication -- If use_eks: true , runs aws eks update-kubeconfig to generate kubeconfig from the EKS cluster and set up authentication.
Executes the requested command -- Runs helmfile diff , apply , sync , destroy , etc. with the generated varfile and any additional flags.

This means a single command like atmos helmfile apply nginx-ingress -s ue2-dev replaces what would normally require multiple manual steps: configuring kubeconfig, writing variable files, and then running helmfile.

Stack Configuration for Helmfile Components

Helmfile components are defined under the components.helmfile section in stack manifests:

components: helmfile: nginx-ingress: metadata: type: real component: nginx-ingress

  settings: {}

  vars:
    installed: true
    namespace: ingress
    chart_version: "4.0.0"

  env:
    HELM_DEBUG: "true"

Component Attributes

vars -- Variables passed to Helmfile. Deep-merged and available to your Helmfile configuration.
metadata -- Extends component functionality. Supports type , component , and inherits for inheritance chains.
settings -- Free-form map for integration configuration.
env -- Environment variables set when running Helmfile commands (e.g., HELM_DEBUG , KUBECONFIG ).

Component Inheritance

Use metadata.inherits to share configuration across components:

components: helmfile: ingress-defaults: metadata: type: abstract vars: chart_version: "4.0.0" replica_count: 2

nginx-ingress:
  metadata:
    type: real
    component: nginx-ingress
    inherits:
      - ingress-defaults
  vars:
    namespace: ingress

Core Commands

diff

Shows what changes would be made without applying them. This is the Helmfile equivalent of a dry-run.

atmos helmfile diff <component> -s <stack>

Basic diff

atmos helmfile diff nginx-ingress -s ue2-dev

Diff with stderr redirection

atmos helmfile diff echo-server -s tenant1-ue2-dev --redirect-stderr /dev/null

apply

Applies Helmfile changes (install/upgrade charts).

atmos helmfile apply <component> -s <stack>

Apply a component

atmos helmfile apply nginx-ingress -s ue2-dev

Apply with stderr redirect

atmos helmfile apply echo-server -s tenant1-ue2-dev --redirect-stderr /dev/stdout

sync

Synchronizes the desired state with the cluster. Installs missing releases, upgrades existing ones, and removes releases that are no longer in the configuration.

atmos helmfile sync <component> -s <stack>

Sync a component

atmos helmfile sync echo-server --stack tenant1-ue2-dev

Sync with stderr redirect

atmos helmfile sync echo-server --stack tenant1-ue2-dev --redirect-stderr ./errors.txt

destroy

Removes all releases managed by a component.

atmos helmfile destroy <component> -s <stack>

Destroy a component

atmos helmfile destroy echo-server --stack=tenant1-ue2-dev

Destroy with stderr redirect

atmos helmfile destroy echo-server --stack=tenant1-ue2-dev --redirect-stderr /dev/stdout

deploy

Combines diff and apply in a single step.

atmos helmfile deploy <component> -s <stack>

atmos helmfile deploy nginx-ingress -s ue2-dev

Variable File Generation

Atmos generates variable files from the vars section in the stack configuration. This happens automatically before Helmfile commands, but can also be invoked manually:

atmos helmfile generate varfile <component> -s <stack>

Output to a custom file

atmos helmfile generate varfile echo-server -s tenant1-ue2-dev -f vars.yaml

With explicit stack flag

atmos helmfile generate varfile echo-server --stack tenant1-ue2-dev --file=vars.yaml

Source Management (JIT Vendoring)

Helmfile components support just-in-time (JIT) vendoring through the source field. Instead of pre-vendoring components or maintaining separate component.yaml files, declare the source inline in stack configuration.

Configuring a Source

Sources can be declared in two formats:

String format (simple):

source: "github.com/cloudposse/helmfiles//releases/ingress-nginx?ref=1.0.0"

Map format (full control):

components: helmfile: ingress-nginx: source: uri: github.com/cloudposse/helmfiles//releases/ingress-nginx version: 1.0.0 included_paths: - ".yaml" - "values/**" excluded_paths: - ".md" - "tests/**" vars: namespace: ingress-nginx

Automatic Provisioning

Sources are automatically provisioned when running any Helmfile command. If a component has source

configured and the target directory does not exist, Atmos downloads the source before running Helmfile:

Source is automatically provisioned on first use

atmos helmfile sync ingress-nginx --stack dev

-> Auto-provisioning source for component 'ingress-nginx'

-> Auto-provisioned source to components/helmfile/ingress-nginx

-> Helmfile runs

Source Commands

Explicit commands for fine-grained source management:

Pull (vendor) a component source

atmos helmfile source pull ingress-nginx --stack dev

Force re-vendor (overwrite existing)

atmos helmfile source pull ingress-nginx --stack dev --force

Pull with identity override for private sources

atmos helmfile source pull ingress-nginx --stack dev --identity admin

View source configuration

atmos helmfile source describe ingress-nginx --stack dev

List all components with source configured

atmos helmfile source list --stack dev

List across all stacks

atmos helmfile source list

List in different output formats

atmos helmfile source list --format json

Delete vendored source (requires --force)

atmos helmfile source delete ingress-nginx --stack dev --force

Version Pinning per Environment

Override the source version per environment using stack inheritance:

stacks/catalog/ingress-nginx/defaults.yaml

components: helmfile: ingress-nginx/defaults: source: uri: github.com/cloudposse/helmfiles//releases/ingress-nginx version: 1.0.0

stacks/dev.yaml

components: helmfile: ingress-nginx: metadata: inherits: [ingress-nginx/defaults] source: version: 1.1.0 # Override version for dev

stacks/prod.yaml

components: helmfile: ingress-nginx: metadata: inherits: [ingress-nginx/defaults] source: version: 1.0.0 # Pin to stable version for prod

Supported Source Protocols

The source provisioner uses go-getter and supports multiple protocols:

Git -- github.com/org/repo//path or git::https://github.com/org/repo.git//path
S3 -- s3::https://s3-us-east-1.amazonaws.com/bucket/path.tar.gz
HTTP/HTTPS -- https://releases.example.com/helmfiles/component-1.0.0.tar.gz
OCI -- oci::registry.example.com/helmfiles/component:v1.0.0
GCS -- Google Cloud Storage URIs

Retry Configuration

Configure retries for transient network errors:

source: uri: github.com/cloudposse/helmfiles//releases/ingress-nginx version: 1.0.0 retry: max_attempts: 5 initial_delay: 2s max_delay: 60s backoff_strategy: exponential

EKS Integration

Atmos can automatically manage kubeconfig for Amazon EKS clusters before running Helmfile commands.

Configuration in atmos.yaml

components: helmfile: base_path: components/helmfile use_eks: true kubeconfig_path: /dev/shm cluster_name_template: "{{ .vars.namespace }}-{{ .vars.environment }}-{{ .vars.stage }}-eks"

Configuration Options

command -- Executable to run (default: helmfile ). Env: ATMOS_COMPONENTS_HELMFILE_COMMAND .
base_path -- Directory containing Helmfile components. Env: ATMOS_COMPONENTS_HELMFILE_BASE_PATH .
use_eks -- Enable EKS integration (default: false ). Env: ATMOS_COMPONENTS_HELMFILE_USE_EKS .
kubeconfig_path -- Directory for kubeconfig files. Use /dev/shm for security. Env: ATMOS_COMPONENTS_HELMFILE_KUBECONFIG_PATH .
cluster_name -- Explicit EKS cluster name. Env: ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME .
cluster_name_template -- Go template for dynamic cluster names (recommended). Env: ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME_TEMPLATE .

Cluster Name Precedence

--cluster-name flag (highest priority)
cluster_name configuration
cluster_name_template expanded with Go templates
cluster_name_pattern expanded with token replacement (deprecated)

Non-EKS Kubernetes Clusters

For non-EKS clusters (k3s, GKE, AKS, etc.), disable EKS integration and use existing kubeconfig:

components: helmfile: base_path: components/helmfile use_eks: false # Use existing KUBECONFIG

Path-Based Component Resolution

You can use filesystem paths instead of component names:

Navigate to component directory and use current directory

cd components/helmfile/echo-server atmos helmfile diff . -s dev atmos helmfile apply . -s dev

Use relative path

cd components/helmfile atmos helmfile sync ./echo-server -s prod

From project root

atmos helmfile apply components/helmfile/echo-server -s dev

Combine with other flags

cd components/helmfile/echo-server atmos helmfile diff . -s dev --redirect-stderr /dev/null atmos helmfile sync . -s dev --global-options="--no-color"

Path resolution only works when the component path resolves to a single unique component in the stack. If multiple components reference the same path, use the explicit component name instead.

Global Options

Pass global Helmfile options using the --global-options flag:

atmos helmfile apply nginx-ingress -s dev --global-options="--no-color --namespace=test"

Use double-dash -- to separate Atmos flags from native Helmfile flags:

atmos helmfile sync echo-server -s dev -- --concurrency=1

Common Flags

Flag Short Description

--stack

-s

Target Atmos stack (required)

--dry-run

Preview without executing

--redirect-stderr

Redirect stderr to file or descriptor

--global-options

Pass global options to Helmfile

--cluster-name

Override EKS cluster name

--identity

Override authentication identity

Debugging

Describe Component

Use atmos describe component to see the fully resolved configuration:

atmos describe component nginx-ingress -s ue2-dev

This shows all merged vars, metadata, settings, and env for the component.

Dry Run

Preview what Atmos will do without executing:

atmos helmfile apply nginx-ingress -s dev --dry-run

Helm Debug Logging

Set HELM_DEBUG in the component env:

components: helmfile: nginx-ingress: env: HELM_DEBUG: "true"

Best Practices

Use diff before apply. Run helmfile diff first, review the output, then run helmfile apply

to ensure exactly the reviewed changes are applied.

Use deploy for combined operations. The deploy command runs diff and apply in a single step.

Store kubeconfig in /dev/shm . When using EKS integration, use shared memory for security since files are not persisted to disk.

Use cluster_name_template instead of cluster_name_pattern . The Go template syntax is more powerful and the token replacement pattern is deprecated.

Use source-based version pinning for multi-environment setups. Override the source.version

per environment to control which version is deployed to each stack.

Use atmos describe component to debug configuration resolution issues. It shows the fully merged result of all stack manifest inheritance.

Leverage component inheritance to share common configuration across Helmfile components and reduce duplication in stack manifests.

Additional Resources

For the complete list of all atmos helmfile subcommands, see references/commands-reference.md

atmos-helmfile

Safety Notice

Copy this and send it to your AI assistant to learn