Skip to main content

atmos ansible

Configure hosts and deploy applications with Ansible using your Atmos stacks. Define playbooks and inventories alongside your infrastructure configuration, then select the component and environment you want to operate.

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​