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

# Ansible collections in Gateway

> How to discover, install, refresh, and navigate Ansible Collections in Itential Gateway.

Itential Gateway provides Ansible Collections support. Ansible Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. You can install and use collections through [Ansible Galaxy](https://galaxy.ansible.com/). To learn more about collections, see the official [Ansible Collections](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html) documentation guide.

A complete set of REST APIs are available for clients to manage and execute Ansible collections. See the API Documentation section within the Automation Gateway UI for more information.

## Discovery

The Gateway server performs discovery of collections at startup time and maintains a cache of all managed collections in memory. You can determine the collections that are managed by providing either a single path or a list of directory paths in the Gateway `properties.yml` configuration file. A recursive search of the directory paths is performed.

```yaml
#
# Path(s) to the set of Ansible Collections you would like to invoke from Gateway.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
collection_path: ['/usr/share/ansible/collections', '/usr/share/ansible/collections2']
```

## Install collections in Gateway

Ansible collections can be installed from a tarball or from the Ansible Galaxy server using the `{IAG_Url}/collections/install` API.

### Install a collection from Ansible Galaxy server

To install a collection via Ansible Galaxy server, use the API mentioned above from either Postman or the API Documentation section within the Automation Gateway UI.

The request object format is given below. Note that `package_name` is the name of the collection to be installed.

```json
{
  "force": true,
  "package_name": "string",
  "server_params": {
    "auth_url": "string",
    "password": "string",
    "token": "string",
    "url": "string",
    "username": "string"
  },
  "version": "string"
}
```

## Refresh collections in Gateway

If new collections are installed and need to be discovered and cached by Gateway, there are two ways to accomplish this:

1. Use the `/collections/refresh` API from the API Documentation in Gateway, or send a POST request to `{IAG_url}/collections/refresh` in Postman.
2. From the Gateway Collections UI, click the refresh icon.

![](/_fern-img/bcb019e4fedcb3e397ecc94b513d6d6304437b72fe7153249ab0410bd177fb8c.webp)

## Navigate the collections UI

#### Open the collections list

Select **Ansible** in the left navbar and then select **Collections**. A list of all the collections in Gateway will display.

#### View collection details

Click on an individual collection in the list. Two cards (Modules and Roles) will appear side-by-side.

#### Search within a collection

Use the search bar to search for Modules and Roles in the collection.

#### Page through collection items

Use the pagination controls at the bottom of each card to page through a collection. These controls can also be used to set how many items to display at once.

![](/_fern-img/ec846663fc0b3b05dae0849c18ba702558f1c7609d5f2afca7d9e1e8d88c0393.webp)

> How to discover, install, refresh, and navigate Ansible Collections in Itential Gateway.