Native Helm releases in Atmos now capture that evidence at the moment of failure and fold it straight into the error: which pod is failing, what the container is reporting, and - at debug level - the crash log and recent events.

The Problem​

A failed readiness wait tells you that a release did not come up, but not why. The error names the release and namespace, yet the actual cause - a CrashLoopBackOff, an ImagePullBackOff from a bad registry mirror, a container exiting non-zero on a bad config value - lives on the pods, not in the release record.

So the cause is one kubectl session away. Except:

• In CI there is usually no interactive cluster access, so the run just fails with a timeout and no cause.
• When a release is configured to roll back or uninstall on failure, that recovery deletes the failing pods first. By the time anyone looks, the pod - and its logs - are gone.

The result is a dependency-ordered rollout that stops at a release nobody can diagnose from the output alone.

The Fix​

On a release failure, and before any rollback or uninstall runs, Atmos now enumerates the release's pods, finds the not-ready containers, and appends their diagnostics to the same error:

Error: failed to perform helm release operation
  workload diagnostics:
    pod keda-operator-7d9f  keda-operator CrashLoopBackOff (exit 1, 5 restarts)
      last log (keda-operator):
        panic: failed to load config: invalid duration "5x"
      events:
        BackOff  Back-off restarting failed container

The container-status summary (reason, exit code, restart count) is always included on failure. The log tail and the pod's recent events are added when you run at debug or trace level, so normal output stays concise.

To guarantee the evidence survives, Atmos now performs the configured on_failure rollback or uninstall itself, after collecting the diagnostics rather than before - the rollback and history-retention behavior you configure is unchanged, it just no longer races the diagnostics.

How to Use It​

There is nothing to enable. Any native Helm apply or deploy that fails readiness surfaces the diagnostics automatically. To include the log tail and events, raise the log level:

atmos helm apply keda -s plat-ue2-prod --logs-level=Debug

Diagnostics are best-effort: if the cluster cannot be reached, Atmos reports the original failure unchanged rather than masking it.

Get Involved​

This pairs with the native Helm release lifecycle controls. If there is a failure signal you want surfaced that Atmos does not yet capture, open an issue or discussion on GitHub.

Native Helm components now expose the two Helm 4 controls that resolve this - server_side_apply and force_conflicts - as release-policy settings and command-line flags, so a conflict clears in the normal atmos helm apply path.

The Problem​

Helm 4 applies release manifests with server-side apply by default, so field ownership is shared with any other actor that writes the same fields. Two situations routinely put another manager on a field a release also declares:

• A controller continuously reconciles an object it also received from a release, and takes ownership of fields the release sets.
• An object's managedFields ledger is orphaned - for example, a custom resource whose CRD hosts a conversion webhook loses its ledger when a conversion fails during a controller disruption. The next apply synthesizes a stand-in manager that owns the pre-existing fields, and a later release apply that changes those fields conflicts with it.

In both cases the apply reports a conflict and the install or upgrade aborts. Because Atmos set no conflict-resolution option, there was no way to clear it through the deploy path: you had to repair the object out of band and re-run. That breaks dependency-ordered rollouts, cannot be remediated in CI, and hid a control Helm 4 already implements.

The Fix​

Two keys are added to the native Helm release policy, alongside the existing wait, timeout, history, install, and upgrade controls:

components:
  helm:
    my-component:
      release:
        # Apply method. Omit to use the Helm default.
        server_side_apply: true
        # Resolve field-ownership conflicts by overwriting the contested
        # fields and becoming their sole manager. Opt-in; default false.
        force_conflicts: false

With force_conflicts enabled, a release apply that meets a field owned by another manager overwrites the contested fields and becomes their sole owner, so the release reaches a successful completion state and its dependents proceed. It is opt-in by design: forcing overrides other managers, so a controller that legitimately co-owns a field loses it on the next apply. That trade-off is yours to make per component, which is why the default leaves conflicts fatal and visible.

server_side_apply accepts auto, true, or false. Omitting it preserves the Helm default - server-side apply on install, and the prior release's method on upgrade - so a release that sets neither key behaves exactly as before.

Both settings resolve through the same path as the rest of the release lifecycle: stack type defaults, base-component inheritance, concrete component configuration, and command-line override. A release-wide value is the common case, and the per-phase install and upgrade blocks can override it when first install and later upgrades need different behavior. The configured values are validated before any chart download or cluster mutation.

How to Use It​

Set the policy in a stack for steady-state behavior, or force a single recovery apply from the command line without editing configuration:

# One-off recovery: take ownership of the contested fields and continue.
atmos helm apply my-component -s plat-ue2-prod --force-conflicts

# Override the apply method for this run (a bare flag selects true).
atmos helm apply my-component -s plat-ue2-prod --server-side-apply=false

The --force-conflicts and --server-side-apply flags are available on apply and deploy, and take precedence over stack release configuration.

Get Involved​

See the native Helm release lifecycle documentation for the full policy reference. If you hit a server-side apply scenario this does not cover, open an issue or discussion on GitHub - we would like to hear about it.

The Problem​

atmos scaffold generate --update and atmos init --update compute a three-way merge for every file the template still generates: what changed upstream, layered onto what you've customized locally. But that merge only ever ran for files that exist on both sides. Two real gaps followed from that:

• When the template stopped generating a file, --update never noticed. The stale file just sat there, untouched, on every future update, forever.
• When you deleted a file yourself — because you didn't need it, or you'd replaced it with something else — the next --update silently wrote it straight back, as if your deletion had never happened.

The Fix​

