Skip to main content

!aws.organization_id

The !aws.organization_id YAML function retrieves the AWS Organization ID by calling the AWS Organizations DescribeOrganization API.

Usage​

The !aws.organization_id function takes no parameters:

  # Get the AWS Organization ID
  org_id: !aws.organization_id

Arguments​

This function takes no arguments. It uses the AWS credentials from the environment or the Atmos authentication context if configured.

How It Works​

When processing the !aws.organization_id YAML function, Atmos:

  1. Loads AWS Configuration - Uses the standard AWS SDK credential resolution chain:

    • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
    • Shared credentials file (~/.aws/credentials)
    • Shared config file (~/.aws/config)
    • EC2 Instance Metadata Service (IMDS)
    • ECS Task credentials
    • Web Identity Token credentials

  2. Calls Organizations DescribeOrganization - Makes an API call to retrieve the organization details

  3. Returns Organization ID - Extracts and returns the organization ID (e.g., o-abc123def4) as a string

Authentication​

Atmos Auth Integration​

When using Atmos Authentication, the function automatically uses credentials from the active identity. This enables seamless integration with SSO, assume role chains, and other authentication methods configured in your atmos.yaml.

The credential resolution order is:

  1. Atmos Auth Context (highest priority) - If an identity is active (via --identity flag or default identity in settings.auth), Atmos uses the Atmos-managed credential files and profile instead of the standard AWS credential chain
  2. Standard AWS SDK resolution (fallback) - If no Atmos auth context is available, falls back to the standard chain (environment variables, ~/.aws/credentials, IMDS, etc.)

When Atmos Auth is active, the function receives an AWSAuthContext containing:

  • Profile - The identity name (e.g., core-auto/terraform)
  • CredentialsFile - Path to Atmos-managed credentials (e.g., ~/.atmos/auth/{realm}/aws/{provider}/credentials)
  • ConfigFile - Path to Atmos-managed config (e.g., ~/.atmos/auth/{realm}/aws/{provider}/config)
  • Region - AWS region from the identity or component override

This context is passed to LoadConfigWithAuth(), which configures the AWS SDK to use the Atmos-managed files instead of the default ~/.aws/ paths.

Stack-Level Auth Configuration​

Auth can be configured at three levels, with component-level taking highest precedence:

atmos.yaml
# Global auth configuration
auth:
  identities:
    core-auto/terraform:
      kind: aws/permission-set
      default: true
      via:
        provider: aws-sso
stack.yaml
components:
  terraform:
    my-component:
      # Component-level auth override (highest precedence)
      settings:
        auth:
          identities:
            prod-deploy:
              default: true
              kind: aws/assume-role
      vars:
        # Uses credentials from prod-deploy identity
        organization_id: !aws.organization_id

Using with the --identity Flag​

# Explicitly specify the identity for the command
atmos terraform plan my-component -s prod-ue1 --identity core-auto/terraform

# The !aws.organization_id function will use the core-auto/terraform credentials

Caching​

The !aws.organization_id function uses its own cache, separate from the identity functions (!aws.account_id, !aws.caller_identity_arn, etc.). Results are cached in memory for the duration of the CLI invocation:

  • Multiple uses of !aws.organization_id in the same command only make one Organizations API call
  • Different authentication contexts (e.g., different profiles or credential files) get separate cache entries
  • The cache key is derived from Profile:CredentialsFile:ConfigFile, so different identities never share cached results
  • Each new CLI command starts with a fresh cache
Type-Aware Merging

Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts. See the full explanation: YAML Function Merging

Examples​

Basic Usage​

stack.yaml
components:
  terraform:
    my-component:
      vars:
        # Inject the AWS Organization ID into Terraform variables
        organization_id: !aws.organization_id

Resource Tags​

stack.yaml
components:
  terraform:
    vpc:
      vars:
        tags:
          OrganizationId: !aws.organization_id
          AccountId: !aws.account_id
          ManagedBy: "atmos"

SCP and Policy Scoping​

stack.yaml
components:
  terraform:
    scp-policies:
      vars:
        organization_id: !aws.organization_id
        account_id: !aws.account_id

Cross-Account References​

stack.yaml
components:
  terraform:
    cross-account-role:
      vars:
        organization_id: !aws.organization_id
        trusted_org_id: !aws.organization_id

Comparison with Terragrunt​

This function is equivalent to Terragrunt's get_aws_org_id() function:

TerragruntAtmos
get_aws_org_id()!aws.organization_id

Error Handling​

If the function fails to retrieve the AWS organization info, Atmos will log an error and exit.

Common error scenarios:

  • No AWS credentials configured - Standard credential resolution fails
  • Account not in an organization - The AWS account is not a member of an AWS Organization
  • Missing permissions - The caller does not have the organizations:DescribeOrganization permission
  • Network connectivity issues - Cannot reach the AWS Organizations endpoint

Considerations​

  • Requires organizations:DescribeOrganization permission - This is a specific IAM permission that may not be available by default, unlike sts:GetCallerIdentity
  • Requires organization membership - The AWS account must be a member of an AWS Organization. Standalone accounts will receive an error
  • Network dependency - Requires connectivity to the AWS Organizations endpoint
  • Performance - Results are cached per CLI invocation, so there's minimal overhead when used multiple times
  • Separate cache - Uses a separate cache from the identity-based functions (!aws.account_id, !aws.region, etc.) since it calls a different AWS API

Related Functions​