Atmos Ansible

atmos ansible playbook <component> -s <stack> [flags] [-- ansible-options]

# Basic playbook execution
atmos ansible playbook webserver -s prod

# Specify playbook explicitly (overrides stack manifest)
atmos ansible playbook webserver -s prod --playbook deploy.yml

# Specify both playbook and inventory
atmos ansible playbook webserver -s prod -p site.yml -i inventory/production

# Dry run (shows command without executing)
atmos ansible playbook webserver -s prod --dry-run

# Pass native ansible-playbook flags after --
atmos ansible playbook webserver -s prod -- --check
atmos ansible playbook webserver -s prod -- -vvv
atmos ansible playbook webserver -s prod -- --limit "web01,web02"
atmos ansible playbook webserver -s prod -- --tags "deploy,config"
atmos ansible playbook webserver -s prod -- --skip-tags "slow"
atmos ansible playbook webserver -s prod -- --extra-vars "version=1.2.3"

atmos ansible version

components:
  ansible:
    <component_name>:
      vars: {}              # Variables passed via --extra-vars
      env: {}               # Environment variables during execution
      settings:
        ansible:
          playbook: <file>  # Playbook file to run
          inventory: <src>  # Inventory source (file, directory, or script)
      metadata: {}          # Component behavior and inheritance
      command: ansible      # Override ansible binary
      hooks: {}             # Lifecycle event handlers

components:
  ansible:
    hello-world:
      vars:
        app_name: my-app
        app_version: "1.0.0"
        app_port: 8080
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory.ini

import:
  - catalog/ansible/_defaults
  - orgs/acme/plat/prod/_defaults

vars:
  region: us-east-1
  stage: prod

ansible:
  vars:
    managed_by: Atmos
  env:
    # Security note: Setting ANSIBLE_HOST_KEY_CHECKING to "false" disables SSH host key verification,
    # which exposes connections to man-in-the-middle attacks. Only use this in controlled environments
    # (e.g., ephemeral CI environments with known-clean network paths). For production environments,
    # maintain and distribute a known_hosts file or use the ansible_ssh_extra_args approach with
    # StrictHostKeyChecking=accept-new to accept keys on first connection only.
    ANSIBLE_HOST_KEY_CHECKING: "false"

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

    database:
      metadata:
        component: database
      vars:
        db_name: acme-prod
        db_port: 5432
      settings:
        ansible:
          playbook: deploy.yml
          inventory: inventory/production
      dependencies:
        components:
          - component: webserver

# These apply to all Ansible components
ansible:
  vars:
    managed_by: Atmos
  env:
    # Security note: ANSIBLE_HOST_KEY_CHECKING: "false" disables SSH host key verification and should
    # only be used in controlled environments. For production, use a known_hosts file instead.
    ANSIBLE_HOST_KEY_CHECKING: "false"
    ANSIBLE_FORCE_COLOR: "true"

# Individual components inherit and can override
components:
  ansible:
    webserver:
      vars:
        app_port: 8080

# Stack manifest
components:
  ansible:
    webserver:
      vars:
        app_name: myapp
        app_port: 8080

# Playbook references variables directly
- name: Deploy app
  hosts: webservers
  tasks:
    - name: Show config
      ansible.builtin.debug:
        msg: "Deploying {{ app_name }} on port {{ app_port }}"

# Stack manifest (lower priority)
components:
  ansible:
    webserver:
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory/production

# Command-line override (higher priority)
atmos ansible playbook webserver -s prod --playbook deploy.yml -i inventory/staging

components:
  ansible:
    # Executable to run
    command: ansible

    # Base path to Ansible components
    base_path: components/ansible

components/ansible/
  hello-world/
    site.yml
    inventory.ini
  webserver/
    site.yml
    roles/
      nginx/
    inventory/
      production
      staging
  database/
    deploy.yml
    inventory.ini