cloudposse/atmos v1.203.0-rc.1

on GitHub

Create new packages for modularized function handling and YAML utilities:

• pkg/function/: Format-agnostic function registry and handlers (env, exec, random, include, template, store, terraform, aws, repo-root)
• pkg/yaml/: YAML-specific utilities (position tracking, error handling, types)
• pkg/aws/identity/: Consolidated AWS identity caching (from internal/aws_utils)

Why

• Separation of Concerns: Function handlers work across all formats (YAML, HCL, JSON); only parsing differs
• Code Reuse: Registry pattern eliminates duplication across formats
• Extensibility: New functions without modifying core logic
• Testing: Interface-driven design with dependency injection
• AWS Consolidation: Eliminate duplicate identity caching logic

References

Foundation for PR #1842 which refactors YAML processing.
Consolidates AWS identity handling per request.

Summary by CodeRabbit

• New Features

  • New AWS functions: aws.account_id, aws.caller_identity_arn, aws.caller_identity_user_id, aws.region.
  • Format-agnostic function registry added with built-in handlers: env, exec, store, store.get, template, terraform.output, terraform.state, random, literal, include, repo-root.
  • Store interface now supports direct key retrieval (GetKey).

• Refactor

  • Centralized AWS identity handling with per-context caching and Atmos auth support.
  • YAML utilities improved with position tracking and clearer error signals.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Add aws/assume-root identity kind for centralized root access to AWS member accounts
• Implement STS AssumeRoot API integration with AWS-managed task policies
• Add shared STS client helper for assume-role and assume-root identities
• Include comprehensive test coverage (1000+ lines)

why

• Enables secure, centralized management of root access across AWS Organizations
• Provides audit trail for root operations through AWS-managed task policies
• Reduces risk of credentials scattered across multiple accounts
• Follows AWS best practices for delegated root access via IAM Identity Center

references

• AWS Centralized Root Access Documentation
• PRD: docs/prd/aws-assume-root-identity.md

Validated locally. Here's an example

auth:
  providers:
   sso:
      kind: aws/iam-identity-center
      region: us-east-2
      start_url: https://acme.awsapps.com/start
      auto_provision_identities: true

  identities:
    # ==========================================================================
    # Centralized Root Access
    # ==========================================================================
    # AWS Centralized Root Access allows management account administrators to
    # assume root in member accounts using short-lived STS credentials.
    # See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-enable-root-access.html
    #
    # Prerequisites:
    #   1. Centralized root access enabled in AWS Organizations
    #   2. Permission set with sts:AssumeRoot in management account
    #
    # Supported task policies (limit root operations to specific tasks):
    #   - IAMAuditRootUserCredentials  - Audit root MFA and access keys
    #   - IAMCreateRootUserPassword    - Create/reset root password
    #   - IAMDeleteRootUserCredentials - Remove root access keys and MFA
    #   - S3UnlockBucketPolicy         - Unlock S3 buckets with restrictive policies
    #   - SQSUnlockQueuePolicy         - Unlock SQS queues with restrictive policies
    # ==========================================================================

    # Step 1: Authenticate to permission set with sts:AssumeRoot in management account
    organizational-root-access:
      kind: aws/permission-set
      via:
        provider: sso
      principal:
        name: RootAccess
        account:
          name: Root

    # Step 2: Chain to assume root in target member account
    #
    # Usage:
    #   atmos auth login --identity core-audit/iam-audit-root
    #   atmos auth exec --identity core-audit/iam-audit-root -- aws iam list-mfa-devices
    #
    core-audit/iam-audit-root:
      kind: aws/assume-root
      via:
        identity: organizational-root-access
      principal:
        target_principal: "1234567890"  # core-audit
        task_policy_arn: arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials

atmos auth exec --identity core-audit/iam-audit-root -- aws sts get-caller-identity
{
    "UserId": "1234567890",
    "Account": "1234567890",
    "Arn": "arn:aws:iam::1234567890:root"
}

