That namespace may not exist. Native Helm creates it for you automatically, so a release deploys in a single operation instead of requiring a separate command, component, or workflow to create the namespace first.

Sometimes, though, the deployment should not be creating namespaces at all.

The Problem​

A Helm chart does not always specify the namespace where its resources should be installed. Atmos solves this by installing the release into the namespace configured for the component:

components:
  helm:
    backend-api:
      chart: "backend-api"
      namespace: backend-api

This keeps the release out of the default namespace, and native Helm creates the namespace automatically when it is missing, so the deployment is self-contained.

Automatic creation is not always wanted. When a platform team owns the namespace along with its labels, quotas, and NetworkPolicies, the release should not create it. And when the deploy identity is scoped to a single namespace and cannot create namespaces, the forced creation fails with a 403, even when the namespace already exists.

The Fix​

Native Helm components now support create_namespace. It defaults to true, so the namespace is created automatically as before. Set it to false to install into a pre-existing namespace instead:

components:
  helm:
    backend-api:
      chart: "backend-api"
      namespace: backend-api
      create_namespace: false
      values:
        replicaCount: 1

The release then deploys into the namespace that already exists, with no cluster-level permission to create namespaces:

atmos helm apply backend-api -s plat-ue2-dev

Left at its default, Helm creates the namespace when it is missing. Set to false, Helm installs into the namespace that is already there.

When to Use It​

Keep create_namespace enabled (the default) when the Helm deployment should manage its own namespace and the deploying identity has permission to create namespaces.

Set it to false when namespaces are managed separately, for example when a platform component is responsible for namespace labels, quotas, NetworkPolicies, or other guardrails, or when the deploy identity is scoped to a single namespace.

Get Involved​

Atmos is open source and we'd love your feedback. Join the conversation in the Atmos community Slack or open an issue on GitHub.

The Problem​

Atmos stack manifests support Go templates, and the Gomplate library supplies most of the functions and every datasource behind them. The version Atmos embedded, Gomplate v3, was built on the AWS SDK for Go v1. AWS retired that SDK, and its open advisories (GO-2022-0635 and GO-2022-0646) will never be resolved upstream because there will never be another v1 release.

Tools like OpenSSF Scorecard and dependency scanners do not distinguish between a library you call and a library that merely sits in your dependency tree. Every Atmos release showed the same findings, and the only honest explanation was that the code is present but never reached. That is not an answer anyone should have to keep giving. The only way to clear it was to remove the SDK from the build altogether, which meant upgrading the template engine across two major versions.

The Fix​

Atmos now embeds Gomplate v5, which is built on the AWS SDK for Go v2. Every Gomplate function and datasource that Atmos supported before continues to work, and Sprig functions are still layered on top by default. What changed 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 removed functions it had deprecated in v3 and changed a few datasource behaviors between v3 and v5. Most stacks will need no changes. If yours uses any of the following, update the template before upgrading. 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 unqualified aliases slice, contains, hasPrefix, hasSuffix, split, splitN, and trim are no longer registered by Gomplate. In practice most of them keep working: slice is a built-in of Go templates, and contains, hasPrefix, hasSuffix, split, and trim are also defined by Sprig, which Atmos enables by default through templates.settings.sprig.enabled. Be aware that Sprig's argument order differs from Gomplate's for some of these. The only alias with no fallback is splitN; replace it with strings.SplitN. If you have disabled Sprig, switch all of them to their strings.* or coll.* forms.

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. If a stack relied on the silent zero, guard the input first:

retries: '{{ if .vars.retries }}{{ conv.ToInt64 .vars.retries }}{{ else }}0{{ end }}'

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:

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:

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.

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​

If a template that worked before this release fails after it, and the cause is not on the list above, open an issue with the template expression and the error. The goal of this upgrade was to change what ships in the binary, not what your stacks can do.

The Problem​

A version in .tool-versions pins what you asked for. It does not pin what Atmos actually installed. Every atmos toolchain install command resolves that version against the live registry again. The exact download URL, checksum, and platform artifact are not fixed anywhere. Only the version number is fixed.

The Fix​

Toolchain installs now write a lockfile by default. You do not need to configure anything. Run atmos toolchain install. Atmos records the exact resolved version, download URL, checksum, and size for your platform. Installs skip a tool that already exists on disk, so an already-installed tool will not get a lockfile entry until you run atmos toolchain lock (or reinstall it with atmos toolchain install --reinstall). Once every tool has an entry, the next install resolves against the lockfile instead of asking the registry again, on your machine, a teammate's, or in CI. Reproducibility holds per platform: everyone on an operating system and architecture with a matching lock entry gets the same artifact, byte for byte.

If a project's atmos.yaml pins an edition dated before this change, the project keeps the old opt-in behavior. Nothing changes for a project that relied on the previous default. New and unpinned projects get the lockfile from the start.

How to Use It​

You do not need to opt in. Install as usual:

$ atmos toolchain install

Commit the resulting toolchain.lock.yaml file next to .tool-versions. If some of those tools were already installed before you ran this, run atmos toolchain lock too -- atmos toolchain install won't touch a tool it finds already on disk, so it can leave that tool's entry missing. Once every tool has an entry, every install resolves the exact pinned artifact for that platform. This applies on your machine, a teammate's machine, and a CI runner. Atmos does not resolve the version against the registry again.

The atmos toolchain command is still experimental. Its interface may change. The reproducibility does not depend on that.

Get Involved​

If you already use the toolchain, check whether toolchain.lock.yaml has an entry for every tool in .tool-versions. Run atmos toolchain lock to fill in any atmos toolchain install skipped because they were already installed, then commit the lockfile. If your installs still do not reproduce the same way across machines with matching lock entries, open an issue. That is exactly the gap this fix closes.

The Problem​

The same class of error can just as easily hit helmfile sync pulling a chart, packer build downloading a plugin, or ansible-playbook reaching a remote inventory. None of those got the same protection until now.

That gap got harder to miss once stacks could set retry once for the whole stack. A stack-root retry: block reads as "every component here recovers from this." But that was only true for the Terraform components.

The Fix​

retry: now works the same way for every component type that shells out to a binary. Terraform, Helmfile, Packer, and Ansible all share the same retry engine. It captures the subprocess output, matches it against your conditions regex patterns, and retries with backoff only on a match.

components:
  helmfile:
    myapp:
      retry:
        max_attempts: 5
        backoff_strategy: exponential
        initial_delay: 2s
        conditions:
          - /Bad Gateway/
          - /connection reset/
  packer:
    ami:
      retry:
        max_attempts: 3
        conditions:
          - /rate limit/

Nothing changes for existing Terraform retry configuration. This change only adds new coverage. A real failure still fails immediately. Examples include a bad Helmfile release, a Packer template error, or a broken playbook. Only output that matches your conditions triggers a retry.

How to Use It​

Add retry: to any Helmfile, Packer, or Ansible component the same way you would for Terraform. See the component retry docs for the full field reference. A stack-root retry: block now protects every supported component in the stack.

Native Kubernetes and native Helm components don't shell out to a binary. They call Go SDKs directly. So they aren't covered by this change yet. That gap is tracked as a follow-up.

Get Involved​

Open a discussion in the Atmos repo. Let us know if you hit a transient failure pattern in Helmfile, Packer, or Ansible that conditions doesn't catch cleanly.

The Problem​

Both atmos scaffold generate and atmos init could already pull templates from git, HTTPS, and S3 sources, but nothing else. A team standardizing on OCI for internal distribution — components, container images, Helm charts — had no way to publish a scaffold template the same way. Templates were the one artifact type still forced onto a separate channel.

The Fix​

Both commands now accept an oci:// source directly, pulled through the same client Atmos already uses for atmos vendor pull and just-in-time component provisioning. Authentication follows the identical precedence: Docker credentials from docker login, then ATMOS_GITHUB_TOKEN for ghcr.io, then anonymous — nothing new to configure if OCI sources are already working elsewhere in the project.

How to Use It​

Point either command at an OCI reference the same way you would a git URL:

atmos scaffold generate oci://ghcr.io/example/templates:v1.0.0 ./components/terraform/vpc
atmos init oci://ghcr.io/example/templates:v1.0.0 ./my-project

A version lives directly in the reference (:v1.0.0), the same way an OCI vendor source is pinned — there's no separate --ref flag to learn for this case, since that flag only ever applied to git sources. --update's three-way merge, --git/--no-git, and --base-ref all work exactly as they already do for every other source type: the merge base always comes from the generated project's own git history, never from re-fetching the template, so switching a template to OCI changes nothing about how updates behave. A scaffold.templates entry in atmos.yaml can point at an oci://... source too, right alongside existing git-hosted entries.

Get Involved​

Open an issue with feedback, or let us know what registry you're publishing scaffold templates to.

The Problem​

Component retry matches transient failures against conditions regex patterns and retries with backoff. That mechanism works well for one component. Restructuring unrelated components to share an abstract base just so they inherit a policy, or setting up a mixin file with overrides.retry and importing it everywhere, gets you there too — but none of those match the real goal: every component in this stack should recover the same way, without extra plumbing.

The Fix​

Stacks now accept a top-level retry: block. This works the same way as the existing top-level vars, metadata, and hooks blocks. Set it once at the root of a stack manifest. Every supported component in that stack then picks it up:

retry:
  max_attempts: 5
  backoff_strategy: exponential
  initial_delay: 2s
  max_delay: 30s
  conditions:
    - /Bad Gateway/
    - /GOAWAY/
    - /could not query provider registry/

components:
  terraform:
    vpc:
      # ...
    transit-gateway:
      # ...

