The Problem​

A reusable authentication session is useful for repeated commands, but a temporary reader token may need a shorter lifetime: acquire it, fetch the requested secret, and revoke it before another command receives the value. A failed read or an interrupted command needs the same cleanup boundary.

The Fix​

The new options.identity_lifetime: operation setting is being prepared in PR #3668 and has not been released. It takes effect only when explicitly configured on a HashiCorp Vault or OpenBao store.

Each operation authenticates the selected target identity afresh and logs out that operation's credentials before returning. Existing sessions for the same target identity, reusable provider sessions, and ancestor identity sessions are preserved. If cleanup fails, Atmos returns an error and withholds read, list, and existence results.

Graceful SIGINT/SIGTERM cancellation gives credential acquisition and cleanup bounded time to finish. Remote revocation depends on the configured identity revoking its token during logout. Forced termination, an unreachable issuer, or an ambiguous network response can prevent confirmed revocation, so short server-enforced token TTLs remain necessary.

How to Use It​

Configure a dedicated native auth identity that emits environment/v1 credentials containing VAULT_TOKEN and revokes its issued token on logout. Pin that identity to the store and set its lifetime:

stores:
  vault-secrets:
    type: hashicorp-vault
    secret: true
    identity: vault-reader
    options:
      address: https://vault.example.com
      mount: secret
      identity_lifetime: operation

Operation lifetime requires an explicit store identity and an authentication manager that supports operation ownership. Authentication failures do not fall back to static or ambient tokens. The default identity_lifetime: session keeps the existing reusable-session behavior.

See the secret-store configuration guide for the identity and cleanup requirements, and the official secret-store authentication example for connecting fetched values to a command's environment.

Get Involved​

Review PR #3668 and share feedback on identity isolation, cancellation, and cleanup behavior before release.

The Problem​

Several Atmos commands hand you a URL to open yourself. atmos auth login shows the AWS sign-in URL in case the browser doesn't open, and atmos auth console shows a console sign-in URL when it doesn't launch a browser. AWS IAM Identity Center URLs now exceed 500 characters, and console sign-in URLs carry a full session token. Printing the raw URL was the only option, even though most modern terminals can show a short label as a clickable hyperlink and every desktop has a clipboard.

The Fix​

A new settings.terminal.links option controls how Atmos delivers these links:

• auto (default): a short clickable link, such as "Open AWS sign-in", when your terminal is known to support hyperlinks. Otherwise, the plain URL.
• osc8: always the clickable link. Use this when your terminal supports hyperlinks but Atmos can't tell, which is common inside a container or over SSH.
• clipboard: copy the URL straight to your clipboard. If no clipboard is reachable, Atmos asks the terminal to copy it and also prints the URL.
• raw: always the plain URL.

In auto mode, Atmos recognizes iTerm2, VS Code, WezTerm, Ghostty, kitty, Windows Terminal, GNOME Terminal and other VTE-based terminals, Konsole, and Orca. Inside tmux or screen, or anywhere it can't identify the terminal, it falls back to the plain URL. When output isn't a terminal, such as in CI or when piped, Atmos always prints the plain URL and never touches the clipboard. Atmos also honors the FORCE_HYPERLINK convention other command-line tools use: 1 forces the clickable link and 0 turns it off.

The AWS sign-in prompts are tidier too. A URL that fits in 80 columns stays inside the prompt's box. A longer one is delivered below the box, so the border no longer wraps into the URL or ends up in the text you copy.

How to Use It​

Most people don't need to change anything: auto already gives you a clickable link in a supported terminal.

To pick a mode for your project, set it in atmos.yaml:

settings:
  terminal:
    links: clipboard   # auto, osc8, clipboard, or raw

To override it for a shell session or a single command, use the ATMOS_TERMINAL_LINKS environment variable or the --links global flag:

export ATMOS_TERMINAL_LINKS=osc8
atmos auth console --no-open --links=clipboard

The flag takes precedence over the environment variable, which takes precedence over atmos.yaml.

Get Involved​

If your terminal supports hyperlinks but auto doesn't recognize it, let us know in GitHub Issues so we can add it.

The Problem​

The --branch flag maps to git clone --branch, which only accepts branch and tag names, not commit SHAs. Reconciling an existing checkout also fast-forwards to the branch tip. That is the right behavior for keeping a working copy current, and the wrong behavior when a pipeline must operate on one immutable revision, such as the event SHA for a plan, an apply, or a describe affected diff.

The Fix​

The new --ref flag (or the ATMOS_GIT_REF environment variable) accepts a branch, tag, full ref such as refs/tags/v1, or a commit SHA. Atmos fetches exactly that ref and checks it out detached:

• Fresh clones fetch the requested ref instead of checking out the default branch.
• Existing checkouts move to the requested revision exactly, even when the cached copy is ahead of it. Nothing is merged or fast-forwarded past it. Uncommitted changes are still refused.
• Named repositories and URI queries: --ref overrides any configured branch.
• Submodules are updated to match when submodules are enabled.

--ref and --branch are mutually exclusive. The fork-PR safety gate also applies: in an elevated pull_request_target or workflow_run event for a fork pull request, an explicit --ref is refused unless you opt in with --allow-unsafe-fork.

How to Use It​