--update-strategy=rendered now detects a file the template stopped generating and removes it, but only when your copy still matches exactly what the template last produced. If you'd edited that file since, --update doesn't guess: it surfaces an unresolved conflict instead, the same way a genuine merge conflict does, so you decide whether to keep it or let it go. --update-strategy=tracked can't offer this part safely — there's no reliable way to know which files in your project's own git history actually belonged to the template versus anything else that happened to live there.

Independently of strategy, --update also stops silently overwriting a deletion you made yourself. Both tracked and rendered now check whether a file was previously generated before recreating it, and leave your deletion in place if so. Pass --recreate-deleted to opt back into the old always-recreate behavior — it's deliberately its own flag rather than folded into --force, since --force already means "the template's version wins" for merge conflicts, and tying file recreation to it would make "resolve conflicts manually" and "recreate what I deleted" mutually exclusive. --force does, however, now resolve a deletion conflict the same way it resolves any other: if the template removed a file you'd since edited, --force deletes it anyway instead of leaving you stuck with a conflict only manual cleanup could clear.

How to Use It​

# A file the template no longer generates is removed automatically on --update,
# as long as you haven't edited it -- otherwise you'll get a conflict to resolve.
atmos scaffold generate my-template ./my-project --update --update-strategy=rendered

# Recreate a file you deleted instead of leaving the deletion in place.
atmos scaffold generate my-template ./my-project --update --recreate-deleted

# Force past a deletion conflict -- the template's choice (delete it) wins.
atmos scaffold generate my-template ./my-project --update --update-strategy=rendered --force

Get Involved​

See the atmos scaffold generate and atmos init docs for the full flag reference. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Small pieces of reference data — license choices, region codes, a naming convention lookup — show up constantly in real scaffold templates, and they rarely stay confined to one field. A select field needs them as {label, value} options; a file elsewhere in the same template needs the raw table to look values up by key. Duplicating that table by hand, once per field that needs it, means every future edit has to find and update every copy — and a missed one quietly drifts out of sync with the rest. Beyond reference data, templates also commonly need small dynamic values — the user's git branch or commit SHA, an environment variable, a random suffix for a resource name — with no way to derive any of them automatically.

The Fix​

scaffold.yaml now resolves a set of Atmos YAML functions — the same explicit-tag mechanism stack manifests already use — anywhere it currently accepts a literal value: options:, a type: computed field's value:, or a matrix: axis.

• !include/!include.raw pulls in a local or remote file, optionally reshaped with a YQ filter.
• !env reads an environment variable, !random generates a random number, and !cwd reads the current working directory.
• The !git.*/!repo-root family exposes the current git branch, commit SHA, repository name, and more.
• !literal preserves a value exactly as written, bypassing scaffold's own template evaluation — useful when a value legitimately contains {{ }} and shouldn't be treated as a template expression.

spec:
  fields:
    - name: license
      type: select
      options: !include "./lib/licenses.yaml '. | to_entries | map({\"label\": .value.full_name, \"value\": .key})'"

    - name: license_lookup
      type: computed
      value: !include ./lib/licenses.yaml

    - name: branch
      type: computed
      value: !git.branch

A locally-included file that exists solely to be included is automatically excluded from generated output, the same way scaffold.yaml itself is. atmos scaffold validate resolves everything too, not just generate, so a missing file, a bad filter, or a malformed value is caught up front.

Not every YAML function is available here: anything that needs real stack, component, or backend context (!terraform.state, !store, !secret, and similar) is rejected with a clear error instead. A template's scaffold.yaml is often resolved just to show its name and description in atmos scaffold list or the interactive picker — before a user has chosen or generated anything — so only functions that are safe to run in that situation are supported.

The !exec function is excluded for a different reason: it needs no stack context at all, but scaffold.yaml is resolved for every template configured in atmos.yaml just to populate the list and picker, not only the one a user actually generates — so allowing shell execution there would let any configured template, including a shared or vendored one, run arbitrary code merely by being listed.

How to Use It​

Add any of the functions above anywhere options:, a computed field's value: (see Computed Fields), or a matrix axis currently accepts a literal value. See the full examples/scaffolding-yaml-functions example, or the Loading External Data with !include and Other YAML Functions section of the atmos scaffold generate docs.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

By default, --use-mocks now treats mocks as fallbacks. Real state wins whenever it exists, and a mock fills in only for a component that has not been provisioned or an output that is missing.

The Problem​

Mocks were designed to let a plan or describe component run before its dependencies exist. In practice, a stack is usually partly deployed. Turning mocks on replaced every !terraform.state and !terraform.output lookup with literal values, so a plan against a half-built environment showed fake IDs for resources that already had real ones. The only alternative was to turn mocks off and fail on the components that were not there yet.

The Fix​

The behavior is configurable. In the new default fallback mode, each lookup resolves in this order:

1. The real value, when the referenced component's state exists and declares the output.
2. The component's mock, when the state is not provisioned or the output is missing.
3. A YQ // default in the expression, if one is present.
4. The same result as without mocks: the not-provisioned error for a component that was never applied, or null for an output missing from applied state.

Mocks never hide real problems. Credential, network, and backend failures still fail the command instead of quietly returning a mock value. As before, only atmos terraform plan and atmos describe component accept --use-mocks; every other Terraform subcommand, such as apply, deploy, and destroy, rejects it. Map outputs are merged: a mock fills keys that are missing from a real map output, while every value present in real state wins.