Summary by CodeRabbit

• New Features

  • Added AWS "assume-root" identity for task-scoped, short-lived root access via AWS STS.

• Documentation

  • New PRD and blog post with examples, supported policies, prerequisites, and getting-started guidance.
  • Added blog author metadata for the new guide.

• Tests

  • Extensive tests covering identity flows, STS client behavior, environment setup, credential handling, and lifecycle operations.

• Chores

  • Provider registration and STS client support enhancements.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Implement new atmos list affected command to compare affected components between branches
• Fix false positive affected components when using the -C flag by correctly computing relative paths from git root
• Generalize spinner implementation from internal/exec to pkg/ui/spinner for better reusability across the codebase
• Add FormatSuccess/FormatError functions to properly render markdown in toast messages, fixing backtick formatting

why

The original describe affected implementation had a bug where components appeared affected with reason stack.metadata even when there were zero differences between branches when using the -C flag. This was caused by incorrect path calculation and cache contamination. The new list affected command provides a cleaner interface while fixing these issues. Additionally, the spinner implementation was duplicated across multiple files with formatting issues, so we centralized it in pkg/ui/spinner for better maintainability and proper markdown rendering support.

references

• Fixes false positive issue in describe affected when using -C flag
• Consolidates duplicate spinner implementations
• Improves CLI output formatting and markdown rendering

Summary by CodeRabbit

• New Features

  • Added the new atmos list affected command with filtering, sorting, custom columns and multiple output formats.
  • Enhanced CLI spinner UI with dynamic completion messages and improved success/error formatting.

• Bug Fixes

  • Fixed false positives when listing affected components in subdirectories by improving path handling and cache isolation.
  • Clearer error when a Git reference is not found.

• Documentation

  • New docs and blog post describing the list affected command and usage.

• Tests

  • Expanded test coverage and updated snapshots.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Modified the blog-release-data Docusaurus plugin to compute release versions dynamically at build time using git
• Blog posts without explicit release frontmatter now automatically resolve to their release version
• Respects manual frontmatter overrides (highest precedence)

why

The changelog was displaying recently released features as "Unreleased" because the plugin only read from blog post frontmatter. By detecting releases during the build process, we eliminate timing issues and ensure the website always shows accurate release information.

references

• Fixes changelog showing released changes (v1.201.0, v1.202.0) as "Unreleased"

Summary by CodeRabbit

• New Features

  • Blog posts gain automatic release detection (frontmatter override → VCS-derived stable tag → "unreleased" fallback).
  • Release associations are populated in a global release map and exposed to UI components for consistent version-aware grouping and filtering.
  • Changelog/timeline grouping now uses the global release map for more accurate release-based organization.

• Chores

  • No public plugin API changes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Problem-first intro: "When your infrastructure depends on external modules..." instead of feature-focused messaging
• Concrete benefits: git diff visibility, audit trails, emergency patching (instead of abstract "standardizes" language)
• New "Why Vendor?" section explaining explicit vs implicit vendoring philosophy
• Use cases rewritten with concrete scenarios (compliance reviews, security patches, deployment reliability) instead of enterprise jargon
• Link to design-patterns page for full philosophy and details

why

User feedback indicated the vendoring docs don't effectively "sell" the value before diving into technical details. Readers looking for information about vendoring use cases couldn't find compelling reasons to adopt the pattern without watching videos or reading external resources. The design-patterns page does this better, so we aligned the main docs with that approach.

references

Addressing user feedback: "I have been reading about Atmos vendoring and wanted to check if there are any video demos that go over the use cases etc"

Summary by CodeRabbit