Pin a CI job to its event revision and keep full history for diffs:

atmos git clone --ci --ref "$GITHUB_SHA" --depth 0

Check out a release tag of a managed repository:

atmos git clone flux-deploy --ref v1.2.0

See the atmos git clone reference for every flag.

Get Involved​

Try --ref in your pipelines and tell us how it works for you in the Cloud Posse Slack or on GitHub.

The Problem​

A port mapping such as host: 3000 / container: 3000 asks the container runtime to listen on 0.0.0.0:3000. On a laptop connected to shared Wi-Fi, or on a CI runner, that service becomes reachable from other machines. Restricting it meant dropping down to raw docker run -p 127.0.0.1:3000:3000 invocations outside of Atmos.

The Fix​

The existing host field now accepts either a port number or an IP:port string. For example, host: "127.0.0.1:3000" publishes port 3000 only on loopback. Numeric values retain the runtime's default binding, so existing configuration is unchanged.

How to Use It​

Set host to an address and port in any entry under run.ports:

components:
  container:
    portal:
      image: my-portal:local
      run:
        ports:
          - host: "127.0.0.1:3000"
            container: 3000

• IPv6 addresses require brackets: host: "[::1]:3000". Use an IP literal, not a hostname.
• Omitting host or setting it to 0 lets the runtime assign a free host port. Use host: "127.0.0.1:0" to restrict that automatic assignment to loopback.
• The same field works in container workflow steps, background container services, and emulators.

Binding to loopback narrows where the runtime listens, but it isn't a firewall. Docker Engine versions before 28.0.0 can expose localhost-published ports to hosts on the same network segment, and some network configurations allow direct routing to container ports. See Docker's port publishing documentation for details.

Port bindings are fixed when a container is created. After you change one, recreate just that container:

atmos container down portal -s <stack>
atmos container up portal -s <stack>

Get Involved​

Questions or ideas for container components? Join us in the Cloud Posse community or open an issue on GitHub.

What’s Supported​

The new gitea-actions provider integrates with Gitea’s API and runner environment:

• Commit statuses: Report CI results against the checked-out commit.
• Pull request comments: Publish plan results and update an existing Atmos comment instead of adding a new comment on every run. Atmos only updates comments owned by the authenticated account.
• Affected-component detection: Resolve a pull request’s base SHA from its event payload when the checkout matches the PR head. Push runs use the event’s before SHA.
• Runner integration: Write job outputs and environment files, group logs, and write summaries when the runner supplies a summary file. Summary display depends on the runner.

Gitea runners can also expose GitHub-compatible environment variables. Atmos checks GITEA_ACTIONS=true to select the Gitea provider, even when GITHUB_ACTIONS=true is present. It uses Gitea’s API for reporting.

Enable It in Your Workflow​

Enable native CI in atmos.yaml:

ci:
  enabled: true
  checks:
    enabled: true
  comments:
    enabled: true
    behavior: upsert

Create a Gitea token with repository status and issue/PR comment access. For a scoped personal access token, use write:repository, write:issue, and read:user. Store it as an Actions secret named ATMOS_CI_GITEA_TOKEN.

Once your Gitea job has checked out the repository and installed Atmos and Terraform, add a plan step to its workflow under .gitea/workflows/:

- name: Plan infrastructure
  env:
    ATMOS_CI_GITEA_TOKEN: ${{ secrets.ATMOS_CI_GITEA_TOKEN }}
  run: atmos terraform plan vpc -s dev

Replace vpc and dev with your component and stack. No provider selection is needed. Atmos derives the API endpoint from the runner; ATMOS_CI_GITEA_API_URL can override it. HTTPS is required by default. The local emulator can explicitly opt into HTTP with ATMOS_CI_GITEA_ALLOW_INSECURE=true.

For pull request workflows, check out the event’s head SHA, rather than a moving branch. Checking out that exact revision also gives affected-component detection a known head and base to compare.

Plan on PR, Provision After Merge​

Use pull request jobs to validate and plan infrastructure changes. After merge, check out the push event’s commit and create a fresh plan before applying it. The Gitea provider does not yet resolve merged-PR plan provenance, so it cannot establish that a saved PR plan is the reviewed plan for the merged commit.

Gitea jobs do not automatically use GitHub artifact storage. Configure a shared planfile store if plans need to survive between jobs; otherwise, Atmos uses local storage. Remote Actions cache, GitHub Checks annotations, and commit comments are not supported by this provider.

See the Gitea Actions CI documentation for provider configuration, credentials, and capability details.

The Problem​

Opening a URL is one of the most common last steps in developer tooling: a local portal, a docs preview, a login page. Scripts had no built-in way to do it, so each command carried its own operating-system check and passed the URL through a shell, where a stray character could change what was run.

The Fix​

The new browser.open(url) function uses the same cross-platform browser launcher Atmos already uses elsewhere. It accepts only absolute HTTP or HTTPS URLs without embedded credentials, so local file paths, javascript: URLs, and argument-like strings are rejected before anything launches. Launch failures fail the script with a clear error, and dry runs never open a browser.

How to Use It​

Add it to any script step or standalone script:

commands:
  - name: portal
    commands:
      - name: open
        description: Open the local dashboard
        steps:
          - type: script
            interpreter: starlark
            script: |
              browser.open("http://localhost:3000")