The other mode, always, keeps the previous behavior for lookups that must not depend on what is deployed, such as describing a component on a machine without cloud credentials. In always mode, !terraform.state and !terraform.output lookups resolve from mocks only and never initialize Terraform, authenticate, or read a backend for the components they reference. A plan still runs Terraform against the component being planned, with that component's own backend and provider credentials. Choose the mode per run with the flag, or set a project default with mocks.mode, as shown below.

How to Use It​

Declare mocks on the producer component as before:

components:
  terraform:
    vpc:
      mocks:
        vpc_id: vpc-local
        private_subnet_ids: [subnet-a, subnet-b]

    app:
      vars:
        vpc_id: !terraform.state vpc vpc_id

Then pick the mode per run, or set a project default:

# Real state where it exists, mocks for the gaps.
atmos terraform plan app -s dev --use-mocks

# Lookups use mocks only, with no backend reads or credentials for them.
# The plan itself still uses app's own backend and provider credentials.
atmos terraform plan app -s dev --use-mocks=always

components:
  terraform:
    mocks:
      mode: always   # fallback (default) | always

The mocks.mode setting can also be set with ATMOS_COMPONENTS_TERRAFORM_MOCKS_MODE. Attach a mode to the flag with =, because --use-mocks always does not select one. An explicit mode passed with the flag, such as --use-mocks=fallback or --use-mocks=always, wins over the environment variable, which wins over atmos.yaml. A bare --use-mocks turns mocks on and keeps the configured mode.

Upgrading​

This changes what a bare --use-mocks does, so the new default is tied to config editions. Projects pinned to an edition before 2026-10-01 keep the previous mocks-only behavior with no changes. Unpinned projects, and projects that move their edition forward, get the fallback behavior. To keep mocks-only regardless of edition, set mocks.mode: always or pass --use-mocks=always.

See resolution modes for the full details.

Get Involved​

Try the provider-free component mocks example, which walks through both the fallback and always flows. Questions and feedback are welcome in GitHub Discussions or the SweetOps Slack.

The Problem​

Just-in-time access is the right default for privileged roles, but the activation step lands on the operator every single session, outside the tool they actually came to use. You want to run a plan against production; first you have to remember the role definition id, the scope, a justification, and the sequence of REST calls to turn your eligibility into an active assignment - and redo it when the window expires. Worse, nothing downstream benefits from a single place that performs the elevation: the credential your tooling consumes is the same either way, so there is no natural seam to hang "activate my role, then run" on. Atmos already modeled the two things this needs - becoming something more privileged through identity chaining, and credential time-boxing - but Azure only had the azure/subscription identity. There was no way to express the elevation at all.

The Fix​

A new azure/pim-role identity chains from an existing Azure identity and, on authentication, runs the Azure Resource Manager PIM self-activation for a role you are eligible for - scoped and time-boxed by config. Because the elevation lives in the identity chain, every consumer inherits it with no extra wiring: atmos terraform, atmos auth exec, the AKS kubeconfig exec plugin, and MCP servers all just see the role active.

Unlike assuming a role, azure/pim-role mints no new credentials. Azure RBAC evaluates roles by object id at request time, not as token claims, so the activation elevates the principal you already authenticated as - server-side - and the identity hands back the parent credentials unchanged, now carrying the active role. That is what lets it sit transparently anywhere in a chain.

It is also careful about not being noisy:

• It does not re-request on every command. If an active assignment already covers the scope, it returns immediately instead of filing another request and tripping PIM throttling.
• It resumes instead of duplicating. If a request for the same role and scope is already waiting on an approver, a later run attaches to that pending request rather than starting a new one.
• It refuses clearly when it cannot proceed. A missing eligibility is reported as "not eligible" (this activates an eligibility, it does not grant one), distinct from an activation that failed. In a non-interactive context with no justification, it fails fast and tells you how to supply one.

How to Use It​

Add a azure/pim-role identity that elevates from an identity you already have:

auth:
  identities:
    azure-dev:
      kind: azure/subscription
      via:
        provider: azure-interactive
      principal:
        subscription_id: "00000000-0000-0000-0000-000000000000"

    prod-contributor:
      kind: azure/pim-role
      via:
        identity: azure-dev          # elevate from who I already am
      principal:
        role_definition_id: "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c"
        scope: "/subscriptions/00000000-0000-0000-0000-000000000000"
        duration: "8h"               # converted to ISO-8601; Azure enforces the role's policy maximum
        justification: "planned change window"

Then authenticate or run as usual - the role activates as part of the chain:

atmos auth login --identity prod-contributor
atmos auth exec --identity prod-contributor -- terraform plan

Need a different reason for a specific run? Pass the --justification global flag (or set the ATMOS_AUTH_JUSTIFICATION environment variable) - it overrides the configured default:

atmos auth exec --identity prod-contributor --justification "incident INC-123" -- terraform apply

In a non-interactive context (CI, a running MCP server) with no justification available at all, the login fails fast and tells you to pass --justification or set ATMOS_AUTH_JUSTIFICATION. If a role requires approval, the login bounds its wait and shows progress; a later invocation picks up the pending request instead of starting over.

This covers Azure resource roles. Entra directory roles and PIM for Groups activate through different APIs and will be separate identity kinds.

Get Involved​

The azure/pim-role identity is part of the broader Atmos Auth effort to make least-privilege, just-in-time access something you configure once and forget. If you run PIM in Azure, try it against an eligible role and let us know how it fits your workflow in GitHub Discussions.

The Problem​

atmos scaffold generate --update and atmos init --update compute a three-way merge for every existing file: what changed in the template, layered onto what you've customized locally. If that merge would touch more than 50% of a file's lines, it bails out entirely — no conflict markers, no partial result, just a hard failure and the file left untouched. That 50% ceiling was hardcoded, with no flag to raise it, even though a large conflict is often exactly the kind of thing a person wants surfaced for manual review rather than blocked outright.

