# atmos ansible

Use these subcommands to interact with [Ansible](https://docs.ansible.com/ansible/latest/index.html)
for automating infrastructure configuration, application deployment, and orchestration.

## Usage

```shell
# 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](https://docs.ansible.com/ansible/latest/cli/index.html).
:::

### 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:

```shell
# 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

```shell
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

```shell
# 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:

```shell
# 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:

```yaml
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