Then run atmos portal open. The function is also available inside helpers loaded with module.load.

Get Involved​

Try it in your own custom commands and let us know what else your scripts need on GitHub or in the Cloud Posse community Slack.

The Problem​

Atmos uses Go templates in many places: stack manifests, vendor manifests, scaffolding, atmos docs generate, Helm and Kubernetes component templates, and generated backend and varfile paths. Gomplate supplies most of the template functions and all of the datasources.

Atmos releases used Gomplate v3. Gomplate v3 and v4 are no longer maintained, and both use the AWS SDK for Go v1. AWS no longer supports that SDK, so its vulnerabilities (GO-2022-0635 and GO-2022-0646) will never get a fix.

Dependency scanners and OpenSSF Scorecard report a vulnerable library even when your code never calls it. So every Atmos release showed these findings. The only supported fix was Gomplate v5. Atmos goes straight from v3 to v5, so this one upgrade brings the breaking changes of v3 → v4 → v5 together.

The Fix​

Atmos now embeds Gomplate v5, which is built on the AWS SDK for Go v2. Upgrading was not optional, but breaking your stacks along with it would not have been acceptable either. Despite the sheer number of breaking changes across Gomplate v3 → v4 → v5, we went through them one by one and kept backward compatibility everywhere it made sense to: we built a compatibility test suite that runs the same templates through the previous release and this one and compares the results, and added a shim for every removed function we could restore faithfully. Most stack templates keep working unchanged, and Sprig functions are still layered on top by default. Each shim logs a warning naming the replacement the first time a stack manifest calls a removed function, so you can migrate on your own schedule. A handful of datasource behaviors changed in ways Atmos cannot paper over with a shim — what to check in your stacks below covers each one. What changed unconditionally is what ships inside the binary: the AWS SDK for Go v1 is no longer present in any form.

One HashiCorp Vault authentication library still pulled the old SDK in its latest tagged release, even though its development branch had already been ported to v2. Atmos pins that library to the ported development revision until HashiCorp tags a release. That pin is temporary. Dependabot will propose the bump automatically as soon as a tagged release exists, and nothing about how you use Vault datasources changes in the meantime.

The same upgrade moved the Go cryptography library to a release that closes two SSH-related denial-of-service advisories (GO-2026-6354 and GO-2026-6355). This is preventative hygiene, not a response to an exploited issue, but it is one more finding that will no longer appear on a scan of Atmos.

What to Check in Your Stacks​

Gomplate v5 removed functions it had deprecated in v3 and changed some datasource behavior. Atmos keeps the removed names working through compatibility shims. Each shim logs a warning that names its replacement. A compatibility test suite runs the same templates through a v3 build and this release and compares the results; the sections below list the differences it found. The shims will be removed in a future major release, so replace the old names now. The templates configuration reference and the datasources reference carry the same list.

Renamed functions​

Deprecated function names were removed. Replace them with their namespaced equivalents:

# Before
enabled: '{{ conv.Bool .vars.flag }}'
names: '{{ conv.Slice "a" "b" }}'
cfg: '{{ conv.Dict "k" "v" }}'
has: '{{ conv.Has .vars "key" }}'
sorted: '{{ strings.Sort .vars.list }}'
ip: '{{ net.ParseIP .vars.addr }}'
cidr: '{{ net.ParseIPPrefix .vars.cidr }}'

# After
enabled: '{{ conv.ToBool .vars.flag }}'
names: '{{ coll.Slice "a" "b" }}'
cfg: '{{ coll.Dict "k" "v" }}'
has: '{{ coll.Has .vars "key" }}'
sorted: '{{ coll.Sort .vars.list }}'
ip: '{{ net.ParseAddr .vars.addr }}'
cidr: '{{ net.ParsePrefix .vars.cidr }}'

The old net functions still return their v3 types (netaddr.IP, netaddr.IPPrefix, and netaddr.IPRange), so method calls such as .Contains and .Prior keep working. The replacements return net/netip types, which have different methods.

The unqualified aliases slice, contains, hasPrefix, hasSuffix, split, splitN, and trim are no longer registered by Gomplate, but your templates keep working with no action needed:

• slice, contains, hasPrefix, hasSuffix, split, and trim resolve to Sprig, as they did before, because Atmos layered Sprig over Gomplate's aliases. If you have disabled Sprig (templates.settings.sprig.enabled), an Atmos shim restores Gomplate's versions. For slice, that is Gomplate's list builder (slice "a" "b"), not Go's builtin.
• splitN has no Sprig equivalent, so a shim always provides it.

Replace shimmed names with their strings.* or coll.* forms when you get the chance, and check the argument order as you go. With Sprig disabled, the shims keep Gomplate v3's order, with the input first, while the strings.* functions take the input last so they work in pipelines. contains "alphabet" "pha" becomes strings.Contains "pha" "alphabet", and splitN "a,b,c" "," 2 becomes strings.SplitN "," 2 "a,b,c". slice becomes coll.Slice with the same arguments.

Conversions and regular expressions now fail loudly​