The Fix​

--max-changes on both commands controls that same conflict-percentage threshold. The default stays 50 — no behavior change if you don't pass it. 0 disables the check entirely: the merge always proceeds and writes conflict markers for you to resolve, instead of refusing the update.

One nuance worth understanding before you reach for a specific number: the change percentage this is compared against isn't itself capped at 100. When your local edits and the template's changes both diverge significantly from the common base, the computed percentage can climb well past 100% (200%+ in some cases). That means only --max-changes=0 is a guaranteed "never fail on this" setting — raising it to 100, 200, or higher only makes a hard failure progressively less likely, it doesn't rule one out. If what you actually want is "always give me conflict markers, never a hard failure," reach for 0, not a large number.

How to Use It​

# Default behavior is unchanged: fails if a merge would touch more than 50% of a file.
atmos scaffold generate my-template ./my-project --update

# Always get conflict markers instead of a hard failure.
atmos scaffold generate my-template ./my-project --update --max-changes=0
atmos init --update --max-changes=0

# Or configure it once via environment variable.
ATMOS_SCAFFOLD_MAX_CHANGES=0 atmos scaffold generate my-template ./my-project --update
ATMOS_INIT_MAX_CHANGES=0 atmos init --update

Get Involved​

See the atmos scaffold generate and atmos init docs for the full flag reference. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Exception capture previously depended on configuring a separate Sentry destination. Enabling Atmos Pro for a stack did not automatically send CLI exceptions to Pro, leaving failures disconnected from the execution records already uploaded there.

The Fix​

The automatic Pro exception reporter sends failures from GitHub Actions when the effective settings.pro.enabled is true, using fresh GitHub OIDC credentials and the configured Pro base URL. Separately configured Sentry destinations continue to receive events with the same IDs and fingerprints.

Resolved component metadata, including inherited stack defaults, becomes unprefixed Sentry tags. A production presence tag becomes production: "true"; a team: platform label becomes team: "platform". Events also include stack/component identity and the execution ID used by Pro uploads, with Atmos's existing masking applied.

How to Use It​

Enable Pro in atmos.yaml for invocation-wide reporting, or use the existing stack/component Pro setting:

settings:
  pro:
    enabled: true

Grant the GitHub Actions workflow id-token: write permission:

permissions:
  contents: read
  id-token: write

Upgrade behavior: existing stacks with settings.pro.enabled: true now send CLI exceptions automatically in eligible GitHub Actions runs. To retain the previous behavior while keeping other Pro features, explicitly opt out:

settings:
  pro:
    enabled: true
    errors:
      enabled: false

The ATMOS_PRO_ERRORS_ENABLED=false environment override also disables reporting and takes precedence over component settings. Edition pins do not suppress this new behavior. Reporting failures preserve the command's exit code, with a two-second delivery timeout and a shared two-second shutdown flush.

The CLI contract covers successful ingestion and authentication rejection; Pro's provider verification and persisted-tag assertions are tracked in issue #3219.

Get Involved​

See the reporting configuration and tag precedence for details, and open an issue with feedback about exception reporting.

Enable toolchain.frozen_lock_file: true in CI and security-sensitive environments to reject those missing entries and prevent lockfile writes. That way, you can prepare and review lockfile updates before running CI.

This update makes project configuration consistent across invocation directories and keeps automatic installs from changing declared dependencies. The same project paths and declarations apply whether a developer or CI runs the command.

The Problem​

Relative toolchain paths could follow the directory where you invoked Atmos. A command run from a component directory could therefore look for a different version manifest or use a different installation directory than the same command run from the project base.

Automatic installation also used the declaration-writing behavior of an explicit install command. Running an infrastructure command could leave a change in .tool-versions, even though you had not asked to change the project's dependencies.

The Fix​

Toolchain paths now resolve from the configured project base, and automatic installs leave declared versions unchanged.

For example, with /work/infra as the configured project base, Atmos reads /work/infra/.tool-versions even when invoked from /work/infra/components/vpc. A configured install_path: .tools resolves to /work/infra/.tools from either directory. The same rule applies to relative versions_file and lock_file settings.

Binaries still use shared XDG cache storage by default. When Atmos installs a version of itself outside a project, it now keeps installation metadata there too, unless you explicitly override the installation path.

How to Use It​

Existing projects get the path and declaration fixes without adding configuration. Continue running your usual Atmos commands; when they need to install a tool automatically, the project's declarations remain unchanged. Use explicit toolchain management commands when you intend to add or change those declarations.

Use the toolchain environment overrides to select a different manifest or installation directory without editing project configuration. For example, ATMOS_TOOLCHAIN_INSTALL_PATH=/shared/atmos-tools atmos toolchain install installs binaries in the supplied directory even when invoked outside the project.

Automatic installs can still update resolved artifact metadata in the existing toolchain.lock.yaml: they record missing version or platform entries after successful installation, preserve matching entries, and fail on checksum mismatches. The distinction is between declaring a dependency and recording the artifact used to satisfy it. See automatic installation and lockfiles for details.

Compatibility​

If you relied on toolchain paths relative to the invocation directory, adjust them relative to the project base or use absolute paths. These behavior fixes apply to every config edition; pinning an older edition does not restore the earlier path or declaration-writing behavior.

The existing lockfile defaults still depend on your edition. Editions before 2026-08-05 retain use_lock_file: false; set it explicitly to enable ordinary lockfile use. Frozen mode remains opt-in and requires verification regardless of that setting.

