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

# ZPE Cloud dynamic inventory

> How to create and manage ZPE Cloud dynamic inventory in Itential Gateway using the Nodegrid and ZPE Cloud plugins.

To create and manage device inventory via plugin, several steps are required. This guide covers the Nodegrid and ZPE Cloud plugin.

> **Info**
>
> **Related reading:** [ZPE Cloud automation with Ansible](https://docs.zpesystems.com/guides/docs/configure-sequential-profiling-using-zpe-cloud-libraries)

## Prerequisites

Verify you are using the correct Ansible and Python binaries. Depending on your setup in Itential Gateway, it will change how you perform a few of the steps below.

If you are using the default `python3` bin location at `/usr/local/bin/python3` or `/usr/bin/python3`, ensure the location of the `python3` binary matches your path:

```bash
which python3
```

If you are using a Python VENV (virtual environment), source the VENV first:

```bash
source /opt/automation-gateway/.venv/bin/activate
```

Then use the binary location of the Python VENV:

```bash
source /opt/automation-gateway/.venv/bin/activate && which python3
```

Sourcing the VENV first will ensure the Ansible and Python binaries are the correct ones being used by Gateway.

#### Install the Nodegrid collection

1. Download the repository:

   ```bash
   git clone https://github.com/ZPESystems/Ansible.git
   ```

2. Enter the Ansible directory:

   ```bash
   cd Ansible
   ```

3. Build the library using the `build.py` script:

   ```bash
   python3 build.py
   ```

4. Install the collection with ansible-galaxy:

   ```bash
   ansible-galaxy collection install -r build/collections/requirements.yml --force
   ```

5. In the `/etc/ansible/ansible.cfg` file, define the key `interpreter_python` with the location of the Python interpreter. This is the minimal recommended `ansible.cfg` content:

   ```ini
   [defaults]

   interpreter_python = /usr/bin/python3

   gathering = explicit

   host_key_checking = False

   [ssh_connection]

   ssh_args = -o ControlMaster=no -o ControlPersist=3600s -o PreferredAuthentications=publickey
   ```

#### Install ZPE Cloud collection

Once the Nodegrid collection is installed in Gateway, install the ZPE Cloud collection to access ZPE Cloud features. The installation process involves the following steps:

1. Download and install the ZPE Cloud collection.
2. Set up a dynamic inventory.
3. Set up the connection plugin.

#### Install the connection plugin

Before installing, ensure the following prerequisites are met:

* Nodegrid version 5.6.5 or higher is recommended.
* An account with ZPE Cloud based on which the inventory is created.

1. On the Ansible controller, install the ZPE Cloud collection:

   ```bash
   ansible-galaxy install zpe.zpecloud
   ```

2. Set up the `zpecloud` dynamic inventory plugin by creating a file called `zpecloud.yml` in the Ansible inventory folder with the following content:

   ```yaml
   plugin: zpe.zpecloud.zpecloud_nodegrid_inventory
   url: https://zpecloud.com
   username: youruser@email.com
   password: yourpassword
   organization: yourcompanyname
   ```

   * If the URL field is left unassigned, `zpecloud.com` is set as the default value.
   * The `organization` field is required only if you have more than one organization associated with the account. This field is case-sensitive.

3. Test the inventory connection to display the list of available devices:

   ```bash
   ansible-inventory --graph
   ```

4. Set up the connection plugin by providing the same details used during the inventory setup. This plugin is used to access the ZPE Cloud API. In the Ansible inventory folder, create a `group_vars` folder and a file called `zpecloud_device_enrolled.yml` with the following content:

   ```yaml
   "ansible_connection": zpe.zpecloud.zpecloud
   "ansible_zpecloud_username": "youruser@email.com"
   "ansible_zpecloud_password": "password"
   "ansible_zpecloud_organization": "yourcompanyname"
   "ansible_python_interpreter": "/usr/bin/python3"
   ```

You now have all the required components installed and can start creating and running a playbook.

#### Create and run a playbook

Create a sample playbook executed against the online Nodegrid devices in the inventory to display the gathered default facts from the specific Nodegrid device.

1. In your Ansible playbook directory, create a sample playbook file called `zpecloud_get_facts.yml` with the following content:

   ```yaml
   name: Get Ansible Facts
   hosts: zpecloud_device_online
   gather_facts: True
   tasks:
      - name: Display Systems Facts
   debug:
      var: ansible_facts
   ```

2. Run the playbook:

   ```bash
   ansible-playbook zpecloud_get_facts.yml
   ```

#### Make ZPE Cloud work with Gateway

In Gateway, navigate to **Configuration** > **Automation Gateway** > **Ansible**.

Under the **Inventory File** section, set your path to the full path of your `zpecloud.yml` file:

```bash
/opt/automation-gateway/ansible/inventory/zpecloud.yml
```

Restart Gateway to initialize the new external (dynamic) inventory:

```bash
systemctl restart automation-gateway
```

![](/_fern-img/8bcfb90088d8a26323dd72e1db199fae9f76b332fb8996c9388484015694414f.webp)