A concrete component's retry: overrides stack and abstract-base values for keys it sets. Missing keys inherit from lower-precedence layers. The full precedence order, lowest to highest, is: stack-level default → abstract base component → concrete component → overrides.retry.

How to Use It​

Add retry: to the root of any stack manifest, alongside vars: and components:. You need no mixin file, no shared base component, and no per-component copies:

retry:
  max_attempts: 3
  conditions:
    - /Bad Gateway/
    - /connection reset/

components:
  terraform:
    vpc:
      vars:
        name: vpc
    rds:
      vars:
        name: rds

Both vpc and rds retry on the same conditions without either one declaring retry: itself. If one component needs a different policy, set retry: directly on that component. Its values override lower-precedence layers unless overrides.retry sets the same keys. Missing keys continue through the precedence chain.

The mixin pattern from the component retry docs is still the right tool for a policy that applies to only part of a stack.

Get Involved​

Open a discussion in the Atmos repo or post in the SweetOps Slack. Let us know if you hit a retry scenario that the current scoping (stack, base component, component, overrides) doesn't cover well.

The Problem​

In a scaffold template, select and multiselect fields normally take their choices from options:, a static list fixed at authoring time. That's fine when the choices really are fixed, but two situations don't fit:

• Narrowing to a previous answer. Someone selects their environments (dev, staging, production) via a multiselect; a later select field should default to offering just those chosen environments — not the entire list the template supports.
• Friendly labels vs. stored values. You want to display something readable while still storing the actual value (dev/staging/production) that generated files and conditions rely on. Previously this meant either showing raw values on screen, or hand-maintaining a separate label mapping elsewhere in the template.

A static options: list can't handle either case — it's decided once and never revisited.

The Fix​

A field's options: can now be computed dynamically, using the same answers.-dot-path syntax and Go-template conventions already available elsewhere in scaffold templates:

spec:
  fields:
    - name: envs
      type: multiselect
      options: [dev, staging, prod]
    - name: default_env
      type: select
      options: answers.envs

If someone picks staging and prod, default_env will only offer those two — dev is excluded. The source field doesn't need to be a multiselect; a plain text input works too, combined with a template expression that converts it to a list:

spec:
  fields:
    - name: csv_owners
      type: input
      default: "platform-team,security-team"
    - name: primary_owner
      type: select
      options: '{{ splitList "," answers.csv_owners }}'

Both forms resolve options: based on whatever was supplied for the earlier field, whether answers come from an interactive prompt or are passed in non-interactively.

The same options: field also accepts a list of label/value pairs, so what's displayed and what's stored can differ:

spec:
  fields:
    - name: envs
      type: multiselect
      options:
        - label: Development
          value: dev
        - label: Staging
          value: staging
        - label: Production
          value: prod
    - name: default_env
      type: select
      options: answers.envs

Here, envs displays "Development," "Staging," and "Production" while storing dev/staging/prod everywhere they're actually needed — generated files, when: conditions, and other fields' options:. Since default_env pulls its choices dynamically from envs, it inherits those same friendly labels for whatever was picked, rather than falling back to raw stored values.

How to Use It​

Point options: at answers.<field> (or a template expression) on any select/multiselect field to source its choices from an earlier answer instead of a fixed list, and switch a plain string list to label/value object entries wherever the stored value and the display text should differ. See the atmos scaffold generate docs for the full field reference.

Get Involved​

Open an issue with feedback, or share templates that put dynamic options to use in your own projects.

Even teams already on Native CI run into a quieter version of the same problem: a setting that doesn't take effect looks exactly like one that does. Maybe ci.enabled is set on one profile but not another, or an Atmos Pro workspace never got configured in the first place — nothing errors either way. The pipeline finishes green, and the first symptom is a status check or an upload that isn't there, discovered days later.

The Problem​

Confirming any of it meant checking for side effects after the fact: did the expected status check show up, did the drift upload happen, is this pipeline still wired to a marketplace action. None of that was visible from the CI run itself, so a misconfigured pipeline was only ever discovered because something else broke first.

The Fix​

Atmos now prints a short status banner the moment it detects it's running inside a CI provider: the version, whether Native CI mode is on or off, and whether Atmos Pro is configured. If it's invoked from one of the older marketplace actions, it also warns directly in the run log and points at migrating to Native CI — which has more features, gets tested end-to-end as part of the Atmos core test suite, and is where all future investment is going. Teams still on the legacy actions should treat this as a prompt to move now, not eventually.

▶ Atmos version 1.228.0 linux/amd64
✓ Atmos CI is enabled; learn more at https://atmos.tools/ci
✗ Atmos Pro is disabled; learn more at https://atmos.tools/pro

⚠ Detected legacy action cloudposse/github-action-atmos-terraform-plan; migrate to Native CI for better performance — learn more at https://atmos.tools/ci

How to Use It​

