cloudposse/atmos v1.200.0

on GitHub

What

This PR adds comprehensive documentation for Terraform planfiles and complete reference documentation for all Terraform commands in Atmos.

Planfile Documentation

• New comprehensive guide: website/docs/core-concepts/terraform/planfiles.mdx
• Covers what planfiles are, how they work, benefits, and best practices
• Documents Terraform backend limitations and security considerations
• Includes workflow examples and integration patterns

Terraform Command Documentation

Complete reference documentation for all Terraform commands:

• terraform apply, terraform plan, terraform destroy
• terraform init, terraform get, terraform validate
• terraform state, terraform import, terraform taint/untaint
• terraform output, terraform show, terraform version
• terraform providers, terraform modules, terraform workspace
• And many more...

Each command page includes:

• Purpose and use cases
• Atmos-specific behavior and enhancements
• Usage examples
• Arguments and flags
• Screengrabs showing actual CLI output

Color Output Improvements

• Fixed NO_COLOR environment variable detection
• Proper terminal capability detection and degradation
• Fixed ANSI code leakage in validation messages
• Improved UI output with proper line clearing

Why

• Users needed comprehensive documentation for Terraform planfile workflows
• Command reference was incomplete or missing for many Terraform commands
• Documentation had inconsistencies and broken links
• Color output wasn't properly respecting NO_COLOR specification

Testing

• ✅ All documentation builds successfully
• ✅ All links verified
• ✅ Screengrabs generated for all commands
• ✅ Golden snapshots regenerated and passing
• ✅ NO_COLOR tests passing

References

• Addresses documentation gaps in Terraform command coverage
• Improves planfile workflow documentation

Summary by CodeRabbit

• New Features

  • Comprehensive user docs added for Terraform commands (apply, plan, destroy, init, etc.) and many auth subcommands (console, env, exec, list, login, logout, shell, user, validate, whoami).
  • New CLI flags: --force-color, --force-tty, --mask, --redirect-stderr; ATMOS_FORCE_COLOR env support.

• Improvements

  • Theme-aware, color-capable help output with improved code-block styling and examples.
  • Robust pager detection with graceful fallbacks.

• Documentation

  • Expanded planfile and workflow guidance and numerous help pages for CLI commands.

Summary

Implements automatic provisioning of AWS SSO identities from AWS Identity Center, eliminating the need for manual configuration of every role/account combination. Users enable auto_provision_identities: true on their provider, and Atmos discovers all available identities during login.

What Changed

Implementation

• SSO Provisioning: Auto-discovers identities via AWS Identity Center APIs (ListAccounts, ListAccountRoles)
• Dynamic Config Generation: Writes discovered identities to XDG cache (~/.cache/atmos/aws/{provider}/provisioned-identities.yaml)
• Seamless Integration: Provisioned identities work across all Atmos commands
• Lifecycle Management: Cache generated on login, cleaned on logout
• Manual Override: Hand-configured identities in atmos.yaml take precedence

Documentation

• PRD: Complete design document (docs/prd/sso-role-auto-discovery.md)
• Standards: Tags vs labels classification (docs/prd/tags-and-labels-standard.md)
• CLI Docs: Updated auth command documentation with provisioning examples
• Blog Post: Getting started guide with real-world examples

Testing

• Comprehensive unit tests for provisioning, schema, writer, and logout behavior
• Integration tests covering end-to-end flows
• Test coverage for all new components

Usage

Enable auto-provisioning in atmos.yaml:

auth:
  providers:
    sso-prod:
      kind: aws/iam-identity-center
      start_url: https://my-org.awsapps.com/start
      region: us-east-1
      auto_provision_identities: true

Login once to discover identities:

$ atmos auth login --provider sso-prod
✓ Authenticated with AWS SSO
✓ Provisioned 46 identities

All identities now available:

$ atmos terraform plan prod-vpc --identity production/AdministratorAccess
$ atmos auth list  # Shows all 46 provisioned identities

Key Features

• Zero Configuration: No manual identity mapping required
• Opt-in Design: Backward compatible, disabled by default
• Filtered Discovery: Optional account/role filters to limit scope
• Cache Management: Uses XDG cache directories, cleaned on logout
• Non-blocking: Provisioning failures warn but don't prevent authentication

Related Issues

Addresses the manual configuration burden for organizations with many AWS accounts and permission sets.

Summary by CodeRabbit

• New Features

  • Opt-in AWS SSO identity auto‑provisioning with local cache, injected import of provisioned identities, and a new --provider flag for provider-based login.

• Bug Fixes

  • Provisioned identities cache is removed on provider logout to avoid stale entries.

• Documentation

  • New PRDs, blog post, CLI docs and examples for auto‑provisioning, tags/labels standards, keyring/XDG defaults, and IAM permission guidance.

• UX

  • More actionable, contextual error messages across SSO and identity flows.

• Tests

  • Expanded test coverage for provisioning, caching, import injection, pagination, logout, and merge behaviors.

• Chores

  • Patch dependency updates and example version bumps.

what

• Replace buggy docusaurus-plugin-llms v0.2.2 with lightweight custom plugin
• Remove 58-line bash workaround script
• Use Docusaurus's resolved routes directly for correct URLs

why

• Original plugin reconstructs URLs from filenames with buggy regex
• Only removes first numeric prefix (2025-10-13-slug → 10-13-slug)
• Hardcodes /blog/ path instead of reading routeBasePath config
• Ignores frontmatter slug field
• Required bash workaround to fix URLs after generation

