> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/iagctl/create-service-ansible-playbook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl create service ansible-playbook

Create a new Ansible playbook service.

The `iagctl create service ansible-playbook` command creates an Ansible playbook service in the gateway data store. You can then run the service with the `iagctl run` command. For more information, see [Create gateway services](../create-gateway-service).

Consider an Ansible repository called `example-repo` with the following directory layout:

```bash
├── README.md
├── upgrade-plays
│   ├── upgrade-router.yml
│   ├── upgrade-switch.yml
│   ├── inventory.yml
│   ├── some-vars.yml
│   ├── requirements.yml
│   └── requirements.txt
```

To create a service from the playbooks in the `upgrade-plays` directory, specify the repository with `--repository`, the subdirectory with `--working-dir`, and the playbook files with `--playbook`.

## Prerequisites

Before you create an Ansible playbook service, you need a repository that contains your playbooks.

## Syntax

```bash
iagctl create service ansible-playbook <service-name> --repository <string> --playbook <string> [flags]
```

## Usage notes

### Extra variables

Pass Ansible extra variables with the `--extra-vars` flag using `key=value` syntax or JSON (for example, `{"key": "value"}`). To reference a variables file in the repository, use `--extra-vars-file`. The file path must be relative to your `--working-dir`.

### Requirements files

The gateway installs all dependencies listed in `requirements.yml` and `requirements.txt` when you run the service. You can specify the Ansible version in `requirements.txt`. If you don't specify a version, the gateway installs the latest version. Both requirements files must be in the `--working-dir`.

### Inventory

Specify inventory files with the `--inventory` flag. You can provide multiple inventory files, and the gateway loads them in the order you specify. File paths must be relative to your `--working-dir`.

### Decorators

You can attach a decorator to the service for input validation at runtime with the `--decorator` flag. For more information, see [iagctl create decorator](./create-decorator).

## Examples

### Create a basic Ansible playbook service

The following example creates a service called `my-ansible-service` where the playbook `main.yml` is at the root of the `my-repo` repository:

```bash
iagctl create service ansible-playbook my-ansible-service \
--repository my-repo \
--playbook main.yml
```

### Create an Ansible playbook service with all options

The following example creates a service that uses multiple playbooks, an inventory file, extra variables, and several Ansible-specific options:

```bash
iagctl create service ansible-playbook upgrade-os \
--repository example-repo \
--working-dir ansible_with_inventory \
--playbook upgrade-router.yml \
--playbook upgrade-switch.yml \
--inventory inventory.yml \
--extra-vars 'version=3.0' \
--extra-vars '{"rollback": false}' \
--extra-vars-file some-vars.yml \
--verbosity 6 \
--diff \
--check \
--forks 1 \
--decorator my-decorator \
--description "Simple Hello World" \
--tag hello
```

## Options

```bash
  --check                         Don't make changes; report potential changes instead.
  --config-file string            Path to an Ansible config file. Relative to the working directory root.
  --decorator string              The decorator to associate with the service.
  --description string            A brief description of the service.
  --diff                          Show differences without making changes. Typically used with --check.
  --extra-vars stringArray        Variables referenced by Ansible. Accepts JSON or key=value pairs.
  --extra-vars-file stringArray   Path to an Ansible extra-vars file in the repository. Relative to the working directory.
  --forks int                     Number of parallel processes to use.
  -h, --help                      Help for ansible-playbook.
  --inventory stringArray         Inventory files for the service. Provide multiple files to load them in order. Paths must be relative to the working directory root.
  --limit stringArray             Limit the hosts the playbook runs against.
  --playbook stringArray          Ansible playbook file in the repository. Must exist in the working directory, if specified. Provide multiple flags to run playbooks sequentially. (default [main.yml])
  --repository string             The gateway repository that contains the playbooks.
  --skip-tags string              Ansible tags to skip. Separate multiple tags with commas.
  --tag stringArray               Metadata tags to associate with the service.
  --tags string                   Ansible tags to use. Separate multiple tags with commas.
  --verbosity int                 Ansible output verbosity level, from 1 to 6. For example, set to 4 for the equivalent of -vvvv.
  --working-dir string            Path to the playbook directory, relative to the repository root. If not provided, the playbook runs from the repository root.
```

## Options inherited from parent commands

```bash
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --config string   Path to the configuration file
  --raw             Display the result of the command in raw format
  --verbose         Enable verbose output
```