cloudposse/atmos v1.208.1-rc.1

on GitHub

Implement a ttl (time-to-live) field on component source configuration to control how long cached JIT-vendored sources are reused before re-pulling from the remote. This solves the problem of stale caches when using floating refs (branches) without requiring manual --force flags.

Key Feature: Declarative cache expiration policy. Set ttl: 0s for active development (always fresh), ttl: 1h for team collaboration (hourly refresh), or omit TTL for infinite cache (backward compatible).

Problem Solved

When JIT-vendored components use floating refs like version: "main", Atmos skips re-pulling because the version string in metadata hasn't changed—it's still "main" even though upstream content has. Developers must manually delete .workdir/ or run source pull --force.

Solution

Add optional ttl field to source configuration. When set, the source provisioner compares the workdir's update timestamp against the TTL. If expired, the source is re-pulled automatically.

# Per-component override (stack manifest)
components:
  terraform:
    my-module:
      source:
        uri: git::https://github.com/org/repo.git
        version: main
        ttl: "0s"  # Always re-pull

# Global default (atmos.yaml)
components:
  terraform:
    source:
      ttl: "1h"  # Re-pull if older than 1 hour

Changes

• ✅ Add TTL field to VendorComponentSource schema
• ✅ Add TerraformSourceSettings struct with global TTL default
• ✅ Parse ttl from source maps in extract.go
• ✅ Implement TTL expiration check in needsProvisioning()
• ✅ Support per-component override and global defaults
• ✅ Handle zero TTL explicitly (always expires)
• ✅ Comprehensive unit tests for all TTL behaviors

Documentation

• ✅ Updated terraform, helmfile, and packer source command docs with ttl field
• ✅ Added "Cache TTL for Floating Refs" section to source-based versioning design pattern
• ✅ Created PRD explaining problem, solution, and architecture (docs/prd/source-cache-ttl.md)
• ✅ Created blog post with user-facing guidance (website/blog/2026-03-03-source-cache-ttl.mdx)
• ✅ Updated roadmap with shipped milestone

Test Plan

• Unit tests for TTL behavior: zero TTL, relative TTL with recent/old timestamps, no TTL
• Integration tests for component sourcing with TTL
• Tests for global TTL default merging
• Code compiles: go build ./...
• Tests pass: go test ./pkg/provisioner/source/...
• Linting passes: make lint
• Website builds: cd website && npm run build

Related

Fixes #2135

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added source cache TTL for JIT‑vendored components. Configure per‑component or via a global default; "0s" forces re‑pull, other durations (e.g., "1h", "7d") trigger automatic refresh, unset = indefinite cache. Global default merges with per‑component TTL (per‑component wins).

• Documentation

  • New docs, examples, a blog post, and CLI doc updates demonstrating TTL usage for Terraform, Helmfile, and Packer and recommended workflows.

• Tests

  • Added unit tests for TTL parsing, invalid TTL handling, default merging, and TTL-driven provisioning decisions.

Implement vendor targets as both strings and maps with optional version overrides, enabling multiple versions of the same component from a single source entry.

• New AtmosVendorTarget type with custom YAML unmarshaling that accepts both string and map syntax
• Per-target version re-resolution: When a target specifies its own version, the source URL template is re-resolved with that version
• List vendor command support: Updated to show correct paths for per-target version overrides
• JSON Schema update: Changed targets.items from single string type to oneOf supporting both syntaxes
• 14 comprehensive tests: 9 unmarshal tests + 5 processTargets unit tests covering all scenarios
• Blog post and roadmap: Announced feature and updated roadmap milestone

why

Vendor targets syntax was documented but never implemented—a hallucination from commit d549991. Previously, vendoring multiple versions of the same component required duplicating the entire source entry. Per-target overrides allow a single source definition to vendor multiple versions cleanly:

sources:
  - component: vpc
    source: "github.com/cloudposse/terraform-aws-vpc.git///?ref={{.Version}}"
    version: "2.1.0"
    targets:
      - "components/terraform/vpc"
      - path: "components/terraform/vpc/{{.Version}}"
        version: "3.0.0"