Get Involved​

Try running your existing commands from a project subdirectory and check that automatic installs leave .tool-versions unchanged. Share any unexpected behavior in GitHub Discussions.

The Problem​

Templating and scaffolding tools all hit the same shape of problem eventually: a value the generated output needs isn't something the user should be prompted for at all — it's derived from answers they already gave. Ask for a list of regions, then only ask for a primary region when there's more than one; when there's exactly one, it's the primary by definition, no prompt needed. That derivation logic is simple once, but a scaffold template has no single place to put it. It gets pasted into every file that references the value, and every copy has to independently stay in sync with the same conditional. Miss one, or get the fallback logic subtly wrong in one file, and that file quietly disagrees with the rest of the generated project.

The Fix​

A new type: computed field declares a value once — either derived from other answers via a value: Go-template expression, or a plain literal (string, number, boolean, list, or map) used as-is — and is never itself prompted for or settable with --set. A string is only treated as an expression when it actually contains a template action; a plain string like hello is a literal too, same as any other type:

spec:
  fields:
    - name: regions
      type: multiselect
      options: [us-east-1, us-west-2, eu-west-1]
    - name: primary_region_select
      type: select
      options: answers.regions
      when: "size(answers.regions) > 1"
    - name: primary_region
      type: computed
      value: "{{ ternary answers.primary_region_select (index answers.regions 0) (gt (len answers.regions) 1) }}"

primary_region derives its value exactly once, and .Config.primary_region is then usable everywhere .Config is — file content, target: path templates, and matrix: axes — with no per-file fallback logic to keep in sync. Computed fields evaluate in declaration order, after every regular field's answer is already final, so a computed field can reference any regular field regardless of where it's declared, and any earlier-declared computed field's own result.

A computed field's value: doesn't have to be an expression at all — a plain literal works too, useful for a small hand-authored reference table shared across every file in the template:

- name: provider_version_pins
  type: computed
  value: {aws: "~> 5.0", azurerm: "~> 3.0", google: "~> 5.0"}

provider_version_pins is stored exactly as written, with no template rendering, and is reachable the same way as any other computed field: .Config.provider_version_pins.

How to Use It​

Add a type: computed field to any existing scaffold.yaml, following the shape above, and reference its name from .Config in any file the template generates:

atmos scaffold generate <template> <target> --set regions=us-east-1,us-west-2

See the Computed Fields section of the atmos scaffold generate docs for the full set of validation rules (value: is required on a computed field and rejected on every other type; required:/default: are both rejected on a computed field) and the ordering constraints that keep a computed field's dependencies resolvable.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

The Problem​

The matrix: field already expands a single declared file into one generated file per selected value — pick three environments, get three files, from one template file. But real templates aren't single files; they're whole directories. A components/ tree with a dozen resources that needs to exist under every environment couldn't be matrixed as a unit — only file by file, one spec.files[] entry per file, each with its own repeated matrix: and target:. Skipping a directory recursively (docs that only ship when an answer opts in, a cloud-specific subtree that only applies to one provider) had the same problem in miniature: one when:-gated entry per file, duplicated across every file the directory contained.

The Fix​

The spec.files[].path field can now be a glob pattern instead of a literal path — *, ?, [...], ** for any depth, and {a,b} brace expansion — matched against every file the template discovers. One entry now covers an entire directory:

spec:
  files:
    - path: "docs/legacy/**"
      when: "answers.include_legacy_docs"

The when: field still evaluates exactly as it does for a single file — it just now applies to every file the glob matches, at any depth, recursively, with no per-file repetition. When more than one entry's path: matches the same file, the last one declared wins, the same precedence .gitignore/CODEOWNERS use: write broad patterns first, specific overrides after.

Combine a glob path: with matrix: and target: to duplicate an entire directory once per combination, the same way a single file already could:

spec:
  files:
    - path: "components/**"
      target: "environments/{{ .matrix.env }}/{{ .file.RelPath }}"
      matrix:
        env: [dev, staging, production]

Since a glob can match many files, target: needs to know which matched file an output came from — .file.RelPath is that file's own path with the glob's literal prefix stripped (so components/vpc/main.tf becomes vpc/main.tf), available in target: and the file's own content alongside .matrix.<axis>. A components/ directory with vpc/main.tf and eks/main.tf produces six files across three environments — each preserving its own relative position under every environment.

How to Use It​

The scaffolding-directory-matrix example is a minimal, runnable template — a two-resource components/ directory duplicated once per selected environment:

cd examples/scaffolding-directory-matrix
atmos scaffold generate example ./my-project --set environments=dev,staging

This generates four files: environments/dev/vpc/main.tf, environments/dev/eks/main.tf, and the same pair under staging/ — two full copies of components/, one per selected environment, without listing vpc/main.tf and eks/main.tf individually in scaffold.yaml. Add a glob path: to any spec.files[] entry in your own templates — with when: alone to skip a directory, or with matrix: and .file.RelPath in target: to duplicate one.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

The Problem​

Atmos AI let you talk to your infrastructure through a fixed set of API providers. If you wanted to try a cheaper or non-US model - route through an aggregator, run DeepSeek directly, or use a GLM model from Z.AI - you were out of luck unless you were willing to point the generic OpenAI provider at a hand-copied base URL and hope the defaults lined up. There was no first-class way to say "use OpenRouter" and get a sensible model, API-key variable, and endpoint out of the box.

The Fix​

Atmos AI adds three OpenAI-compatible API providers you can select by name:

