The Problem​

Someone new to Atmos should be able to kick the tires almost immediately. A working example provides the configuration, stacks, and components to start exploring with just a few commands.

The Fix​

Start with any of the official Atmos examples. Atmos copies the example verbatim, including examples that contain a scaffold manifest.

The same command also works with directories in other Git repositories, supported remote sources, and local directories. These sources use scaffold generation when a root manifest exists and copy their contents otherwise.

Git sources use a single shallow fetch to avoid downloading repository history. Configure init.depth for any repository: use 1 for the latest revision or 0 for full history. A source URL's explicit depth parameter takes precedence. The CLI prints the actual destination and displays the example's README when present.

Copies preserve literal template content, dotfiles, executable permissions, and empty directories while excluding Git metadata. Existing template names and interactive selection continue to work.

How to Use It​

After installing Atmos, initialize the quick-start example and list its stacks:

atmos init github.com/cloudposse/atmos//examples/quick-start-simple
cd quick-start-simple
atmos list stacks

The destination defaults to the source directory's name. Supply a second argument to choose another destination, or use the shorthand for the default repository:

atmos init examples/quick-start-simple ./my-project

Configure initialization defaults in atmos.yaml to use your team's repository and revision:

init:
  repository: github.com/acme/starters
  ref: main
  depth: 1
  git: true

The repository defaults to github.com/cloudposse/atmos. Git initialization and an initial commit are enabled by default; set git: false or pass --no-git to skip them. Explicit source URLs bypass the default repository, and a revision embedded in the source takes precedence over --ref and configuration.

Use --copy to copy another source verbatim even when it contains a scaffold manifest. Copy mode skips template rendering and scaffold hooks, requires an empty destination unless --force is supplied, and does not support scaffold updates or template variables. Read the init reference for source formats, precedence, and overwrite behavior.

Get Involved​

Explore the examples and share your experience in GitHub Discussions.

Some components need privileged credentials or manual approval. Others need network access that the CI runner lacks: a private VPC, a peering connection, or access to an internal service. Selectors let you leave those components out of a workflow and run them where the required access is available.

Select Components from Stack Metadata​

Give components a default label in your shared stack defaults, then override it for components that need a different execution environment:

metadata:
  labels:
    ci: auto

components:
  terraform:
    private-service:
      metadata:
        labels:
          ci: manual

Build the matrix using that label:

atmos describe affected --format=matrix --labels=ci:auto

--labels=ci=auto is equivalent. The command includes affected components labeled ci: auto and leaves out private-service. The names ci, auto, and manual are user-defined; manual means excluded from this automated workflow, not a built-in execution mode. Run excluded components manually or through a separate workflow with the appropriate credentials and network connectivity.

Labels match all supplied pairs; tags match any supplied tag, such as --tags=production,tier-1. When you combine them, components must satisfy both filters. Components missing the requested metadata do not match, so the shared default makes the selection explicit across your stacks. Selectors work with every output format, including JSON, YAML, and CI matrices. You can also plan the selected components directly with atmos terraform plan --affected --labels=ci:auto, using the same labels in local and automated runs.

The legacy Atmos GitHub Actions used settings.github.actions_enabled for component opt-outs. Native CI does not read that setting. Labels provide an explicit selection pattern when migrating to native CI, without post-processing the matrix in workflow YAML.

Include Matching Dependents​

With --include-dependents, matching dependents remain in the result even when their parent is filtered out. Add --flatten to make each remaining dependent a separate matrix entry. Terraform also honors tags and labels when including dependents; prerequisites added with --include-dependencies still run regardless of those selectors. See the selector reference for details.

Configure Your Workflow​

Labels express workflow selection; they do not detect connectivity or enforce access. The native CI guide covers setup and an optional OPA policy for components prohibited from running in GitHub Actions. Components that only need a different runner can use a separate workflow instead.

For workflow configuration, see the Deploy Affected example, including its empty-matrix guard, and the command reference for environment variables and uploads.

Get Involved​

Have a workflow this pattern does not cover? Open an issue and share your use case.

