Skip to main content

Atmos Profiles: One Configuration, Multiple Contexts

· 6 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

Stop fighting with different Atmos configurations for development, CI/CD, and production. Profiles let you switch contexts with a single flag while keeping your core configuration consistent.

The Problem​

Here's a scenario you've probably faced: You want Atmos to behave one way in CI, another way for developers, and yet another way for platform engineers. You need:

  • Different default identities - Platform engineers use admin permissions, developers use sandbox access
  • Different error reporting - Sentry enabled in CI for verbose error tracking, but disabled in production to avoid noise
  • Different terminal settings - CI needs plain text output with no color, developers want rich formatting
  • Different authentication - Interactive AWS SSO for developers, GitHub OIDC for automation

Sure, you could handle this with environment variables scattered across GitHub Actions, .bashrc, and CI configs:

# Every single time in CI - export all these env vars
export ATMOS_IDENTITY=github-oidc
export ATMOS_LOGS_LEVEL=info
export NO_COLOR=1
# Plus Sentry config, terminal settings, etc.
atmos terraform apply vpc -s prod

# Every single time as a developer - different env vars
export ATMOS_IDENTITY=developer-sandbox
export ATMOS_LOGS_LEVEL=debug
# Plus terminal width, color settings, etc.
atmos terraform plan vpc -s dev

Either way, you're juggling a complex combination of overrides that aren't version-controlled or easily shared.

How do you codify these contexts so they're consistent, version-controlled, and easy to switch between?

The Solution: Atmos Profiles​

Profiles let you codify what it means to have a certain context and change all the settings of Atmos to match that context. No flags to remember. No environment variables to export. Just set it once and forget it.

# Developer: One flag replaces 5+ configuration settings
atmos terraform plan vpc -s dev --profile developer

# CI: Set once in your workflow
export ATMOS_PROFILE=ci
atmos terraform apply vpc -s prod

# Platform Engineer: One flag, consistent settings
atmos terraform plan vpc -s prod --profile platform-admin

Same command, same component, same stack—but the profile handles your identity, logging, terminal settings, error reporting, and everything else. It's all version-controlled configuration, not scattered flags and environment variables.

How It Works​

Profiles are simply directories containing YAML configuration files that override your base atmos.yaml settings. Atmos discovers profiles from multiple locations with clear precedence rules:

  1. Configurable location (set in profiles.base_path)
  2. Project-hidden (.atmos/profiles/)
  3. User directory (~/.config/atmos/profiles/)
  4. Project directory (profiles/)

Example: Developer Profile​

Create a profile for local development with a sandbox identity:

# profiles/developer/auth.yaml
auth:
  defaults:
    identity: developer-sandbox  # Set default identity for this profile
  identities:
    developer-sandbox:
      kind: aws/permission-set
      via:
        provider: aws-sso
      principal:
        account_id: "123456789012"
        permission_set: DeveloperAccess
# profiles/developer/settings.yaml
logs:
  level: Debug

settings:
  terminal:
    max_width: 120

Activate it with:

atmos terraform plan vpc -s dev --profile developer

Or set it as your default:

export ATMOS_PROFILE=developer
atmos terraform plan vpc -s dev

Example: CI Profile​

Create a profile for GitHub Actions with OIDC authentication, Sentry error tracking, and CI-friendly output:

# profiles/ci/auth.yaml
auth:
  defaults:
    identity: github-oidc  # Set default identity for CI
  identities:
    github-oidc:
      kind: aws/role
      via:
        provider: aws-oidc
        audience: sts.amazonaws.com
      principal:
        role_arn: arn:aws:iam::123456789012:role/GitHubActionsRole
# profiles/ci/settings.yaml
logs:
  level: Info

errors:
  sentry:
    enabled: true  # Enable Sentry in CI for error tracking
    environment: ci

settings:
  terminal:
    color: false  # Plain text for CI logs
    max_width: 80
    markdown:
      code:
        style: ascii

Set once in your workflow:

# .github/workflows/deploy.yml
env:
  ATMOS_PROFILE: ci  # Set it once, forget it

jobs:
  deploy:
    steps:
      - run: atmos terraform apply vpc -s prod
      # No flags needed - profile handles everything

Combining Profiles​

Need to layer multiple contexts? Stack profiles from left to right, with rightmost values winning:

# Base security settings + developer overrides
atmos terraform plan vpc -s dev --profile security-baseline --profile developer

This is powerful for composing shared policies with role-specific settings.

Managing Profiles​

List available profiles:

atmos profile list

View profile details:

atmos profile show developer

The output shows you exactly what settings the profile provides, where it's located, and how to use it.

See it in action — listing available profiles and inspecting one in detail:

atmos config profiles
00:00.0 / 00:00.0

View the full example

Why This Matters​

Before profiles, you had environment variables and config scattered everywhere:

  • .bashrc for developers with ATMOS_IDENTITY, ATMOS_LOGS_LEVEL, etc.
  • GitHub Actions secrets for CI with different values
  • GitLab CI variables for other pipelines
  • Different dotfiles for different team members
  • atmos.yaml overrides that vary by machine
  • No version control, no consistency

This approach meant:

  • ❌ Settings aren't codified - Tribal knowledge about which flags to use
  • ❌ Easy to get wrong - Forget one flag, wrong behavior
  • ❌ Can't share configurations - Everyone maintains their own setup
  • ❌ Onboarding is painful - New team members reinvent the wheel
  • ❌ Drift over time - CI uses different settings than developers

With profiles, you:

  • ✅ Codify each context once - Developer, CI, platform engineer profiles all version-controlled
  • ✅ Set it and forget it - export ATMOS_PROFILE=ci or --profile developer, done
  • ✅ No flag juggling - One profile replaces dozens of configuration overrides
  • ✅ Version-controlled consistency - Commit profiles, share with the team
  • ✅ Compose when needed - Layer profiles for complex scenarios (security baseline + role overrides)
  • ✅ Onboard instantly - New team members use proven profiles, no setup required

Real-World Example​

Here's what a complete profile setup looks like for a team:

profiles/
├── developer/          # Local development
│   ├── auth.yaml      # Sandbox identity via AWS SSO
│   └── settings.yaml  # Debug logs, wide terminal
├── ci/                # GitHub Actions
│   ├── auth.yaml      # OIDC identity for automation
│   └── settings.yaml  # Plain output, no color
├── platform-admin/    # Platform engineers
│   ├── auth.yaml      # Admin identity via AWS SSO
│   └── settings.yaml  # Warning-level logs only
└── audit/             # Security reviews
    ├── auth.yaml      # Read-only identity
    └── settings.yaml  # Full audit logging

Each team member activates the profile that matches their role:

  • Developers use the developer profile → get sandbox identity with debug logging
  • CI workflows use the ci profile → get OIDC identity with plain text output
  • Platform engineers use the platform-admin profile → get admin identity with minimal logs
  • Security audits use the audit profile → get read-only identity with comprehensive logging

No duplicated configuration. No environment variable sprawl. No confusion about which identity to use. Just clear, version-controlled contexts that do exactly what they say.

Learn More​

  • Example Configuration: See the complete working example in examples/config-profiles/ with developer, CI, and production profiles
  • Profile Commands: Use atmos profile list and atmos profile show <name> to discover and inspect profiles
  • PRD Documentation: See docs/prd/atmos-profiles.md for complete technical specification

Get Involved​