references

• closes #1804
• Original plugin issue: rachfop/docusaurus-plugin-llms#15
• llmstxt.org spec: https://llmstxt.org

what

• Fixed --profile CLI flag not loading profile configuration
• Fixed --identity CLI flag not propagating to nested component operations when using --identity with --profile
• CLI flags now correctly take precedence over environment variables
• Profiles specified via --profile flag load and merge correctly with global configuration
• User's explicit --identity choice propagates to all nested operations (YAML functions like !terraform.state) when using --identity with --profile

why

Issue 1: Profile Loading from CLI Flag

When using the --profile CLI flag, profile configuration was not loaded or merged with global configuration, causing authentication failures even when valid profiles were defined. The ATMOS_PROFILE environment variable worked correctly, but the --profile flag did not.

Root Cause: Viper's BindPFlag() creates a binding between Viper key and Cobra flag, but flag values aren't synchronized into Viper immediately when commands execute. Environment variables work because they're read directly into Viper without synchronization delay.

Solution: Implemented dual approach with correct precedence order:

1. Check CLI flags FIRST (manual os.Args parsing - highest priority)
2. Fall back to environment variables (direct os.Getenv() read - lower priority)

This ensures both ATMOS_PROFILE env var and --profile CLI flag work correctly, with CLI flags taking precedence as expected.

Precedence Order (highest to lowest):

1. CLI flags (--profile)
2. Environment variables (ATMOS_PROFILE)
3. Config file
4. Defaults

Files Modified:

• pkg/config/load.go - Added parseProfilesFromArgs() and getProfilesFromFlagsOrEnv() with correct precedence
• pkg/config/load_profile_test.go (NEW) - Comprehensive test suite with 9 test cases
• pkg/config/load_flags_test.go (NEW) - Tests for precedence and environment variable handling

Issue 2: Identity Flag Not Propagating to Nested Components

After fixing profile loading, a related issue was discovered: when using --profile and --identity flags together, the identity selector still appeared during nested component operations (such as !terraform.state YAML functions).

Root Cause: When YAML template functions need to fetch state from other components, they create component-specific AuthManagers. The original implementation did not inherit the user's explicitly specified identity, always passing empty string which triggered auto-detection. With profiles containing multiple default identities, auto-detection showed the selector prompt.

Solution: Extract the authenticated identity from the parent AuthManager's chain using GetChain() and pass it to nested component AuthManager creation. This ensures the user's --identity choice propagates to all nested operations.

Files Modified:

• internal/exec/terraform_nested_auth_helper.go - Updated createComponentAuthManager() to inherit identity from parent AuthManager
• internal/exec/terraform_nested_auth_helper_test.go - Added comprehensive tests for identity inheritance

Issue 3: Test Isolation (CI Failures)

Initial implementation caused test failures in CI due to Viper caching environment variables.

Root Cause: Viper caches environment variable values on first read. In CI, if ATMOS_PROFILE was set by the environment or previous tests, Viper retained the cached value even after tests cleaned up, causing "profile not found" errors.

Solution: Changed to read ATMOS_PROFILE directly using os.Getenv() instead of Viper. This provides:

• Fresh reads on every call (no caching)
• Proper test isolation (t.Setenv() cleanup works correctly)
• No stale cached values from previous tests

Testing:

All issues were thoroughly tested:

Profile Flag:

• CLI flag syntax: --profile managers ✅
• Environment variable: ATMOS_PROFILE=managers ✅
• Comma-separated profiles: --profile=managers,staging ✅
• CLI flags override environment variables ✅
• Original failing command: atmos terraform plan --profile managers ✅
• All existing tests pass ✅

Identity Flag:

• With --identity flag: No selector, uses specified identity ✅
• Without --identity flag: Shows selector once, nested operations inherit selected identity ✅
• Backward compatibility: Auto-detection still works when no parent exists ✅
• YAML functions use inherited identity ✅

Test Isolation:

• Tests pass in CI (no Viper caching issues) ✅
• Proper cleanup with t.Setenv() ✅
• No "profile not found" errors ✅

Success Criteria:

All success criteria met:

1. ✅ --profile CLI flag loads profile configuration and merges with global config
2. ✅ ATMOS_PROFILE environment variable continues to work
3. ✅ CLI flags take precedence over environment variables (correct behavior)
4. ✅ --identity flag propagates to nested component operations
5. ✅ No identity selector appears when identity is explicitly specified
6. ✅ User's identity choice is consistent throughout entire command execution
7. ✅ Comma-separated profiles work
8. ✅ All existing tests continue to pass (including in CI)
9. ✅ New tests provide comprehensive coverage
10. ✅ Proper test isolation (no cached state issues)

references

• Documentation: docs/fixes/profile-and-identity-flags-loading.md - Complete technical documentation of all issues and fixes
• Related PR: #1786 - Initial work on auth context propagation through nested operations

Summary by CodeRabbit

Release Notes

• New Features

  • Improved CLI flag handling for --profile and --identity flags with better environment variable support
  • Identity settings now properly propagate to nested components
  • Global authentication configuration is now shared with component-specific auth sections

• Bug Fixes

  • Fixed profile loading from environment variables and CLI flags in commands with flag parsing disabled

• Tests

  • Added comprehensive test coverage for profile flag parsing and identity inheritance

• Chores

  • Updated dependencies including AWS SDK v2, gRPC, and OpenTelemetry components