---
name: schematics-inventories
title: Creating resource inventories for Schematics actions
description: A resource inventory defines a single IBM Cloud resource or a group of resources where you want to run Ansible playbooks, modules, or roles by using Schematics actions.
last-updated: 2025-11-18
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/schematics?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Creating resource inventories for Schematics actions
{: #inventories-setup}

A resource inventory defines a single IBM Cloud resource or a group of resources where you want to run Ansible playbooks, modules, or roles by using Schematics actions.
{: shortdesc}

You can specify your resource inventory by using a [static inventory file](#static-inv), or [dynamically retrieve](#dynamic-inv) target IBM Cloud resources from Schematics workspaces.

## Creating static inventory files
{: #static-inv}

Schematics supports the definition of `hosts.ini` files where you specify a single target host or a group of target hosts using their IP address. You can assign names to a group of target hosts, such as `[webserver]`, and use this name in your Ansible playbook to instruct Schematics where to run the playbook tasks.
{: shortdesc}

### Defining static hosts
{: #static-host-defs}

To connect to a target host through SSH, Ansible requires either a DNS resolvable hostname or an IP address.

Typical usage of Schematics actions to configure VSI's on IBM Cloud is through a bastion host. See [actions documentation](https://cloud.ibm.com/docs/schematics?topic=schematics-sc-actions&format=markdown). Access to the private network interface of a VSI is through a bastion host. This means using the hosts private IP address to connect to the target host, as private host names are not advertised by DNS to Schematics. For private hosts, inventory must be configured with an IP address and the IP address of a bastion host.

VSI's with public IP addresses and publicly registered DNS host names can be referenced by fully qualified DNS host names.

The use of (short form) hostnames is not supported.

### Creating the host file
{: #static-inv-create}

1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}.
2. Click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation**  >  **Schematics** > **Ansible**.
3. Click the playbook name.
4. Click **Inventory** > **Create Inventory**.
5. Enter a name for your inventory, verify your location, and select your `Resource group` where you want to create an inventory.
6. Select the **Define manually** tab.
7. In the **File** field, enter the target hosts where you want to run the Ansible playbook. Make sure to specify your hosts in an `INI` syntax. For a sample syntax, see [File format](#inv-file-format). Review the [limitations](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown#inv-file-limitation) to ensure that your inventory definition is supported in Schematics.
8. Click **Create inventory**.
9. Follow the [steps](https://cloud.ibm.com/docs/schematics?topic=schematics-action-working&interface=ui&format=markdown) to create a Schematics actions and use the resource inventory that you created.

### File format
{: #inv-file-format}

Review the following sample `hosts.ini` file to see the structure of the static host inventory list. For more information about `hosts.ini` file structures, see [Ansible documentation](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-to-build-your-inventory){: external}.

This example references both publicly accessible hosts through host name and private hosts through IP address.

```text
mail.example.com

[webservers]
web1.mydomain.com
web2.mydomain.com

[dbservers]
172.16.5.9
172.16.5.10
172.16.5.11

[datacenters]
172.15.4.0
```
{: screen}

### Limitations
{: #inv-file-limitation}

Review the following limitations of static inventory files in Schematics:

- Schematics supports only the `INI` file syntax.
- Variables are not supported in `hosts.ini` files.
- Specifying host groups by using key-value pairs in `hosts.ini` files is not supported.
- You must manually update the `hosts.ini` file if hostname or IP address of target hosts change.
- Where hosts are secured by a bastion host and only accessible through private IP address, the IP address of the host must be specified.
- Where hosts are accessible through a publicly accessible IP address and have a registered DNS name, the host can be referenced by its fully qualified host name.
- All target hosts must be configured with the same public SSH key. When you use the static inventory file in your Schematics action, you can specify one SSH key to authenticate with all target hosts that are included in your resource inventory. The SSH key should contain `\n` at the end of the key details in case of command-line or API calls. For more information about SSH keys, see [Adding an SSH key](https://cloud.ibm.com/docs/ssh-keys?topic=ssh-keys-adding-an-ssh-key&format=markdown).

## Dynamically building resource inventories from Schematics workspaces
{: #dynamic-inv}

You can dynamically build your resource inventory from the Cloud resources that you provisioned with Schematics workspaces.
{: shortdesc}

Dynamic resource inventories references Cloud resources that you provisioned with Schematics workspaces. To retrieve the Cloud resources from your workspaces, use predefined resource queries. You do not need to keep track of the IP addresses that were assigned to your target resources as Schematics automatically determines the target hosts when you use this inventory in the Schematics action.

1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}.
2. Click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation** > **Schematics** > [**Ansible**](https://cloud.ibm.com/automation/schematics/ansible){: external}.
3. Click the playbook name.
4. Click **Inventory** > **Create Inventory**.
5. Enter a name for your inventory, verify your location, and select your `Resource group` where you want to create an inventory.
6. Select the **Host groups** tab.
7. Click **Create host group**.
8. Enter a name for your host group and select the Schematics workspace that provisioned the target hosts that you want to add to your host group.
9. Optional: Click **Add query** to add another condition to your query and limit the number of target hosts that are added to your host group. You can choose to identify your hosts by using the resource name or a tag. For more information, see [supported resource queries](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown#supported-queries).
10. Repeat step 5-8 to add more host groups.
11. From the table list, select the host groups that you want to include in your resource inventory.
12. Click **Create inventory**.
13. Follow the [steps](https://cloud.ibm.com/docs/schematics?topic=schematics-action-working&interface=ui&format=markdown) to create the Schematics actions and use the resource inventory that you created.

### Supported resource queries
{: #supported-queries}

|Supported query|Description|
|--|--|
|Workspace name|Select all the Cloud resources from a specific workspace.|
|Workspace name AND resource name|Select a specific resource from a specific workspace by using the resource name. To select multiple resources from the same workspace, you can add multiple queries of this type. |
|Workspace name AND tag|Select a specific resource from a specific workspace by using tags. Tags are added to the resource when you create the workspace and provision your resource. To select multiple resources with different tags from the same workspace, you can add multiple queries of this type. |
{: caption="Resource query" caption-side="top"}

### Limitations
{: #dynamic-inv-limitation}

Review the following limitations of dynamic inventories in Schematics:

- You can choose among the [supported queries](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown#supported-queries) to select the target virtual server instances to include in your resource inventory.
- Schematics retrieves the IP address of a target Virtual Servers for VPCs and adds the IP address to the resource inventory. If the target Virtual Servers for VPC has a public IP address, the public IP address is used for the resource inventory. If there is no public IP address, the private IP address is used for the resource inventory.
- All target hosts must be configured with the same public SSH key. When you use the static inventory file in your Schematics action, you can specify one SSH key to authenticate with all target hosts that are included in your resource inventory. The SSH key should contain `\n` at the end of the key details in case of command-line or API calls. For more information about SSH keys, see [Adding an SSH key](https://cloud.ibm.com/docs/ssh-keys?topic=ssh-keys-adding-an-ssh-key&format=markdown).