Conversion functions such as conv.ToInt64, conv.ToFloat64, and conv.Atoi used to return 0 when handed something they could not convert. They now return an error, which surfaces as a template processing failure; Atmos does not paper over this one, since silently returning 0 for bad input is exactly the kind of behavior worth losing. The error message spells out the fix. If a stack relied on the silent zero, check that the input is a number before converting it:

retries: '{{ $r := conv.ToString (index .vars "retries") }}{{ if regexp.Match "^-?[0-9]+$" $r }}{{ conv.ToInt64 $r }}{{ else }}0{{ end }}'

An empty or non-numeric value renders 0, and a whole number converts as before. The example reads the key with index, which returns nothing for a missing key, so a missing retries also renders 0, even where Atmos treats missing values as errors (for example, in an import rendered with context). Writing .vars.retries instead would fail on a missing key there before the check runs.

Similarly, the regexp.* functions return an error for an invalid pattern instead of panicking. The failure is the same as before from your point of view, but the message now names the template and the pattern.

Datasource subpaths are relative URLs​

A second argument to datasource is resolved as a relative URL against the datasource's url. Directory datasources must end with a trailing /, and a subpath that begins with / replaces the base path rather than appending to it. Atmos warns when it sees a datasource used this way without a trailing slash on its URL, but it cannot know whether you meant the old or the new resolution, so the warning is a prompt to check the stack, not an automatic fix:

settings:
  templates:
    settings:
      gomplate:
        datasources:
          configs:
            url: "file:///configs/"   # trailing slash marks a directory

components:
  terraform:
    app:
      vars:
        name: '{{ (datasource "configs" "app.yaml").name }}'   # reads /configs/app.yaml

AWS Parameter Store values are returned directly​

An aws+smp:// datasource returns the parameter's value itself rather than an object with a .Value field. Drop the field access, and if the parameter holds a JSON document, tell the datasource to parse it with the type query parameter. Atmos recognizes a configured aws+smp:// datasource read with .Value still attached and warns about it, without guessing at what the parameter actually contains:

settings:
  templates:
    settings:
      gomplate:
        datasources:
          database:
            url: "aws+smp:///myapp/database/config?type=application/json"

components:
  terraform:
    app:
      vars:
        # Before: '{{ (datasource "database").Value.host }}'
        db_host: '{{ (datasource "database").host }}'

Smaller datasource changes​