There's nothing to configure — the banner appears automatically at the start of every atmos command you run inside a detected CI provider, and it's a complete no-op on a local machine. It reads the same ci and settings.pro configuration you already have, so what it reports always matches your actual setup.

Get Involved​

Atmos is open source and we'd love your feedback. Join the conversation in the Cloud Posse community or open an issue on GitHub.

The Problem​

Atmos talks to a lot of TLS endpoints — cloud provider APIs, git servers, artifact registries, the Terraform module registry. Every one of those connections depends on the cryptography built into the Go runtime atmos is compiled with. Until now, nothing about that cryptography was validated or restricted to FIPS-approved algorithms; it just used whatever Go's standard library picked. Operators who needed a FIPS 140-3 claim for their toolchain had no way to get one from an official atmos release.

The Fix​

Every officially released atmos binary — along with every binary built from a checkout using atmos build — now links Go's own FIPS 140-3 crypto module and defaults to enforcing FIPS 140-3 mode at runtime. Go standard-library TLS connections, key generation, and hashing are restricted to FIPS-approved algorithms and key sizes automatically. No flag, environment variable, or config change is required.

This covers the TLS and cryptography atmos itself uses for outbound connections, and it's FIPS 140-3 mode — enforced by Go's runtime — not a CMVP compliance certification for the atmos binary itself. Declarative secrets management (atmos secret keygen and the age-based SOPS backend, along with the sealed values atmos pushes to GitHub Actions secrets) relies on its own encryption, chosen for compatibility with those specific ecosystems, and sits outside Go's FIPS module boundary entirely — worth knowing if your compliance program needs FIPS coverage across secrets handling too.

How to Use It​

Nothing to opt into — every current and future atmos release ships this way by default. To confirm it on any binary, ask atmos itself:

atmos version --format=json

{
  "version": "1.226.1",
  "os": "darwin",
  "arch": "arm64",
  "fips": true
}

If you'd rather check without atmos installed yet — say, auditing a downloaded binary — any standard Go toolchain can tell you the same thing:

go version -m ./atmos | grep -i fips

build   DefaultGODEBUG=fips140=on
build   GOFIPS140=latest

Get Involved​

Have feedback on this, or a compliance requirement it doesn't yet cover? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Terraform and OpenTofu support -lock-timeout=<duration> to poll for a held lock instead of failing immediately, but it has to be typed on every single invocation. TF_CLI_ARGS_<command> can automate it, but it is a single flat string rather than a structured, independently merged flags: block — so a component that wants to override one flag has to restate the rest or lose them. Teams running concurrent CI matrices, or Atmos Pro-driven deployments, would hit avoidable failures from Terraform's 0s default when no lock timeout is configured.

The Fix​

Terraform CLI execution flags — lock_timeout, lock, parallelism, refresh, and compact_warnings — can now be declared once under a flags: block: globally in atmos.yaml, for an entire stack, or for a single component, with each layer overriding the one before it. An ATMOS_COMPONENTS_TERRAFORM_FLAGS_* environment variable can override the atmos.yaml default too — the same environment-variable handling every other Atmos setting already gets, not a special case invented for these five flags. An explicit flag typed directly on the command line still wins over every declared default, so nothing about existing one-off usage changes.

Atmos only injects a flag into commands that actually support it — for example -refresh isn't valid when applying a saved plan, and terraform import doesn't accept -parallelism — so you don't have to track those exceptions yourself.

How to Use It​

# atmos.yaml — fleet-wide default
components:
  terraform:
    flags:
      lock_timeout: "5m"
      parallelism: 10

# stack manifest — applies to every terraform component in this stack
terraform:
  flags:
    lock_timeout: "5m"

components:
  terraform:
    vpc:
      # per-component override
      flags:
        lock_timeout: "10m"

# one-off override still works exactly as before, and always wins
atmos terraform plan vpc -s plat-ue2-dev -- -lock-timeout=30s

# environment variable overrides the atmos.yaml default — handy for a per-CI-job
# tweak without touching the fleet-wide config
ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK_TIMEOUT=2m atmos terraform plan vpc -s plat-ue2-dev

Why not just use TF_CLI_ARGS?​

Yes, you could. Atmos's env: section also merges by stack and component. Set env: { TF_CLI_ARGS_plan: "-lock-timeout=5m" }, and it scopes the same way flags: does.

But TF_CLI_ARGS_plan is one flat string with no separate fields. If a component overrides -parallelism, it must also restate -lock-timeout, or the component loses that value.

Fields in flags: merge one at a time. A component can override parallelism alone and still inherit lock_timeout from the stack. Every other Atmos section merges the same way.

Get Involved​

See the Terraform Configuration docs for the full field reference, defaults, and environment variable overrides. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Custom command steps already supported when: conditions built on CEL — ci, stack, component, and more — but a step could never see the values the user actually passed to the command that's running it:

commands:
  - name: deploy
    flags:
      - name: dry-run
        type: bool
    steps:
      - type: shell
        command: terraform apply
        # No way to reference --dry-run here.

