# atmos ansible playbook

Use this command to run an Ansible playbook for an Atmos component in a stack, applying configuration
changes to target hosts.

## Usage

Execute the `ansible playbook` command like this:

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

:::tip
For more details on the `ansible-playbook` command and options, refer to [Ansible Playbook Documentation](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html).
:::

## Arguments

- **`component` (required)**

  Atmos Ansible component name or path.

## Flags

- **`--stack` (alias `-s`)(required)**

  Atmos stack.
- **`--playbook` (alias `-p`)(optional)**

  Ansible playbook file to execute. If not specified, uses the value from
  `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, 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 executing the playbook. Shows what commands would be run.

## Examples

### Basic Usage

```shell
# Run playbook with settings from stack manifest
atmos ansible playbook webserver --stack prod

# Specify playbook explicitly
atmos ansible playbook webserver -s prod --playbook site.yml

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

### Passing Ansible Options

Any arguments after `--` are passed directly to `ansible-playbook`:

```shell
# Check mode (dry run at Ansible level)
atmos ansible playbook webserver -s prod -- --check

# Verbose output
atmos ansible playbook webserver -s prod -- -vvv

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

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

# Skip specific tags
atmos ansible playbook webserver -s prod -- --skip-tags "slow"

# Run with extra variables
atmos ansible playbook webserver -s prod -- --extra-vars "version=1.2.3"
```

### Stack Configuration Example

Configure your Ansible component in the stack manifest:

When you run `atmos ansible playbook hello-world -s dev`, Atmos:

1. Generates a variables file with the `vars` section
2. Passes it to `ansible-playbook` via `--extra-vars @<varfile>`
3. Uses the playbook and inventory from settings (or command line flags)
4. Executes the playbook in the component directory

## Variable Handling

Atmos automatically generates a YAML variables file containing all variables from the component's
`vars` section. This file is passed to Ansible using `--extra-vars @<filename>`.

The generated file follows the naming convention: `<context>-<component>.ansible.vars.yaml`

For example, for a component `webserver` in stack `prod-us-east-1`, the file would be:
`prod-us-east-1-webserver.ansible.vars.yaml`

The file is automatically cleaned up after the playbook execution completes.

## Example