Consul directory listings (a consul:// URL ending in /) return a list of key names instead of a map. BoltDB datasources were removed upstream and are no longer available.

S3 datasources reject an object whose checksum does not match, instead of returning its content.

In env://NAME, NAME is the URL host, so older releases read no variable and returned empty data. That form now fails. Use env:NAME or env:///NAME.

Vault KV v2 datasources detect the mount and add the /data/ API segment themselves. Remove /data/ from the URL (.../kv/config, not .../kv/data/config). The result is the secret's data without the data and metadata wrapper, so read fields directly.

Consul, Vault, SSM, and S3 datasources send different requests to those services. For example, Vault reads first check the mount type. The values your templates read do not change, but access policies or proxies that allow only specific requests may need an update. HTTP datasources still make one GET request per read, as before.

The datasource timeout in atmos.yaml (templates.settings.gomplate.timeout) now applies. Older releases replaced it with the 5-second default whenever a stack manifest did not set its own timeout, so a shorter global timeout was ignored. If a datasource takes longer than your global timeout, raise the timeout in atmos.yaml or in that stack's settings.

New: coll.JQ and tmpl​

coll.JQ runs a jq expression on a value, and the tmpl namespace (tmpl.Inline, tmpl.Exec) renders nested templates. Neither was available in templates before this release.

New: semantic version helpers​

Gomplate v5 adds a semver.* namespace for parsing and comparing versions inside templates, for example {{ semver.CheckConstraint ">= 1.5.0" .vars.version }}. See the Gomplate semver reference for the full list.

Get Involved​

We will fix forward. If a template that worked before this release fails after it, or quietly renders a different value, and the cause is not on the list above, open an issue with the template expression and the error. Where a gap can be closed with another compatibility shim, we will close it in a patch release. The goal of this upgrade was to change what ships in the binary, not what your stacks can do.

The Problem​

Bulk plans used to write the normal summary for every component, including "No Changes" results. In v1.221.0, we dropped those summaries as part of the refactoring work to support DAGs, where components run concurrently in dependency order (#2577). Bulk plans showed a single overview table instead. That overview was helpful for seeing which components changed, but it only expanded failed and changed components. To review any other plan in detail, you had to open the individual component logs.

The Fix​

Bulk plans keep the aggregate overview and bring back the normal summary for each executed component, including no-change results, as long as the summaries fit within the shared size limit. The summaries use the same CI templates and configured overrides as single-component plans, ordered by stack and component. Skipped components remain in the overview with their reason.

Durations are easier to read, using seconds, minutes, and hours.

If the summary cannot fit all component details, Atmos includes a warning with guidance for narrowing the plan's scope:

You can inspect omitted details in component logs. For successful plans, you can also use saved plan artifacts when available; failed plans do not produce plan artifacts.

How to Use It​

Run a bulk plan in CI as usual; no new configuration is needed:

atmos terraform plan --all -s dev --ci --max-concurrency 4

The same summary behavior applies to bulk plans selected with --components, --query, or --affected.

For a report that exceeds the size budget, narrow the selected components using tags or labels:

atmos terraform plan --all -s dev --ci --tags production
atmos terraform plan --all -s dev --ci --labels cost-center=platform

Replace these selectors with tags or labels defined on your components.

Get Involved​

See PR #3580 for the change, or open an issue if a bulk-plan summary is missing information you need to review your infrastructure changes.

The Problem​

Take a concrete instance that gets its module from an abstract base:

components:
  terraform:
    k8s_nodes/lxd/defaults:
      metadata:
        type: abstract
        component: lxd/talos-nodes
    k8s_nodes:
      metadata:
        inherits:
          - k8s_nodes/lxd/defaults

Terraform ran in the lxd/talos-nodes directory, while atmos describe component reported k8s_nodes as the component and template lookups through atmos.Component failed. The instance was using one identity for execution and another for everything around it.

The Fix​

The inherited value is now resolved before anything else consumes it, so the directory, descriptions, lookups, and affected detection all agree. The generated backend key follows the same value, matching a component that sets metadata.component itself:

Before You Upgrade​

This affects instances that inherit metadata.component, use a generated S3, GCS, or AzureRM backend, and don't set metadata.name or an explicit prefix or key. Their state remains at the old key, so Terraform starts from empty state at the new one:

Plan: 1 to add, 0 to change, 0 to destroy.

Applying that plan creates duplicate resources, and a later destroy removes only the duplicates. Review plans for these components after upgrading, and pause any auto-approved applies until you have handled them. Edition pins have no effect on this change.

To see the key for a component, run atmos terraform generate backend on the old and new versions and compare the output.

How to Use It​

Pick one of these for each affected instance.

Keep the existing key. Give the instance a stable metadata.name, or set workspace_key_prefix (S3), prefix (GCS), or key (AzureRM) directly:

components:
  terraform:
    k8s_nodes:
      metadata:
        name: k8s_nodes
        inherits:
          - k8s_nodes/lxd/defaults

Adopt the new key. Before the next apply, copy the state of every workspace whose path changes, for example from k8s_nodes/test-k8s_nodes/terraform.tfstate to lxd-talos-nodes/test-k8s_nodes/terraform.tfstate. On S3 that means every named workspace, because the prefix doesn't apply to the default workspace. On GCS and AzureRM it includes default as well. The next plan in each workspace should report No changes.

Get Involved​

If this upgrade affects you in a way these steps don't cover, open an issue or ask in Slack.

The Problem​

The auth-secrets plugin could read a store's conventional scalar value, but it could not select an arbitrary field from a Vault or OpenBao KV document. Vault-backed stores also could not consume credentials produced by a native Atmos identity, leaving ambient or static tokens outside the identity chain.

The Fix​

Secret references now use path for the document location and can name an exact top-level field. Identities map those credentials into their environment with explicit spec.env templates. Vault and OpenBao stores can also bind to a native Atmos identity that emits environment/v1 credentials containing VAULT_TOKEN.

When an identity is configured, its token is exclusive: Atmos does not fall back to options.token or an ambient VAULT_TOKEN if authentication fails. The resolved credentials remain isolated from the Atmos process environment.

How to Use It​

Configure a Vault or OpenBao secret store with an identity, then select the source field in an auth-secrets credential reference:

stores:
  platform:
    type: hashicorp-vault
    secret: true
    identity: openbao/session
    options:
      address: https://openbao.example.com
      mount: secret

auth:
  providers:
    deployment-secrets:
      kind: secrets/store
      spec:
        credentials:
          token:
            store: platform
            path: platform/deploy/example
            field: access_token
  identities:
    deployment:
      kind: secrets/env
      via:
        provider: deployment-secrets
      spec:
        env:
          SERVICE_TOKEN: '{{ .credentials.token }}'

The store's openbao/session identity must emit VAULT_TOKEN; the referenced document may use any top-level field name and may still contain a separate legacy value field. The deployment identity maps the selected credential into SERVICE_TOKEN for its child process. For hyphenated credential names, use a template such as {{ index .credentials "api-access-key" }}. Missing credential references fail authentication; plain strings stay literal.

Get Involved​

Try the native identity chain with a Vault or OpenBao KV v2 store and share feedback on field selection, token lifecycle, and error messages in the Atmos issue tracker.

The Problem​

The existing component retry configuration matches subprocess output for Terraform, Helmfile, Packer, and Ansible. Teams also need conditions on structured SDK errors and consistent retry controls for native Helm, Kubernetes, CloudFormation, containers, and emulators.

The Fix​

Policies can now select explicit error events such as terraform.init.error and kubernetes.apply.error. A policy accepts one event, a list, or a component wildcard such as terraform.*.error. The rule selects qualifying failures, and with configures the retry budget and backoff.

An initialization failure during a plan emits terraform.init.error. Terraform output lookups also have separate initialization, workspace, and output events. SDK integrations retry the failed call while preserving earlier successful steps.

How to Use It​

Save this document in your policy directory:

apiVersion: atmos/v1
kind: Policy
metadata:
  name: retries
spec:
  policies:
    retry-terraform-network-errors:
      description: >-
        Retry initialization, planning, and output retrieval when
        Terraform encounters transient network failures.
      on:
        - terraform.init.error
        - terraform.plan.error
        - terraform.output.error
      action: retry
      rule: input.output.matches('(?i)connection reset|TLS handshake timeout')
      with:
        max_attempts: 3
        initial_delay: 2s

    retry-kubernetes-unavailable:
      description: Retry apply calls when the Kubernetes API is temporarily unavailable.
      on: kubernetes.apply.error
      action: retry
      rule: input.error.message.matches('(?i)service unavailable')
      with:
        max_attempts: 3
        initial_delay: 2s

The maximum attempt count includes the first invocation. Each failure receives fresh output and error facts. A selected retry policy supplies one budget; it does not multiply the existing component retry budget. See retry settings and precedence for ordering, denial handling, and fallback behavior.

Get Involved​

Read the event and failure-input reference to adapt these policies to your components, and share feedback in GitHub Discussions.

View the AWS default tags example

The Problem​

A tagging example should make it easy to see where shared tags are defined and what each environment receives. Adding an organizational hierarchy, Git metadata, CI conditions, and naming rules at the same time makes that basic behavior harder to follow.

The Fix​

Each example has one shared component configuration and two stacks, dev and prod:

• AWS provider default tags: both stacks inherit managed-by and owner, then add their own environment tag. Atmos generates the provider configuration, so the S3 resource needs no tags argument.
• Null Label: both stacks inherit the same tags and supply a stage to the naming module. The module combines the supplied tags with generated Name, Namespace, and Stage tags. A built-in terraform_data resource shows the result without creating cloud resources.

The tagging strategy tutorial builds on these basics with an organizational hierarchy, source-control tag tradeoffs, provider limitations, and AWS enforcement guidance. The shared Terraform code tutorial explains how to distribute common files such as context.tf across components.

How to Use It​

The AWS example describes the merged tags without connecting to AWS:

atmos init examples/tagging-default-tags
cd tagging-default-tags

atmos describe component app -s dev --query .providers.aws.default_tags.tags
atmos describe component app -s prod --query .providers.aws.default_tags.tags

The example contains a real S3 bucket component. Planning or applying requires AWS credentials; applying creates a bucket. Provider default tags apply to supported resources, with exceptions such as Auto Scaling groups that need resource-specific tagging configuration.

The Null Label example plans locally without cloud credentials. Its first plan downloads the module:

View the Null Label example

atmos init examples/tagging-null-label
cd tagging-null-label

atmos describe component app -s dev --query .vars
atmos terraform plan app -s dev

When applying the resulting map to cloud resources, account for the target provider's tag or label restrictions. Null Label preserves supplied tags; it does not normalize them for each provider.

Get Involved​

Share tagging patterns or suggest another focused example in GitHub Discussions.

The Problem​

The documented atmos terraform backend list and describe commands were placeholders. They could not show a stack's configured backends or the settings inherited by a component.

The Fix​

Both commands now inspect merged backend configuration for any backend type. They do not authenticate, provision resources, run Terraform, or check whether remote storage exists. Templates and YAML functions remain unevaluated and appear as stored. Remote stack imports are rejected, and imports that require template evaluation cannot be resolved during inspection.

How to Use It​

List the concrete components that have backend configuration in a stack:

atmos terraform backend list --stack dev
atmos terraform backend list --stack dev --format=json

The default table is sorted by component name. Abstract components and components without a backend are omitted. JSON and YAML formats return an array of objects with stack, component, backend_type, and backend fields.

Inspect one component:

atmos terraform backend describe vpc --stack dev
atmos terraform backend describe vpc --stack dev --format=json

The default output is YAML. JSON output returns a single object with the same fields as a list entry. Missing stacks or components produce an error.

Get Involved​

See the backend command reference for all options. Report problems in Atmos issues.

The Problem​

The documented atmos toolchain aliases command was missing from the CLI. Aliases worked when installing or running tools, but checking their targets meant reading configuration files and accounting for built-in defaults yourself.

The Fix​

The command now lists built-in aliases together with aliases from the merged Atmos configuration. Configured aliases take precedence when names overlap. Output is sorted by alias name and shows each target as declared, without resolving it through a tool registry.

How to Use It​

List aliases in a table:

atmos toolchain aliases

Use structured output for scripts:

atmos toolchain aliases --format=json
atmos toolchain aliases --format=yaml

The command does not install tools or fetch tool registries. Configure mappings under toolchain.aliases in atmos.yaml.

Get Involved​

See the command reference for output options and examples. Report problems in Atmos issues.

The Problem​

A document with several shell lookups evaluated them serially. Even when the commands were independent, configuration loading took the sum of their runtimes. Parallelizing them required changing how values were gathered rather than configuring the evaluation itself.

The Fix​

Set one concurrency limit in atmos.yaml. Atmos runs up to that many expressions at once and assigns every result back to its original location. Serial execution remains the default.

How to Use It​

Configure the limit:

settings:
  functions:
    exec:
      max_concurrency: 4

Keep your stack expressions as they are:

vars:
  network: !exec ./lookup-network
  cluster: !exec ./lookup-cluster
  registry: !exec ./lookup-registry

These three commands can overlap. Their completion order does not change which value belongs to which variable, and JSON results retain their existing decoding behavior.

Use 1 for serial execution. Values below 1 are invalid. When enabling concurrency, you own dependencies between shell commands, including shared files and external state; Atmos does not infer them. Skipping !exec expressions still prevents their execution.

Get Involved​

Read the configuration reference and function reference. Share your use cases in GitHub Discussions.

The Problem​

Each release builds binaries for multiple operating systems and architectures, then packages and verifies them. Our review of downloads across 12 stable releases published from July 26 through October 20, 2026 found that these four targets accounted for fewer than 0.05% of binary downloads among the current release targets. These are cumulative asset downloads, not a count of active users.

Those targets still add compilation, linking, checksumming, and verification work to every release, and our cache warmups build them too. Removing them reduces the release matrix from ten binaries to six and the Linux package matrix from twelve packages to six. We expect shorter builds and releases; the actual time saved will depend on caching and parallelism.

Other large projects have also reduced their 32-bit distributions:

• Node.js 24 stopped providing prebuilt Linux ARMv7 binaries.
• Electron's July 2026 announcement identifies v43 as its last series with prebuilt Linux ARM and Windows x86 binaries, with support ending in January 2027.
• Debian 13's August 2025 announcement removed the i386 installer and kernel while retaining limited use of i386 packages on amd64 systems.

These changes provide context for retiring 32-bit downloads. Our decision to retire FreeBSD downloads is based on their low usage in our own release data.

The Fix​

Starting with the release containing this change, prebuilt downloads will cover six platform combinations:

New releases will no longer include Linux 386 or 32-bit ARM binaries and their DEB, RPM, or APK packages, or FreeBSD amd64 and arm64 binaries. Assets from previous releases remain available.

How to Use It​

On the affected platforms, install Go and build the latest stable Atmos release locally:

go install github.com/cloudposse/atmos@latest

Use a Go toolchain that supports your operating system and architecture and meets the selected Atmos release's requirements. Ensure Go's binary installation directory is on your PATH: this is GOBIN if configured, otherwise the bin directory under GOPATH (usually $HOME/go/bin).

For a specific release, replace @latest with its tag, such as @v1.233.0. Update automation that downloads release binaries to use this build step on the affected platforms. Download-based version switching also requires a published binary for your platform; use Go to install the desired version instead.

The Go installation instructions explain version reporting for locally built binaries. Compiling locally takes time and does not produce the signed release artifacts provided by our prebuilt downloads.

Get Involved​

If you rely on one of these downloads, open an issue describing your platform and installation workflow so we can understand the impact.

The Problem​

Scripts could start programs and read files, but could not supply a program's standard input or write a file. The script's explicit env inputs also differed from the inherited environment available to its subprocesses. That left scripts passing values as command arguments or relying on helper programs for ordinary input and output.

The Fix​

The process functions and Atmos command wrappers accept stdin, file writes use fs.write_file, and the predeclared os module exposes the effective environment, current directory, platform, and architecture. Scripts can change their own execution defaults without changing the host Atmos process. The env dictionary still contains only explicit step inputs, and process calls without stdin receive EOF.

How to Use It​

Read a token and send it through standard input:

token = os.getenv("TOKEN")
if token == None:
    fail("TOKEN is required")
exec.run(["some-tool", "--token-stdin"], stdin = token, output = "capture")

Input is sent exactly as supplied, without an added newline. Each retry receives the complete input again. Atmos excludes the payload from command diagnostics; the subprocess still controls its own output. The same stdin option is available on component process calls and all Atmos command wrappers, including atmos.secret. Pass any CLI flag that tells the receiving command to read stdin separately; the wrapper does not add that flag automatically.

Generate a local configuration file:

fs.write_file("config.json", json.encode({"region": os.getenv("AWS_REGION", "us-east-1")}))

New files default to owner-only read/write permissions. The parent directory must exist, and an existing file causes an error unless you pass overwrite = True. Overwriting preserves the file's existing permissions.

Inspect and adjust execution defaults:

original_directory = os.getcwd()
original_environment = os.environ()
print(os.platform, os.arch)
os.setenv("AWS_REGION", "us-east-1")
os.chdir("generated")  # This directory must already exist.
fs.write_file("config.json", json.encode({"region": os.getenv("AWS_REGION")}))
os.chdir(original_directory)

The os.environ() function returns a frozen snapshot; later changes do not alter it. The os.platform and os.arch attributes describe the running executable. The os.getcwd() function reads the script's current directory.

Call os.setenv() and os.chdir() only in the main thread. Parallel tasks inherit those settings and use per-call env= or working_directory= for their own overrides. Environment changes apply to subsequent process and step calls, including existing component handles. Directory changes affect relative file operations and default process and step directories; component calls retain their component directory. Neither operation changes the host process or another script invocation, and os.setenv leaves the declared env dictionary unchanged.

Get Involved​

See the automation function reference for the complete APIs. Share your scripting use cases in GitHub Discussions.

The Problem​

Secret storage and command authentication are separate concerns. Teams need to connect them without putting plaintext values in configuration, granting every command every secret, or tying plugin updates to an Atmos release.

The Fix​

The package provides a secret-store credential provider and an environment identity. Atmos controls the store references, masking, and authentication dependencies. The identity maps selected fields into the command environment, with a five-minute lifetime for process-local reuse.

Official packages use independent manifest versions and public OCI repositories. The built-in cloudposse catalog makes them discoverable, while consumers can opt out or configure another catalog. Installation selects one platform from the release index.

Plugin authors can use plugin release to build, test, package, publish, and sign a release. Native release planning and catalog reconciliation support independently versioned packages in one repository. One Linux job can cross-build every declared platform concurrently, run Linux tests, and prepare the OCI layout. A two-job workflow checks the inventory, then rebuilds and publishes through a protected release job. Atmos handles package iteration and catalog reconciliation without a package matrix, artifact transfer, or separate release scripts.

How to Use It​

Declare oci://ghcr.io/cloudposse/atmos/plugins/auth-secrets as a plugin package, configure a secrets/store provider, and map its credential fields through a secrets/env identity. See the complete configuration example.

Run atmos plugin install and commit the plugin lockfile before using the identity in CI. Each package version is independent of Atmos's version. Publication requires public GHCR provisioning and successful release checks and native SDK CI; source availability alone does not mean a version has been published.

Get Involved​

Read the plugin development guide to build your own package, or review the official release infrastructure.

kube = module.load("lib/kube.star")
kube.get("pods")

The library defines its functions directly. There is no export object to maintain and no need to repeat each function name in an import list.

This release also adds struct() records and typed YAML/JSON configuration with inline or reusable schemas, source-line diagnostics, and immutable deep merging.

Share functions between scripts​

Create lib/kube.star:

def get(resource):
    return exec.run(["kubectl", "get", resource])

module.load exposes the file's public functions and constants. Names beginning with _ remain private. Relative paths resolve beside the calling script, including calls inside loaded functions; inline scripts use their working directory.

The function works inside conditionals and parallel tasks. Successful loads share a cache with ordinary load(), so concurrent callers initialize a file once. Cyclic imports fail instead of waiting indefinitely, and canceling a waiting task does not cancel another task's initialization. Failed initialization can be retried, so top-level side effects should be repeatable.

Loaded globals are frozen. Library functions can create local collections, but cannot modify shared global lists or dictionaries after initialization.

Create records with named fields​

The new struct() constructor groups values for dot access:

service = struct(name="api", port=8080)
print(service.name)
output = service

Fields cannot be reassigned. Nested collections remain mutable until module loading or parallel execution freezes them. Data-only records encode as JSON objects; records containing functions cannot be JSON-encoded.

Load typed configuration​

config.load reads YAML or JSON with inline schemas:

cfg = config.load("app.yaml", schema={
    "database": {
        "host": str,
        "port": schema.field(int, default=5432, min=1, max=65535),
    },
    "debug": schema.field(bool, default=False),
})
print(cfg.database.port)

Reuse a JSON Schema file or an HTTPS schema:

cfg = config.load("app.yaml", schema="app.schema.json")
cfg = config.load("app.yaml", schema="https://example.com/schemas/app.schema.json")

Schemas can be JSON or YAML, from local files or HTTPS URLs; relative $ref documents resolve beside the schema. Inline schemas apply explicit schema.field defaults, reject unknown fields, and support lists, enums, and optional values. File schemas follow standard JSON Schema semantics, including annotation-only defaults.

config.validate checks existing values. Results are immutable copies with dot and index access. File validation errors include line and column numbers in YAML and JSON, plus the failing field path, for example:

app.yaml:2:9: database.port: expected int, got string

Both APIs work inside loaded functions and parallel tasks. HTTPS schemas support relative references, with cancellation, request timeouts, and bounded downloads. Remote schemas cannot reference local files.

Combine configuration​

Records support Atmos deep merging:

base = config.load("base.yaml", schema=app_schema)
overrides = config.load("prod.yaml", schema=override_schema)
cfg = base.merge(overrides)
cfg_with_tags = base.merge(overrides, list_merge_strategy="append")

Nested objects merge recursively and right-hand values take precedence. Lists replace by default; append and Atmos's merge by index are also available. The result is a new frozen record; both inputs remain unchanged. To enforce a schema on combined data, use config.validate(base.merge(overrides), schema=app_schema).

These APIs are available in standalone scripts, automation script steps, hooks, and their loaded helpers. YAML !starlark expressions and policy predicates keep their existing environments.

See the module loader reference, struct reference, configuration loading reference, and inline schema helpers for the complete behavior.

The Problem​

Executable settings can come from CLI configuration, stack inheritance, and component overrides. A command-line selection must remain effective after those settings merge. Different component families also used different flag names for the same purpose.

The Fix​

Use --command to select an executable name or path for the current invocation. The existing component-specific flags remain compatibility aliases. Supplying both spellings or an empty executable produces an error.

How to Use It​

For Terraform and OpenTofu:

atmos terraform plan app -s dev --command=tofu

The same option applies to Helmfile, Packer, and Ansible:

atmos helmfile template app -s dev --command=/usr/local/bin/helmfile
atmos packer inspect image -s dev --command=/usr/local/bin/packer
atmos ansible playbook app -s dev --command=/usr/local/bin/ansible-playbook

An executable override selects the subprocess-backed component tool. Arguments after -- still belong to that tool. SDK-backed component types do not have an executable to override.

Get Involved​

Share reproducible command-selection problems in Atmos issues.