The flag values were already being extracted for Go/gomplate templates as {{ .Flags.dry_run }}, but that data never reached the CEL evaluator, so when: conditions couldn't use it.

The Fix​

when: expressions can now read flags and arguments, mirroring the same data already available to steps in templates. component is also resolved for custom commands now, the same way it already was for component hooks — via a semantic-typed flag or argument.

How to Use It​

commands:
  - name: deploy
    flags:
      - name: dry-run
        type: bool
    steps:
      - type: shell
        command: terraform apply
        when: !cel '!flags["dry-run"]'

See the custom command steps docs for the full list of available when: facts.

Get Involved​

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

The Problem​

Terraform, Helmfile, Kubernetes, and Helm components have always resolved their working directory the same way: a configurable base_path per component type, joined with the component's own name, computed once and used consistently no matter where atmos is invoked from. Container components never got wired into that mechanism. build.context and build.dockerfile were passed straight through to docker build/podman build with no anchoring at all, and run.mounts[].source anchored only to the bare project root — never to the component itself. components.container.base_path existed in the config schema, but nothing ever read it.

The Fix​

Container components now resolve build.context, build.dockerfile, and run.mounts[].source the same way every other component type does: relative to components.container.base_path (default components/container) joined with the component's own name, independent of the directory atmos happens to be invoked from. components.container.base_path is now a real, working setting. Container components also gained the same just-in-time source provisioning as Terraform and Helmfile components — a component that declares source: is now auto-vendored into a workdir, and that workdir becomes the anchor for build and mount paths instead of the static base path.

Breaking Change​

If your container component's build.context, build.dockerfile, or run.mounts[].source are relative paths, they now resolve against <base_path>/<component-name>/ instead of the previous CWD-dependent (build) or bare-project-root (mounts) behavior. Update your setup one of two ways: move build assets under components/container/<component-name>/ to match the same convention Terraform components already use, or point components.container.base_path at wherever your container build assets currently live.

How to Use It​

# atmos.yaml
components:
  container:
    base_path: components/container   # default

components:
  container:
    api:
      build:
        context: app           # resolves to components/container/api/app
        dockerfile: Dockerfile  # resolves to components/container/api/app/Dockerfile

Get Involved​

Try it out with an existing container component or a fresh one. Questions or ideas? Start a thread in GitHub Discussions, or open an issue in the issue tracker.

The Problem​

The Version Tracker's marker manager rewrites version tokens on lines annotated with an atmos:version comment — but JSON has no comment syntax, so there's no line to annotate. The template manager covers formats like this by rendering a *.tmpl source to a sibling output file, but that means maintaining a template and a generated file as two files that have to be kept in sync by hand every time an unrelated field in the JSON document changes.

The Fix​

A new json file manager writes locked values directly into JSON files at configured field paths. It patches only the targeted field and leaves everything else in the document — key order, spacing, unrelated fields — exactly as it was, so atmos version track apply produces a minimal, single-field diff instead of a fully reformatted file.

How to Use It​

version:
  dependencies:
    atmos:
      ecosystem: github/actions
      datasource: github-releases
      provider: github
      package: cloudposse/atmos
      desired: "~1.160"

  files:
    - manager: json
      paths:
        - package.json
      options:
        set:
          - path: version
            from: atmos

A single rule can target more than one file, and a single file can carry more than one managed field — each just needs its own path/from entry under set:

  files:
    - manager: json
      paths:
        - package.json
      options:
        set:
          - path: version
            from: cli
          - path: engines.node
            from: node

atmos version track apply rewrites every configured field from the lock; --check fails and lists any file that's out of date, so CI can catch drift before it merges.

Get Involved​

See the Version Files docs for the full path/from syntax, including array indexing and escaping keys that contain literal dots. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

--profile activates one or more named configuration overlays — dev settings, CI settings, security overrides, whatever a project defines. But the flag always required an explicit value. Typing --profile alone, expecting the CLI to prompt you the way -i/--identity already does when used bare, instead produced a raw usage error:

$ atmos auth login -i core-auto/terraform --profile
Incorrect Usage
Error: --profile flag needs an argument for command atmos auth login

The Fix​

--profile with no value now opens an interactive multi-select listing every profile Atmos discovers across your configured profile locations. Nothing is checked by default — toggle the ones you want with space, confirm, and they activate left-to-right in the order shown, exactly as if you'd typed them explicitly.

Any profile name you already typed alongside the bare flag starts pre-checked, so --profile ci --profile opens with ci already selected, ready to confirm or adjust. In a non-interactive context — CI, scripts, no TTY — bare --profile returns a clear error instead of hanging or guessing, so automation fails fast rather than silently.

How to Use It​

# Interactively choose which profiles to activate
atmos auth login -i core-auto/terraform --profile