• Documentation
  • Reorganized vendoring documentation with enhanced rationale and concrete benefits
  • Added practical guidance for version management patterns and best practices
  • Improved navigation through restructured content and cross-references to related resources

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Fixed ATMOS_IDENTITY=false and --identity=false not being recognized as a way to disable authentication
• Added normalizeIdentityValue() helper to convert "false", "0", "no", "off" to internal disabled sentinel
• Added IsDisabled() method to IdentitySelector for checking if authentication is disabled
• Added comprehensive tests for identity flag normalization

why

When ATMOS_IDENTITY=false is set via environment variable or --identity=false is passed as a flag, the value "false" was being treated as a literal identity name instead of being normalized to the internal __DISABLED__ sentinel value. This caused auth validation to fail with "Identity specified was not found in the auth config." Users now have a clear way to disable authentication.

references

Closes #1898

Summary by CodeRabbit

• New Features

  • Enhanced identity flag handling to recognize various representations of disabled state (false, 0, no, off in any case variation).
  • Added capability to check if authentication has been explicitly disabled.

• Tests

  • Added comprehensive test coverage for identity flag normalization and disabled state detection across multiple scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Restored several terraform CLI flags that were broken after the command registry migration in v1.202.0
• Added missing flags to the terraform flag registry in cmd/terraform/flags.go
• Registered command-specific flags only on the commands that use them (matching pre-migration behavior)
• Fixed flag value parsing: flags are now properly read from Viper and applied to ConfigAndStacksInfo
• Added comprehensive test coverage for flag parsing and application

Fixed Flags

Flag Availability by Command

The --skip-init flag is available on all terraform commands.

The following flags are registered only on the commands that use them:

why

During the terraform command registry migration in v1.202.0, these flags had two issues:

1. Flag registration: Flags were registered in the old parsing code but not in the new flag registry, causing "unknown flag" errors
2. Flag value propagation: Even when flags were recognized, their values weren't being properly applied to the execution context, causing them to be silently ignored

This broke CI/CD pipelines that relied on these flags for controlling Atmos behavior.

Technical Changes

• cmd/terraform/flags.go: Added BackendExecutionFlags() for command-specific flags
• cmd/terraform/options.go: Added fields to TerraformRunOptions and parsing in ParseTerraformRunOptions()
• cmd/terraform/utils.go: Updated applyOptionsToInfo() to transfer flag values to ConfigAndStacksInfo
• cmd/terraform/options_test.go: Added comprehensive tests for flag parsing and application

references

• Fixes regression introduced in version 1.202.0 (PR #1813)

Summary by CodeRabbit

• New Features

  • Restored/added Terraform CLI flags: auto-generate-backend-file, init-run-reconfigure, planfile, skip-planfile, skip-init, init-pass-vars, deploy-run-init across init/plan/apply/deploy/workspace.

• Documentation

  • Published blog post documenting restored Terraform CLI flags and usage.

• Tests

  • Added extensive unit/integration and CLI tests (including skip-init behavior and flag recognition across commands).

• Chores

  • Updated help output snapshots, test fixtures, and bumped dependency versions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Added structured plain text error formatting to display ErrorBuilder enrichments (hints, explanations, context) even when the markdown renderer is not initialized
• Fixes profile not found errors during config loading to show which profile is missing and how to configure it

why

• Early startup errors (before config is loaded) were falling back to bare plain text output that only showed the sentinel error message
• Rich error information from ErrorBuilder (hints, explanations, context) was being lost because the markdown renderer wasn't initialized yet
• This made errors like "Error: profile not found" unhelpful as they didn't tell users which profile was missing or how to fix it

references

• Improves user experience for all early startup errors that use the ErrorBuilder pattern
• Particularly beneficial for profile configuration errors showing profile name, search paths, and actionable hints

Summary by CodeRabbit

• Bug Fixes
  • Improved error output when rich rendering is unavailable: displays structured sections for explanations, hints, and contextual key/value details while preserving legacy plain output and a helpful default title.
• Tests
  • Added tests validating enriched error formatting, plain-error fallback, and default title behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}