• OpenRouter (openrouter) - a router that fronts hundreds of models behind one API key. Switch models by changing the model slug (anthropic/claude-sonnet-4-5, openai/gpt-4o, deepseek/deepseek-chat, ...) without touching anything else.
• DeepSeek (deepseek) - the DeepSeek API directly, including deepseek-reasoner for the reasoning model. Low cost for a lot of everyday infrastructure questions.
• Z.AI (zai) - Zhipu's GLM models over their OpenAI-compatible endpoint.

Each one behaves like every other Atmos AI provider: set an API key with the !env function, and optionally override the model, base_url, or token limits. Because they are OpenAI-compatible, they work everywhere the existing providers do - atmos ai ask, atmos ai chat, and the --ai flag.

How to Use It​

Add the provider under ai.providers in atmos.yaml and select it as the default:

ai:
  enabled: true
  default_provider: openrouter
  providers:
    openrouter:
      model: "deepseek/deepseek-chat"   # any provider-prefixed slug
      api_key: !env "OPENROUTER_API_KEY"

    deepseek:
      model: "deepseek-chat"            # or "deepseek-reasoner"
      api_key: !env "DEEPSEEK_API_KEY"

    zai:
      model: "glm-5.3"
      api_key: !env "ZAI_API_KEY"

Then ask away:

export OPENROUTER_API_KEY=sk-or-...
atmos ai ask "What stacks and components do we have?"

See the full list of options on the AI providers configuration page.

Get Involved​

The provider list will keep growing as the model landscape shifts. If there's an OpenAI-compatible provider you want to see as a first-class name in Atmos, open an issue or a pull request on cloudposse/atmos - adding one is a small, well-templated change.

The Problem​

Atmos AI could reuse a locally installed coding-agent CLI - Claude Code, OpenAI Codex, GitHub Copilot - instead of an API key, but the popular open-source opencode agent wasn't one of them. opencode users had to fall back to configuring a raw API provider, which meant a second credential to manage and gave up opencode's own model selection and MCP setup.

The Fix​

Atmos AI adds opencode as a CLI provider. Point Atmos at it and every atmos ai command runs through your existing opencode installation and whichever model provider you've authenticated there - no API key in atmos.yaml:

• Reuses your opencode auth and model configuration (opencode auth login).
• Full MCP pass-through: MCP servers you declare in atmos.yaml are handed to opencode automatically, with auth-requiring servers wrapped in atmos auth exec and the Atmos toolchain on PATH. Atmos writes a temporary config and points opencode at it via OPENCODE_CONFIG, so your own opencode.json is never touched.
• Participates in auto-detection: with ai.enabled: true and no default_provider, Atmos finds the opencode binary on your PATH and uses it.

How to Use It​

Select it as the default provider (or let auto-detection find it):

ai:
  enabled: true
  default_provider: opencode
  providers:
    opencode:
      # optional - opencode's provider/model slug; defaults to opencode's own default
      model: "anthropic/claude-sonnet-4-5"

Then ask away - opencode handles the model call and any MCP tools:

atmos ai ask "Which components changed in the dev stack?"

See the AI providers configuration page for the full CLI-provider reference, including the MCP pass-through behavior.

Get Involved​

opencode joins Claude Code, OpenAI Codex, and GitHub Copilot as bring-your-own-subscription CLI providers. If there's another local coding agent you'd like Atmos to drive, open an issue or a pull request on cloudposse/atmos.

The Problem​

A repository can contain many component sources, mixins, and targets. Fetching these one at a time leaves the network idle between jobs and makes a large update hard to follow. Overlapping destinations also mean downloads cannot simply copy files whenever they finish.

The Fix​

Vendor pull prepares up to four packages at once and installs them in declaration order. Local sources wait for earlier writes before being read. Vendor update checks upstream versions concurrently and preserves the order and formatting of manifest edits.

The shared progress display shows active phases, download percentages when the total size is known, retries, and completed results. A ready package is waiting for its turn to install. The overall bar advances during downloads with known sizes and when packages become ready, with equal weight for preparation and installation. The completed count advances only after processing finishes. CI receives plain result lines, and structured update reports stay on stdout.

The vendor clean command displays relative paths and preserves every lock entry when removing vendored files. Recorded versions, checksums, and provenance remain available for the next pull. Fully cleaned packages reinstall without drift warnings; partial deletion and modified files still trigger checks.

How to Use It​

atmos vendor pull --max-concurrency 8
atmos vendor update --check --max-concurrency 8
atmos vendor update --pull --max-concurrency 8

Set vendor.max_concurrency in atmos.yaml or use ATMOS_VENDOR_MAX_CONCURRENCY. Explicit flags take precedence over the environment and configuration. Set one worker for serial execution.

Projects with an edition pin before 2026-09-15 keep one worker by default. All editions receive the progress display, and explicit concurrency settings override the pin.

Get Involved​

Try the commands on your component catalog and share feedback in Atmos GitHub Discussions.

The Problem​

An experimental warning is useful when you first use a feature. Seeing it again for every component in a workflow adds noise, especially alongside repeated Atmos version, CI, and Pro status messages.

The Fix​

The new experimental mode warn-daily gives each feature its own 24-hour timer. A toolchain warning does not suppress the first warning for devcontainers or an experimental setting. Commands in the same experimental family share a timer, and CI commands and CI hooks share the CI feature's timer.

Atmos stores readable feature names and timestamps in its shared local cache. The timers apply across invocations and projects using that cache. Clearing the cache makes warnings eligible again; an unavailable cache never blocks the command. Concurrent suppression is best effort on Windows.