# Explicit values still work exactly as before
atmos --profile developer terraform plan vpc -s prod
atmos --profile ci,security terraform plan vpc -s prod

Get Involved​

See the Profiles docs for the full behavior, including profile discovery order and merge precedence. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

type: container steps take their configuration under with: (and, for the driver, a nested driver: block) as a typed mapping — run, build, push, and inspect actions each have a fixed set of real fields. But nothing checked that the keys you wrote were actually among them. A typo'd field name, a field copied from Docker Compose that doesn't exist in Atmos, or a straight-up nonexistent option all decoded the same way: silently discarded, with the rest of the mapping loaded normally. The step would run — just without the setting you thought you'd configured.

The Fix​

with: and driver: blocks on container steps now reject unknown fields outright, in both standalone workflow files and custom commands. A typo like platforms: (not a real field) now fails the step with a clear decode error naming the field, instead of quietly doing nothing.

Breaking Change​

If a with: or driver: block on a type: container step currently has a field that isn't one of the real, documented fields, it will now fail to load instead of being silently ignored. Check your container steps for typos or leftover fields from a different tool's config format before upgrading.

Also in This Release: Local Backend State Was Being Deleted on Re-Provision​

If you used a local Terraform backend on a component with just-in-time (JIT) workdir provisioning enabled, your state was gone after the second run. Not corrupted — deleted, cleanly, with no error. apply would create it, and the very next plan would silently start over with an empty state, because the workdir provisioner's incremental sync treated the state file the same way it treats any file that isn't part of your component's source: not present in source, so remove it. terraform.tfstate was never protected from that cleanup the way provider lock files already were.

The workdir provisioner now leaves terraform.tfstate, terraform.tfstate.backup, and the transient .terraform.tfstate.lock.info marker alone, in both directions — never copied in from source, never deleted from the workdir. If you were working around this by avoiding JIT workdir provisioning for local-backend components, that workaround is no longer necessary.

Also in This Release: Workdir Path Encoding​

Separately, the internal .workdir/ directory Atmos uses for JIT component provisioning now encodes component and stack names more carefully, to guarantee two differently named components (e.g. one named app/local and another named app-local) can never accidentally resolve to the same on-disk directory and share files or state.

This changes the on-disk directory name for any component whose name contains a literal -, /, or \. Atmos migrates a workdir it finds at the old location automatically the next time that component is provisioned, so this should be transparent for most setups.

The Problem​

Atmos Auth already supports Application Default Credentials, Workload Identity Federation, and service account impersonation. GKE access still required a separate authentication flow outside Atmos, though. That created two sources of truth for identity selection and added external tools to local and CI environments solely to prepare kubeconfig.

The gap was especially visible with native Helm components: Atmos could resolve the intended GCP identity, but an ambient kubeconfig could still point Helm at a different cluster.

The Fix​

The new gcp/gke Auth integration links a GKE cluster to an existing GCP identity. When Atmos selects that identity, it uses the GKE API to discover the cluster endpoint and CA certificate, writes an Atmos-managed kubeconfig, and injects its path into child commands:

auth:
  providers:
    example-gcp:
      kind: gcp/adc
      spec:
        project_id: example-project

  identities:
    example-deployer:
      kind: gcp/project
      via:
        provider: example-gcp
      principal:
        project_id: example-project

  integrations:
    example-gke:
      kind: gcp/gke
      via:
        identity: example-deployer
      spec:
        cluster:
          name: example-cluster
          project_id: example-project
          location: us-central1
          alias: example

Run Kubernetes tools through the selected identity without a preparatory gcloud command:

atmos auth exec --identity example-deployer -- kubectl get nodes

The generated kubeconfig uses atmos gcp gke token as a Kubernetes exec credential plugin. Kubernetes requests a fresh short-lived token when needed; the token and its expiration are returned as ExecCredential JSON and are never stored in kubeconfig.

Guard Native Helm Targets​

Native Helm keeps its existing ambient-kubeconfig behavior by default. Components that must use an Atmos-provisioned GKE identity can opt into a fail-closed endpoint check:

components:
  helm:
    example-release:
      auth:
        require_identity: true
        identities:
          example-deployer:
            default: true

For live plan, apply, and delete operations, Atmos provisions the linked integration and verifies that Helm's effective Kubernetes API endpoint matches the endpoint returned by GKE before any cluster request. Offline template and manifest-baseline operations remain credential-free.

Security Boundaries​

• The kubeconfig stores the HTTPS endpoint, CA certificate, context, and exec-plugin command—not a bearer token.
• The GCP identity needs permission to describe the cluster, normally container.clusters.get.
• Kubernetes RBAC remains separate and determines what the authenticated principal may do inside the cluster.
• Explicit plaintext GKE API endpoints are rejected rather than written to kubeconfig.

See the GKE kubeconfig authentication command documentation for configuration, update modes, permissions, and troubleshooting details.

Get Involved​