This is backward compatible—existing string-based targets continue working identically while new map syntax enables flexible per-target version management.

references

• Documented syntax from: website/docs/design-patterns/version-management/vendoring-components.mdx lines 260-264
• Follows Tasks/Task unmarshaling pattern from pkg/schema/task.go
• All tests passing: schema unmarshal tests, processTargets unit tests, list vendor tests, vendor_utils tests

Summary by CodeRabbit

• New Features

  • Per-target version overrides for vendor configs: targets can be strings or objects with path+optional version; per-target versions re-resolve source URLs, affect package naming, target path templates ({{.Version}}, {{.Component}}), and source locality classification.

• Schema

  • Vendor targets schema now accepts either a string path or an object with path and optional version.

• Documentation

  • Blog post and roadmap entry added with examples.

• Tests

  • Extensive unit tests covering parsing, templating, and per-target resolution.

Add Product Requirements Document for enhancing the aws/user identity with browser-based OAuth2 authentication as a fallback credential source.

• Extends existing aws/user identity (NOT a new provider type)
• Three-tier credential resolution: YAML → Keychain → Browser webflow
• Zero-config authentication using AWS console credentials
• Supports headless/remote mode for servers without browsers
• Native SDK implementation (no AWS CLI dependency)

why

DEV-3829 tracks the implementation of browser-based authentication. This approach:

• Provides seamless fallback when no static credentials configured
• Maintains backward compatibility with existing configurations
• Eliminates need for long-term IAM access keys
• Enables zero-config onboarding for new users

references

• Linear: DEV-3829
• AWS Blog: Simplified developer access

Summary by CodeRabbit

• New Features

  • Browser-based OAuth2 (PKCE) fallback for aws/user enabling interactive and headless remote authentication when no static credentials are present.

• Documentation

  • New product requirements and user-facing docs covering overview, user journeys, credential lifecycle, configuration examples, security, testing, rollout, and success metrics.

• Roadmap

  • Planned milestone added for browser-based OAuth2 auth (Q1 2026).

• Add comprehensive PRD for EKS kubeconfig authentication integration
• Define integration pattern following ECR PR #1859
• Document configuration schema, AWS SDK usage, and CLI command design
• Enhance existing atmos aws eks update-kubeconfig command (not create new atmos auth command)

why

• Establishes design before implementation to ensure alignment with ECR integration pattern
• Provides reference for implementation of dependent components (EKS integration, kubeconfig manager)
• Uses existing atmos aws command namespace to avoid leaking AWS-specific commands into atmos auth
• Enables parallel development once ECR PR #1859 is merged

references

• Relates to: DEV-3815
• Depends on: ECR Authentication PR #1859

Summary by CodeRabbit

• Documentation
  • Added a comprehensive PRD for EKS kubeconfig integration with Atmos authentication, covering architecture and configuration schemas, CLI kubeconfig workflows (integration and explicit cluster modes), multi-cluster support and merge behavior, XDG-compliant kubeconfig storage, AWS integration approach, generated kubeconfig output and environment handling, testing strategy, security considerations, deployment/metrics, and proposed future enhancements.

