atmos-devcontainer

Atmos Devcontainer

Purpose

Atmos provides native devcontainer management for creating standardized, reproducible development environments. It provides built-in orchestration that integrates with Atmos authentication, toolchains, and project configuration, replacing the need for external orchestration tooling like Geodesic (though Geodesic container images remain fully supported).

Note: The devcontainer feature is currently experimental. By default (settings.experimental: warn), Atmos displays a warning but runs the command. Set settings.experimental: silence in atmos.yaml to suppress the warning, or disable to block experimental commands entirely.

Core Concepts

Devcontainer Configuration

Devcontainers are configured at the top level of atmos.yaml (not under components:). Each named devcontainer defines container settings and a devcontainer spec:

devcontainer:
  default:
    settings:
      runtime: docker           # docker or podman (auto-detected if omitted)
    spec:
      name: "Atmos Default"
      image: "cloudposse/geodesic:latest"
      workspaceFolder: "/workspace"
      workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"
      mounts:
        - "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly"
      forwardPorts:
        - 8080
      containerEnv:
        ATMOS_BASE_PATH: "/workspace"
      remoteUser: "root"

Supported Spec Features

The following devcontainer spec fields are supported:

Unsupported fields (features, postCreateCommand, customizations, etc.) are silently ignored with debug-level logging, allowing compatibility with VS Code devcontainer.json files. Use ATMOS_LOGS_LEVEL=Debug to see which fields are being ignored.

Importing from devcontainer.json

Use !include to import existing VS Code devcontainer configurations:

devcontainer:
  vscode:
    settings:
      runtime: docker
    spec: !include .devcontainer/devcontainer.json

Container Naming

Containers follow the naming convention: atmos-devcontainer.{name}.{instance}

• Dot (.) separator avoids parsing ambiguity with hyphenated names
• Default instance name is default
• Multiple instances of the same devcontainer can run simultaneously

Container Labels

All Atmos devcontainers are labeled for management:

tools.atmos.type=devcontainer
tools.atmos.devcontainer.name={name}
tools.atmos.devcontainer.instance={instance}
tools.atmos.workspace={workspace-path}
tools.atmos.created={timestamp}

Runtime Auto-Detection

Atmos automatically detects the available container runtime:

1. Docker (checked first)
2. Podman (fallback)

Override with settings.runtime in the devcontainer configuration.

Key Commands

Lifecycle Management

atmos devcontainer start default           # Start (create if needed)
atmos devcontainer stop default            # Stop running container
atmos devcontainer remove default          # Remove container and data
atmos devcontainer rebuild default         # Destroy and recreate from scratch

Interactive Access

atmos devcontainer shell                   # Start + attach in one command
atmos devcontainer shell default           # Named devcontainer
atmos devcontainer attach default          # Attach to running container

Command Execution

atmos devcontainer exec default -- terraform plan
atmos devcontainer exec default -- aws sts get-caller-identity

Information

atmos devcontainer list                    # List all configured devcontainers
atmos devcontainer config default          # Display resolved configuration
atmos devcontainer logs default            # Show container logs

Instance Management

Multiple instances of the same devcontainer can run simultaneously:

atmos devcontainer start default --instance alice
atmos devcontainer start default --instance bob
atmos devcontainer list                    # Shows both instances
atmos devcontainer attach default --instance alice

Authentication Integration

Devcontainers integrate with the Atmos identity system for credential injection:

atmos devcontainer shell default --identity prod-admin
atmos devcontainer exec default --identity dev -- terraform plan

When --identity is specified, Atmos resolves the identity credentials and passes them to the container environment.

Common Patterns

Standard Development Environment

devcontainer:
  default:
    spec:
      name: "Infrastructure Dev"
      image: "cloudposse/geodesic:latest"
      workspaceFolder: "/workspace"
      workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"
      mounts:
        - "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly"
        - "type=bind,source=${HOME}/.ssh,target=/root/.ssh,readonly"
      containerEnv:
        ATMOS_BASE_PATH: "/workspace"
        AWS_PROFILE: "default"
      remoteUser: "root"

Multiple Environments

devcontainer:
  dev:
    spec:
      name: "Dev Environment"
      image: "cloudposse/geodesic:latest"
      containerEnv:
        ATMOS_BASE_PATH: "/workspace"
        ENVIRONMENT: "dev"

  prod:
    spec:
      name: "Prod Environment"
      image: "cloudposse/geodesic:latest"
      containerEnv:
        ATMOS_BASE_PATH: "/workspace"
        ENVIRONMENT: "prod"

Custom Dockerfile

devcontainer:
  custom:
    spec:
      name: "Custom Dev"
      build:
        dockerfile: .devcontainer/Dockerfile
        context: .
        args:
          TERRAFORM_VERSION: "1.9.8"
      workspaceFolder: "/workspace"
      workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"