Skip to main content

atmos ansible

Use these subcommands to interact with Ansible for automating infrastructure configuration, application deployment, and orchestration.

atmos ansible --help

Usage​

# For playbook subcommand (requires component and stack)
atmos ansible playbook <atmos-component> --stack <atmos-stack> [atmos-flags] -- [ansible-options]

# For version subcommand (no arguments required)
atmos ansible version
tip

For more details on Ansible commands and options, refer to the Ansible Documentation.

Path-Based Component Resolution​

Atmos supports using filesystem paths instead of component names for convenience. This allows you to navigate to a component directory and use . to reference it:

# Navigate to component directory
cd components/ansible/webserver

# Use . to reference current directory
atmos ansible playbook . -s prod

This automatically resolves the path to the component name configured in your stack, eliminating the need to remember exact component names.

Supported path formats:

  • . - Current directory
  • ./component - Relative path from current directory
  • ../other-component - Relative path to sibling directory
  • /absolute/path/to/component - Absolute path

Requirements:

  • Must be inside a component directory under the configured base path
  • Must specify --stack flag
  • Component must exist in the specified stack configuration
  • The component path must resolve to a unique component name - If multiple components in the stack reference the same component path, you must use the unique component name instead of the path

Atmos Flags​

--stack (alias -s)

Atmos stack.

--playbook (alias -p)(optional)

Ansible playbook file to execute. Defaults to the playbook specified in settings.ansible.playbook in the stack manifest.

The command line flag takes precedence over the stack manifest setting.

--inventory (alias -i)(optional)

Ansible inventory source. Can be a file path, directory, or dynamic inventory script.

Can also be specified via settings.ansible.inventory in the stack manifest. The command line flag takes precedence.

--dry-run(optional)

Perform a dry run without making actual changes. Displays the commands that would be executed.

Examples​

Component Name Examples​

atmos ansible version

atmos ansible playbook webserver --stack prod
atmos ansible playbook webserver -s prod --playbook site.yml
atmos ansible playbook webserver -s nonprod -p deploy.yml -i hosts.ini

Path-Based Examples​

# Navigate to component directory and use current directory
cd components/ansible/webserver
atmos ansible playbook . -s prod

# Use relative path from components/ansible directory
cd components/ansible
atmos ansible playbook ./webserver -s prod

# Use from project root with relative path
atmos ansible playbook components/ansible/webserver -s prod

# Combine with other flags
cd components/ansible/webserver
atmos ansible playbook . -s prod --playbook deploy.yml --inventory production

Passing Additional Ansible Options​

Any flags after -- are passed directly to the underlying Ansible command:

# Run playbook in check mode (dry run)
atmos ansible playbook webserver -s prod -- --check

# Run with verbose output
atmos ansible playbook webserver -s prod -- -vvv

# Limit to specific hosts
atmos ansible playbook webserver -s prod -- --limit web01

# Run with specific tags
atmos ansible playbook webserver -s prod -- --tags "deploy,config"

Arguments​

atmos-component (required for playbook)

Atmos component name or filesystem path.

Supports both:

  • Component names: webserver, database/postgres
  • Filesystem paths: . (current directory), ./webserver, components/ansible/webserver

When using paths, Atmos automatically resolves the path to the component name based on your stack configuration. See Path-Based Component Resolution above.

Stack Configuration​

Configure Ansible components in your stack manifests:

components:
  ansible:
    webserver:
      vars:
        app_name: myapp
        app_port: 8080
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory/production

Variables defined in vars are passed to Ansible as extra variables via a generated YAML file.

Subcommands​