The Problem​

An average component size cannot predict the size of a batch containing several large components. A rejected request could also return plain text, which appeared as an unexpected API response format instead of identifying the size limit.

The Fix​

The Atmos Pro upload configuration now defaults to a 3 MiB request budget, down from 4 MiB, leaving more room below the server limit. Uploads preserve component order and account for the request metadata as well as the component data.

If an affected-stack or instances upload receives HTTP 413, Atmos restarts the complete batch with a smaller budget, up to three times. A component that is too large even by itself produces an error naming its stack, component, and serialized size, with guidance to reduce the uploaded data. Small uploads keep their existing single-request behavior, and no server change is required for these two upload paths.

How to Use It​

Continue running affected-stack uploads or instances uploads as before:

atmos describe affected --upload
atmos list instances --upload

No configuration change is required. An explicit positive settings.pro.max_payload_bytes still controls the initial request budget; automatic recovery only reduces it for the current upload. Omitted or nonpositive values now select 3 MiB, regardless of an edition pin, because this is a runtime fallback rather than a stored configuration default.

The shared threshold also moves execution metadata to its existing out-of-band upload path sooner. Large execution-data objects still require the coordinated protocol work described in issue #3313; this release makes their HTTP 413 errors clear but does not add multipart object uploads.

Get Involved​

Report upload failures in GitHub issues, including the Atmos version and error message with sensitive data removed.

The Problem​

Scaffold templates render with {{ }} by default, and spec.delimiters can switch the whole template to a different pair. That works while every file in the template agrees on one pair. It breaks down as soon as a single template generates files that already contain {{ }} of their own:

• A Helm chart needs its {{ .Values.image }} expressions to reach the generated chart untouched, so Helm can render them later.
• A GitHub Actions workflow needs ${{ github.sha }} to stay literal for the same reason.
• The rest of the project, such as stack files and READMEs, still wants the convenient default.

Switching the whole template to [[ ]] fixes the chart but forces every other file to change syntax with it. Keeping {{ }} means escaping every Helm and Actions expression by hand.