• Fix .claude-plugin/marketplace.json schema that caused /plugin marketplace add cloudposse to fail with Invalid schema: plugins.0.source: Invalid input
• Change source from "." to "./agent-skills" — the source field must point to the directory containing .claude-plugin/plugin.json
• Remove non-standard metadata.pluginRoot field — not part of the Claude Code marketplace schema
• Move version/description to top-level marketplace fields where they belong
• Remove duplicate plugin-level fields (author, homepage, repository, license, keywords, strict) from the marketplace manifest — these already exist in agent-skills/.claude-plugin/plugin.json
• Change category from "integration" to "development" — matches the official Anthropic marketplace which uses development, productivity, learning, and security
• Add uninstall/marketplace remove commands to all documentation (PRD, blog, agent-skills doc, ai-assistants doc)
• Fix PRD plugin.json example to match the actual agent-skills/.claude-plugin/plugin.json file
• Fix PRD Team Auto-Discovery section to include extraKnownMarketplaces (was missing, wouldn't work without it)

why

• The original marketplace.json used "source": "." with a custom metadata.pluginRoot field to resolve the path. This is not part of the Claude Code marketplace schema — Claude Code expects source to directly point to the plugin directory containing .claude-plugin/plugin.json
• Users running /plugin marketplace add cloudposse/atmos got an opaque validation error with no guidance on what was wrong
• Documentation was missing uninstall/remove instructions, and the PRD had stale examples that didn't match the actual manifest files
• Verified fix works locally:

  /plugin marketplace add cloudposse/atmos   → Successfully added marketplace: cloudposse
  /plugin install atmos@cloudposse           → ✓ Installed atmos
  /plugin uninstall atmos@cloudposse         → ✓ Uninstalled atmos
  /plugin marketplace remove cloudposse      → ✔ Removed 1 marketplace
  

references

• Claude Code Plugin Marketplaces documentation
• Anthropic's official marketplace.json — reference for valid category values and schema structure
• Official Claude Code plugins directory
• PR #2121 that introduced the original marketplace.json

Summary by CodeRabbit

• Documentation

  • Added uninstall instructions for the Atmos plugin across multiple documentation pages.

• Chores

  • Updated plugin configuration and restructured marketplace metadata.
  • Added support for additional marketplace sources to streamline plugin discovery and auto-configuration.

Updated PR size tier thresholds to better reflect modern AI-assisted development:

• Medium: 500 → 1,000 lines
• Large: 1,000 → 5,000 lines
• Extra Large: new tier (5,001–10,000 lines)
• Extra Extra Large: new tier (>10,000 lines, triggers warning)

why

Previously, any PR >1,000 lines triggered a Mergify warning. With Claude-assisted development, PRs naturally grow while remaining focused on single, logical changes. The new thresholds reflect this reality: PRs under a few thousand lines are ideal, only those exceeding 10,000 are flagged as too large and should be split into smaller PRs.

changes

• Added xl_max_size and xxl_label inputs to PR size action
• Updated workflow to use new threshold values (1,000/5,000/10,000)
• Migrated Mergify warning from size/xl to size/xxl (>10,000 lines)
• Documented guidelines in CLAUDE.md for Claude agents

Summary by CodeRabbit

• New Features

  • Added XXL size label category for pull requests exceeding 10,000 lines of changes.
  • Introduced optional CI/CD failure when XXL-sized PRs are detected.

• Chores

  • Updated Medium and Large PR size thresholds (Medium: 500→1,000 lines; Large: 1,000→5,000 lines).
  • Adjusted automated review warning message to reflect higher recommended PR size limit.

Added comprehensive Azure authentication documentation to the authentication configuration reference pages:

• Added three new provider sections: Azure Device Code, Azure OIDC (Workload Identity Federation), and Azure CLI
• Each section includes parameter reference, YAML examples, and usage guidance
• Added GitHub Actions workflow example for Azure OIDC CI/CD authentication
• Updated multi-provider example to include Azure alongside AWS and GCP
• Added cross-links to the Azure Authentication tutorial from all auth documentation pages

why

Azure authentication is fully implemented in the codebase with a comprehensive 530-line tutorial, but it was completely missing from the configuration reference pages (providers.mdx, index.mdx, stacks/auth.mdx). Customers navigating CLI Configuration > Auth > Providers would see AWS and GCP but zero Azure entries, making it appear undocumented. This fix surfaces the existing Azure implementation in the reference docs alongside other cloud providers.

references

• Existing Azure authentication tutorial at /tutorials/azure-authentication (530 lines, comprehensive)
• Changelog entry: https://atmos.tools/changelog/azure-authentication-support
• Azure auth implementation in pkg/auth/providers/azure/ and pkg/auth/cloud/azure/

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Multi-cloud docs and design patterns added (Multi-Cloud Configuration, Application SDLC Environments).
  • Landing hero now highlights AWS, Azure, and GCP with icons and a /multi-cloud link.
  • Resizable docs sidebar with persisted drag-to-resize behavior.

• Documentation

  • Extensive Azure auth guides (device-code, OIDC/workload identity, CLI) and Azure tutorials added.
  • Expanded GCP auth content; providers/identities reorganized into per-provider tabs and updated cloud-console wording.

• Style

  • Cloud logos, TOC and sidebar styling improvements.

• Propagate Atmos authentication (SSO credentials) to all YAML functions and Go templates when running multi-component execution (--all, --everything)
• Fix custom-gcl lint binary to build with Go 1.26 toolchain

Auth propagation fix

• Create AuthManager in ExecuteTerraformQuery before calling ExecuteDescribeStacks (was passing nil)
• Propagate both AuthContext and AuthManager on configAndStacksInfo in describe_stacks.go for all 4 component types (terraform, helmfile, packer, ansible)
• Inject authbridge.Resolver into identity-aware stores for !store/!store.get auth support

Lint toolchain fix

• Bump .custom-gcl.yml from v2.5.0 to v2.10.1 (Go 1.26 support added in v2.9.0)
• Add GOTOOLCHAIN override in Makefile so custom-gcl is always built with the project's Go version

why

• When running atmos terraform plan --all -s <stack>, YAML functions like !terraform.state, !terraform.output, !aws.*, !store, and Go template atmos.Component() failed to use Atmos-managed authentication (e.g., AWS SSO). Single-component execution worked correctly because ExecuteTerraform creates an AuthManager, but the multi-component path (ExecuteTerraformQuery) did not.
• The custom-gcl binary was built with Go 1.25 after the project switched to Go 1.26 in go.mod, causing the golangci-lint pre-commit hook to fail with "Go language version used to build golangci-lint is lower than targeted"

Affected YAML functions

references

• closes #2081

Summary by CodeRabbit

• Bug Fixes

  • YAML and template functions (including !terraform.state and !terraform.output) now use authentication correctly during multi-component runs (e.g., --all).

• Chores

  • Bumped release version to v2.10.1.
  • Removed a custom linter from the build config.
  • Build now invokes an explicit Go toolchain for the linter step.

• Tests

  • Added extensive unit tests covering auth creation and propagation for YAML/template functions.

• Fixed source provisioner (JIT vendoring) to use atmos_component (instance name) for workdir paths, matching the fix from PR #2093
• When metadata.component differs from the component instance name (e.g., instance demo-cluster-codepipeline-iac inheriting from base demo-cluster-codepipeline), both source pull and terraform plan/init now create the same workdir directory
• Updated determineSourceTargetDirectory() and buildWorkdirPath() to check for atmos_component before falling back to the passed component name
• Added comprehensive tests covering the atmos_component workdir isolation case

why

This is a follow-up to PR #2093 which fixed workdir collision for parallel component instances. However, that PR only updated the workdir provisioner. When both source and workdir are enabled, the workdir provisioner defers to the source provisioner (AutoProvisionSource), which was still using extractComponentName() that returns the base component name. This caused JIT vendoring to write source code to a different workdir path than terraform plan/init expects, breaking the fix.

references

Closes #2134
Follows PR #2093 (fix for issue #2091)

Summary by CodeRabbit

• Refactor

  • Consolidated workdir path construction logic into a centralized utility for improved consistency.
  • Workdir paths now properly utilize component instance names when specified.

• Tests

  • Added comprehensive test coverage for workdir path resolution and instance name handling.

Changes

• pkg/auth/manager.go: Modified isInteractive() to check viper.GetBool("interactive") before TTY/CI checks
• pkg/auth/interactive_test.go: Added test coverage for flag behavior

Implementation

func isInteractive() bool {
    // Check if interactive mode is enabled via flag or environment.
    if !viper.GetBool("interactive") {
        return false
    }
    
    // Check if stdin is a TTY and not in CI.
    return term.IsTTYSupportForStdin() && !telemetry.IsCI()
}

Now aligns with the existing pattern in pkg/flags/interactive.go.

Behavior

• Fixes #2125

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.