Try the integration with your GCP identity chain and GKE clusters. Share feedback in the Cloud Posse community or open an issue on GitHub.

The Problem​

The number of files a project needs often depends on what gets selected when the project is generated. Pick three environments out of five, and you want three stack files, not five. That output was already possible: declare all five stack files in the template up front, and gate each one with its own when: on whether that specific environment got picked. The real cost was authorship — five nearly-identical files, one per environment the template author had to anticipate, kept in sync by hand as the shared parts drifted. Nothing let a template say "generate one of these per selected value" from a single file; only "generate this specific file" or "skip this specific file."

The Fix​

Declaring matrix: on a file entry expands it into one generated file per combination of one or more axes. It reuses the same shape Atmos workflow matrix: steps already use, so the syntax should feel familiar. when: still prunes combinations that don't apply — the same conditional engine that already gates whole files, now scoped to a single combination at a time:

spec:
  fields:
    - name: environments
      type: multiselect
      options: [dev, staging, production]
  files:
    - path: stacks/deploy/environment.yaml
      target: "stacks/deploy/{{ .matrix.environment }}.yaml"
      matrix:
        environment: answers.environments

Selecting dev and staging generates exactly stacks/deploy/dev.yaml and stacks/deploy/staging.yaml. Declaring more than one axis expands their full combination, and each resolved combination is available as .matrix.<axis> in Go-template fields such as the output path and generated content, and as matrix.<axis> in when: conditions — so a file can name itself and branch on its own combination.

Computed axes​

Real answers aren't always a flat, pre-selected list. Say environments were a structured answer instead of a multiselect — supplied through --set or a preset value — shaped like this:

environments:
  dev:
    regions:
      us-east-1: {}
  production:
    regions:
      us-east-1: {}
      us-west-2: {}

The full list of regions actually used isn't something anyone picked directly — it has to be derived from every environment's own regions. The collectKeys function does that: called with one argument, it returns a map's keys; called with a second argument, it collects that key from every value in the map, flattening and deduplicating across all of them.

files:
  - path: deploy.yaml
    target: "deploy/{{ .matrix.environment }}/{{ .matrix.region }}.yaml"
    matrix:
      environment: '{{ collectKeys answers.environments }}'
      region: '{{ collectKeys answers.environments "regions" }}'
    when: "matrix.region in answers.environments[matrix.environment].regions"

environment resolves to dev and production; region resolves to every region used by any of them (us-east-1 and us-west-2). Their combination fans a single deploy.yaml out into deploy/dev/us-east-1.yaml, deploy/production/us-east-1.yaml, and deploy/production/us-west-2.yaml — target: names each one from .matrix.<axis>, and when: prunes the combination down to each environment's actual regions, so dev never gets a us-west-2 file.

How to Use It​

The scaffolding-matrix example is a minimal, runnable template — one multiselect field driving one matrix axis:

cd examples/scaffolding-matrix
atmos scaffold generate example ./my-project

Answering the environments prompt with dev and staging generates stacks/dev.yaml and stacks/staging.yaml from the template's single environment.yaml file — or skip the prompt entirely with --set environments=dev,staging for scripted, non-interactive use. Add matrix: to any spec.files[] entry alongside target: to do the same in your own templates, using a literal list, a multiselect answer, or a computed expression for each axis.

Get Involved​

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

The Problem​

A container component's run config could publish ports to the host, but two container components in the same stack — or a container and a local emulator — had no way to talk to each other directly. A workflow step that spun up a one-shot container to run tests against those services hit the same wall. The only fix was manual: create a network by hand, or fall back to routing everything through the host.

The Fix​

Every container component, one-shot container run, and stack-scoped workflow type: container step now automatically joins a shared network for its stack and gets a predictable DNS alias — no configuration required. It's the same idea as the network Docker Compose creates for a project, scoped to your Atmos stack instead.