Custom delimiters also had a second gap. When Atmos checked a generated file path for unrendered template markers, it always looked for {{ and }}, no matter which delimiters the template used. A path that legitimately contained a literal {{, such as one produced under a [[ ]] template, was rejected as if a variable had been left unrendered.

The Fix​

An entry in spec.files can now carry its own delimiters, which override the template-wide pair for every file the entry matches. The pair covers everything Atmos renders for those files: their content, their paths, target, and any matrix axis written as a Go template expression. The when condition is a CEL expression, so it never uses delimiters.

Atmos picks a file's delimiters in this order:

1. The delimiters of the matching spec.files entry. When several entries match the same file, the last one wins, as it does for path and when.
2. spec.delimiters.
3. {{ and }}.

Path validation now follows the same pair, so a literal {{ or ${{ in a path is accepted under [[ ]] while a forgotten [[ .Config.name ]] is still caught. Both atmos scaffold generate and atmos init honor per-file delimiters, and so do --dry-run previews and --update merges. An update keeps your edits to a chart file while Helm's own expressions stay literal.

How to Use It​

Declare the template-wide default once, then override it for the files that need something else:

spec:
  delimiters: ["{{", "}}"]          # template-wide default (optional)
  files:
    - path: "charts/**"             # Helm templates use {{ }} themselves
      delimiters: ["[[", "]]"]
    - path: ".github/workflows/*.yml.tmpl"
      delimiters: ["<<", ">>"]      # keeps ${{ github.sha }} literal

A chart template can then mix both syntaxes. Atmos fills in the [[ ]] expression and leaves the Helm expression for Helm:

# atmos:template
name: [[ .Config.name ]]
image: "{{ .Values.image }}"

Each pair must be exactly two non-empty strings, and atmos scaffold validate rejects anything else. See Template Delimiters for the full rules, and the atmos scaffold generate reference for how delimiters combine with target and matrix.

Get Involved​

Try it on a template that generates a chart or a workflow, and open an issue with feedback or edge cases you run into.

The Azure Key Vault store now accepts labels and expires options, and applies them to every secret Atmos writes.

The Problem​

Azure Key Vault lets administrators require metadata on every secret through Azure Policy, for example "all secrets must have an expiration date" and "all secrets must carry an owner tag". The Atmos Azure Key Vault store created secrets with only a name and a value, so under such a policy atmos terraform apply hooks, !store writes, and atmos secret set all failed with a policy violation.

The only workaround was to pre-create every secret outside Atmos with the right metadata, which defeats the point of letting Atmos manage the store.

The Fix​

Two new options on the store apply metadata at write time:

• labels sets key-value metadata on every secret Atmos writes. Labels are applied as Azure Key Vault secret tags.
• expires sets the expiration. It accepts either a duration or a specific date, so you don't need separate fields for each style.

Reads, existence checks, listing, and deletion are unchanged, and stores that set neither option behave exactly as before.

How to Use It​

Configure both options in the store's options block in atmos.yaml:

stores:
  prod/azure:
    kind: azure/keyvault
    options:
      vault_url: "https://my-keyvault.vault.azure.net/"
      labels:
        managed-by: atmos
        environment: prod
      expires: 90d

expires accepts these forms:

Prefer a relative duration for long-lived stores. A fixed date eventually passes, and from then on every new secret is created already expired or is rejected by policy. A relative value never goes stale, and because it's recalculated on each write, rewriting a secret renews its expiration. A fixed date that is already in the past is accepted, but Atmos logs a warning because Key Vault or your policy may reject it.

A duration must be at least one second, because Key Vault stores expiration in whole seconds. Invalid values, such as 0d, 500ms, or soon, fail when the store is created rather than on the first write. Label values must be strings, so quote values like "true" or "5".

See the stores configuration reference for the full list of Azure Key Vault options.

Get Involved​

This came from a request in issue #1549. If another store backend needs metadata at write time, such as AWS tags or Google Secret Manager labels, tell us in the issue tracker.

The Problem​

State buckets are long-lived and every deployment depends on them, so a name collision or a lost name hurts more here than almost anywhere else. The usual workaround is to bake an account ID and region into the name and hope nobody else picks the same one, but a convention only lowers the odds. Nothing stops another account from creating a bucket with that name, including after you delete yours. The account-scoped namespace removes the question, and organizations can go further and require it with an IAM or service control policy that checks the s3:x-amz-bucket-namespace condition key.

Backend provisioning exists to remove the chicken-and-egg problem of needing a state bucket before you can deploy the component that manages it. The S3 provisioner created buckets in the default namespace and had no way to request another one. S3 selects a namespace with a parameter on the bucket creation request, and a well-formed name is not enough. Anyone who wanted account-scoped state buckets, or whose policy demanded them, was back to a separate bootstrap step.

The Fix​

The S3 provisioner now accepts an optional bucket_namespace setting under provision.backend. When it is set, Atmos sends it as the BucketNamespace parameter of the S3 CreateBucket call. When it is not set, nothing changes: existing configurations behave exactly as before.

The setting lives next to enabled, not under backend, so it never appears in the generated Terraform backend configuration. Atmos validates the value before it contacts AWS. The valid values are global and account-regional, as defined by Amazon S3, and any other value fails with the list of valid values.

How to Use It​

Set the namespace and use a bucket name that follows the S3 naming rules for that namespace. Atmos uses the name exactly as written, including names produced by Atmos templates:

components:
  terraform:
    example:
      backend_type: s3
      backend:
        s3:
          bucket: example-tfstate-111122223333-us-east-1-an
          region: us-east-1
          key: terraform.tfstate
          use_lockfile: true
      provision:
        backend:
          enabled: true
          bucket_namespace: account-regional

Both automatic provisioning on terraform init and atmos terraform backend create honor the setting. See the Bucket Namespace reference for details and the S3 namespaces documentation for the naming rules.

Get Involved​

Tell us how you provision your state backends in GitHub Discussions, or open an issue if the provisioner is missing a setting you need.

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.