Startup banners appear at the top-level invocation and are suppressed in child Atmos calls. Markdown output also follows Atmos's explicit theme and color profile without automatic terminal-style probing.

How to Use It​

The new default requires no configuration for unpinned projects. To choose it explicitly:

settings:
  experimental: warn-daily

Projects pinned to a config edition before 2026-09-14 retain warn as the default. An explicit settings.experimental value or ATMOS_EXPERIMENTAL takes precedence over the edition default.

To show experimental warnings on each top-level invocation, set experimental: warn. Child command and setting notices are now suppressed in this mode too, independently of the edition pin. CI hooks retain their existing warn behavior. The error and disable modes remain enforced on every invocation, including nested calls, regardless of cached warnings.

Get Involved​

See the experimental settings reference for all modes, or report unexpected output.

The Problem​

atmos init --update and atmos scaffold generate --update read the merge base directly from the target directory's own Git history, at whichever ref was pinned when the project was first generated. That works well when the target is a Git repository with intact history — but it also means --update fails outright the moment it isn't: no Git repo, a rewritten or squashed history, or a base commit that's since been garbage-collected all leave the merge with no base to compare against.

It has a second, quieter cost even when history is intact: because the pinned base ref never advances, the gap between "what the template looked like at that pin" and "what it looks like now" only grows with every successive update — so does the conflict surface.

The Fix​

--update-strategy chooses where that merge base comes from, independently of --merge-strategy (how a conflict resolves) and --merge-driver (which merge algorithm runs):

• tracked (default, unchanged) — the merge base is read from the target's own Git history, exactly as before.
• rendered — the merge base is a fresh, pristine re-render of the template itself, at the ref that produced what's currently on disk, using that generation's own recorded answers. There's no Git read involved at all, so it works whether or not the target is (or still is) a Git repository — and because it re-renders from the last update rather than the original pin, the base never drifts further than one update cycle behind.

rendered needs a scaffold.yaml-driven template, since it relies on the answers Atmos already records in .atmos/scaffold.yaml from the prior generation to reproduce that render faithfully. A plain --set-only template has no such record to replay, so rendered isn't available for those yet — use tracked there.

How to Use It​

# Everyday updates: tracked (the default) keeps reading from Git history.
atmos scaffold generate my-template ./my-project --update

# No Git history to lean on, or you just want the merge base to stay current
# with the last update instead of the original pin.
atmos scaffold generate my-template ./my-project --update --update-strategy=rendered
atmos init --update --update-strategy=rendered

Get Involved​

See the atmos scaffold generate and atmos init docs for the full flag reference. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

That's exactly what Atmos did. Every Terraform subcommand — plan, apply, shell, destroy, and even the read path behind !terraform.output and atmos.Component — started with a full terraform init -reconfigure, unconditionally:

atmos terraform apply demo -s dev
# Initializing provider plugins...
# Initializing the backend...
# ...apply completes...

atmos terraform output demo -s dev
# Initializing provider plugins...   <- nothing changed, but init runs again
# Initializing the backend...

Nothing about demo changed between those two commands, but the second one pays the full init cost anyway. On a slow connection, or with a component that pulls in a lot of providers, that turns a fast edit-plan-apply loop into a slow one. Issue #620 asked Atmos to be smarter about this — Terragrunt-style Auto-Init, where init only re-runs when it actually needs to. Issue #1263 asked for something related: a way to have Atmos run init -upgrade automatically when a provider constraint changes, instead of requiring -upgrade to be typed by hand after every version bump.

The Fix​

Atmos now fingerprints the inputs that actually affect terraform init — the component's root Terraform/OpenTofu files, the lock file, the CLI configuration, the resolved binary, and relevant environment variables — and compares that fingerprint against the one recorded after the last successful init. When nothing has changed, and the working directory still looks initialized, Atmos skips init entirely. Applying a component and then reading one of its outputs no longer performs two full inits.

-reconfigure and -upgrade get the same treatment instead of being added unconditionally: -reconfigure only goes on when the backend configuration actually changed (or on the first init, or after a working directory is re-provisioned), and -upgrade only goes on when Terraform or OpenTofu itself reports that an upgrade is required — the behavior #1263 asked for.

None of this trusts the fingerprint blindly. If a skip turns out to have been wrong — a nested module changed, or .terraform was altered by hand — Terraform or OpenTofu fails with a diagnostic like "Backend initialization required" or "Required plugins are not installed" before it ever touches state. Atmos recognizes that class of diagnostic, runs the init that should have run, and retries the command once. The one gap this doesn't close is a change inside a nested local module, which isn't part of the fingerprint — that's caught by the same retry path rather than avoided up front, and it's a limitation Terragrunt's own Auto-Init shares.

Behavior change, automatically protected by editions: init no longer runs unconditionally, and -reconfigure/-upgrade are no longer added to every init, by default. If your project is pinned to an edition from before 2026-09-12, you see byte-for-byte the same behavior Atmos always had — no config changes needed. Unpinned projects, and anything pinned on or after that date, get the new defaults automatically. See Config Editions for how pinning works.

How to Use It​

Three new settings under components.terraform.init, all defaulting to auto:

components:
  terraform:
    init:
      mode: auto         # auto | always | never
      reconfigure: auto  # auto | always | never
      upgrade: auto       # auto | always | never

mode controls whether init runs at all: auto skips it when nothing relevant changed, always restores the previous behavior, never disables the ordinary implicit init — but terraform workspace select/new still forces a reconfigured init regardless, since it always needs one; --skip-init is the flag that suppresses init unconditionally, including for workspace. reconfigure and upgrade control the two flags the same way, independently.