• A component named api in stack dev is reachable at dev-api.
• An emulator and a container component in the same stack land on the same network, so either can resolve the other by name.
• A workflow run step that resolves a stack (its own stack: field, or the workflow's --stack/ATMOS_STACK) joins that same network too, so a test-runner step can hit http://dev-api:80 directly.

It's best-effort: if the container runtime can't create or join a network, everything still runs — you just lose the ability to resolve peers by name, and host-published ports keep working exactly as before.

How to Use It​

Nothing to turn on. Bring up two services in the same stack and reference one from the other by its <stack>-<component> alias:

components:
  container:
    api:
      image: localhost:5001/api:latest
      run:
        ports:
          - host: 8080
            container: 80

    worker:
      image: localhost:5001/worker:latest
      run:
        command: ./worker --api-url=http://dev-api:80

atmos container up api -s dev
atmos container up worker -s dev
# worker resolves dev-api on the shared network — no host port juggling needed.

The same alias works from a workflow run step scoped to the same stack:

steps:
  - name: smoke
    type: container
    action: run
    stack: dev
    with:
      image: curlimages/curl
      command: curl -f http://dev-api:80/health

Get Involved​

Try it out with a couple of container components or an emulator in the same stack. Questions or ideas? Start a thread in GitHub Discussions, or open an issue in the issue tracker.

Resolving that import still had rough edges. Git fetch authentication was separate from a developer's GitHub CLI session, so gh auth login alone was not enough for a private import. A broken import failed silently: a tag name with a typo, an unreachable host, or a token without read access all added nothing to the configuration, with no warning. And a git:: import with a subdirectory re-cloned on every single command, even when nothing had changed.

Atmos already reused a developer's GitHub CLI session for other GitHub operations, such as toolchain installs. Atmos now reuses that same session for private git:: imports too. This applies to both stack configuration imports and atmos.yaml configuration imports. Atmos also warns you when an import fails. Atmos also lets you cache imports to avoid unnecessary re-fetching.

The Problem​

• Git fetch authentication was separate from GitHub CLI authentication. A private git:: import used its own credential chain. This chain did not include the GitHub CLI. A developer who ran only gh auth login still needed a separate token for private imports to work.
• A broken import failed with no warning. A typo in a ?ref= value, an unreachable host, or an unreadable private repository all produced the same result. The import added nothing to the configuration. No error appeared. The command exited successfully.
• Every command re-cloned a git:: import. A root atmos.yaml import that pointed at a subdirectory in a Git repository had no cache. A command as simple as checking the current identity re-cloned the remote repository first.

The Fix​

• Private git:: imports now fall back to a developer's GitHub CLI session automatically. This covers config imports, vendoring, and private Terraform module fetches. Atmos already used this fallback for other GitHub operations. If gh auth login is already done, no other setup is needed.
• A remote import: entry that fails to resolve now prints a warning by default. The warning names the import path and the underlying error. The command no longer continues silently with an empty or partial configuration.
• Set imports: { ttl: ... } once in atmos.yaml to apply the same expiry policy to every remote import form. A git:: import with a subdirectory then reuses its clone across commands instead of re-cloning every time. A plain remote URL, or a git:: import without a subdirectory, then expires after ttl instead of being cached forever. The two forms track freshness differently under the hood (a marker file in the cloned directory for the first, a cache entry for the second), but ttl now governs both.

How to Use It​

Sign in once. Private imports then work automatically:

gh auth login

If an import breaks, Atmos reports it immediately:

WARN  failed to resolve import path="git::https://github.com/acme/config.git//auth.yaml?ref=v1.2.3" error="..."

Set a cache TTL to stop re-fetching a stable, pinned git:: import on every command:

imports:
  ttl: 5m

import:
  - "git::https://github.com/acme/config.git//auth.yaml?ref=v1.2.3"

Leave ttl unset to keep each import form's default: a git:: subdirectory import refreshes on every command, and a plain remote URL is cached forever. Set ttl once to apply the same expiry to every remote import in the file, of either form.

Get Involved​

Did you find another case where a remote import fails silently? Did you find an operation where GitHub CLI auth does not reach, but should? Open an issue. Include the command and the result you saw.

The Problem​

--update re-runs a template against an existing project and 3-way merges the result. Scaffold picks its merge algorithm by file extension: YAML-aware for .yaml/.yml, line-oriented text for everything else. The YAML-aware path is what makes the complex merges possible in the first place—but re-encoding the whole document through a YAML parser and serializer means anything the parser doesn't model, blank lines between top-level blocks being the common case, gets dropped unconditionally. That's a real cost for files where formatting is a convention—many CI pipeline definitions use blank lines to visually separate jobs, stages, and other top-level blocks.

The Fix​

--merge-driver lets you override which merge algorithm runs, named after git's own merge driver concept:

• auto (default, unchanged) — YAML-aware for .yaml/.yml, text otherwise.
• text — forces every file, YAML included, through a line-oriented, diff3-style merge. Comments, blank lines, and other structural formatting the YAML-aware merger doesn't model are preserved in non-conflicting regions.

Because it's a flag on the --update invocation itself, not a project-wide setting, you're not choosing one mode for the project's entire lifetime. Most updates can stay on the default auto merge, and you reach for --merge-driver=text on the specific update that needs it—bundle up a template's formatting-sensitive changes (a CI pipeline overhaul, say) and pull them in with one deliberate --merge-driver=text run, rather than running every future update through the coarser text merger just to protect that one file.

This is a different axis from --merge-strategy, which decides how a genuine conflict resolves (manual, ours, or theirs) once a merge algorithm has already run. --merge-driver decides which algorithm runs in the first place.

How to Use It​

# Everyday updates: the default auto merge is usually what you want.
atmos scaffold generate my-template ./my-project --update

# This update brings in a batch of formatting-sensitive template changes—
# override the driver just for this run.
atmos scaffold generate my-template ./my-project --update --merge-driver=text
atmos init --update --merge-driver=text

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.