mode and upgrade are edition-protected: pin edition: "2026-09-11" or earlier and both roll back to their pre-this-PR behavior (always and never respectively) with no other config changes. reconfigure isn't — see the note on init_run_reconfigure below.

Each setting also has a matching flag and environment variable for one-off overrides:

atmos terraform plan vpc -s dev --init-mode=always
atmos terraform apply vpc -s dev --init-reconfigure=always
atmos terraform plan vpc -s dev --init-upgrade=always

The existing init_run_reconfigure boolean keeps working: false maps to init.reconfigure: never, and the previous default true now maps to init.reconfigure: auto rather than always. Unlike mode/upgrade, this one isn't edition-protected — pinning an earlier edition doesn't restore it, because init.reconfigure has to stay unset internally for the legacy init_run_reconfigure mapping to keep working at all. Set init.reconfigure: always explicitly to keep the exact previous behavior.

See Terraform Configuration for the full setting reference, and Automatic Initialization for how the skip decision and recovery path work.

Get Involved​

Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

View the full example

The Problem​

Post-deployment checks need a clear result for every test, including independent checks that can still run after another fails. Shell wrappers and CI-specific reporting make that behavior harder to reuse locally and across deployments.

The Fix​

Atmos supports type: test in workflows, custom commands, and lifecycle hooks. Tests continue by default, while a tree with green/red dots and a bottom progress bar shows the results. Nested parallel and matrix groups share the same report.

How to Use It​

Attach a test step to an after.terraform.apply hook with kind: step and on_failure: fail to make checks part of the deployment result. Use output: all when debugging, or fail.mode: fail_fast when remaining checks should stop after an error. CI receives a static tree with the same failure details.

See the test step reference for configuration and failure behavior.

The local example runs without stacks. Running bare atmos now displays usage and available commands, including custom commands, without requiring stack configuration.

Get Involved​

Try the local example and share feedback in GitHub Discussions.

The Problem​

Right-sizing a runner pool means knowing what a job actually costs to run, and Terraform is usually the most expensive step in the pipeline. But teams size runners by guessing, then watching for OOM kills or timeouts and bumping the tier — because nothing reports what a plan or apply actually consumed. That guessing game repeats for every new component, every provider version bump, and every runner generation, whether the pipeline runs on plain GitHub Actions, Atmos alone, or Atmos Pro.

The Fix​

terraform plan, apply, and deploy now measure the actual resource cost of the run: the terraform process itself and everything it spawns — provider plugins and any other child processes — not just the negligible overhead of the Atmos CLI wrapper around it. When each component's command finishes, Atmos prints a one-line summary identifying which component and stack it covers — important in a multi-component --all/--affected run, where this line prints once per component:

▶ Completed vpc (dev) in 45.2s | CPU: 12.3s user, 4.1s sys | Peak memory (largest process): 512 MB

At the end of the whole invocation, Atmos also prints one aggregate summary covering everything that ran:

▶ Total for this invocation in 3m12.4s | CPU: 48.9s user, 16.2s sys | Peak memory (largest process): 780 MB

The same, more accurate numbers now flow into the execution data Atmos Pro receives for CI runs, and — when Native CI is active — into the GitHub Actions job summary itself, right next to the resource-change badges:

📊 Resource usage: 45.2s wall · 12.3s user / 4.1s sys CPU · 512.0 MB peak memory (largest process)

Instead of guessing at a runner tier and adjusting after the fact, size a pool from real CPU-time and peak-memory numbers per component, visible directly in the run UI. The memory figure is the largest single process observed, not a simultaneous sum across Terraform and every provider plugin running alongside it — a lower bound worth catching an obviously undersized runner with, not the exact ceiling to provision to. Re-check the sizing whenever a provider version bump or a new component changes the actual footprint.

How to Use It​

Both summary lines are on by default — no setup required. If you'd rather not see them (for example, in a scripted context where you don't want the extra output), turn them off with one setting:

settings:
  metrics:
    enabled: false

This only controls local terminal output; it never affects what Atmos Pro receives. See the Metrics settings docs for details.

Get Involved​

Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Native Helm components already resolve chart values from inherited stack configuration, component value files, and inline values. Before this update, there was no Helm-compatible command-line override surface for those resolved values. Operators had to commit a temporary configuration change, use a separate wrapper around Helm, or accept that a diff did not necessarily match the subsequent deployment.

The Fix​

Native Helm now accepts repeatable Helm-compatible -f/--values, --set, --set-string, --set-file, --set-json, and --set-literal flags on template/render, diff/plan, and apply/deploy. The overrides apply only to the current invocation and take precedence over the resolved component values; they never modify stack configuration.

The new atmos helm values command prints the final, masked value map as formatted YAML. It lets you inspect the value set that a preview or deployment will consume, including temporary command line overrides, without contacting Kubernetes.

How to Use It​

Use the same override arguments for inspection, preview, and deployment:

atmos helm values monitoring -s plat-ue2-dev \
  -f incident-values.yaml \
  --set image.tag=2026.09.09

atmos helm diff monitoring -s plat-ue2-dev \
  -f incident-values.yaml \
  --set image.tag=2026.09.09

atmos helm apply monitoring -s plat-ue2-dev \
  -f incident-values.yaml \
  --set image.tag=2026.09.09

Atmos layers command-line value files and each supported --set variant over the component's resolved values using Helm's normal parsing and precedence rules. That includes nested paths, list indexes, typed values, string and literal handling, JSON input, and file-backed values.

Get Involved​

See the native Helm command reference for the complete override reference and the values command guide. Have feedback? Open an issue or join the Cloud Posse community Slack.