---
name: schematics-create-ansible-playbook
title: Creating an Ansible playbook
description: To create your Ansible playbook for use with Schematics, follow these prerequisites and the general steps.
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 an Ansible playbook
{: #create-playbook}

To create your Ansible playbook for use with Schematics, follow these [prerequisites](https://cloud.ibm.com/docs/schematics?topic=schematics-create-playbook&format=markdown#plan-ansible-playbook) and the general steps.
{: shortdesc}

Want to use existing Ansible playbooks to get started? Try out one of the [IBM-provided Ansible playbooks](https://cloud.ibm.com/docs/schematics?topic=schematics-sample_actiontemplates&format=markdown) or browse existing Ansible collections and roles in [Ansible Galaxy](https://galaxy.ansible.com/){: external}
{: tip}

- [Prepare your resource inventory where you intend to run your Ansible playbook](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown). You can also use Schematics's built-in Terraform capabilities to provision target hosts. For more information, see [Infrastructure deployment with Schematics workspaces](https://cloud.ibm.com/docs/schematics?topic=schematics-how-it-works&format=markdown#how-to-workspaces).
- Develop your Ansible playbook. Use one of the [IBM-provided playbooks](https://cloud.ibm.com/docs/schematics?topic=schematics-sample_actiontemplates&format=markdown) or explore existing roles and collections in [Ansible Galaxy](https://galaxy.ansible.com/){: external}. Reference these [roles](https://cloud.ibm.com/docs/schematics?topic=schematics-ansible-roles-galaxy&format=markdown#main-file) and collections](/docs/schematics?topic=schematics-create-playbook#schematics-collections) in your playbook as needed.
- Establish a GitHub or GitLab repository, and organize your Ansible playbook, modules, roles, and collections according to the required directory structure. A sample structure can be found in this [sample playbook](https://github.com/Cloud-Schematics/ansible-app-deploy-iks/blob/master/site.yml){: external}.
- Upload your Ansible playbook, modules, roles, and collections to your GitHub repository.
- [Create a Schematics action](https://cloud.ibm.com/docs/schematics?topic=schematics-action-working&interface=ui&format=markdown) by using the uploaded playbook.

Ensure that your playbook adheres to the necessary structure and references any required roles and collections for seamless execution in Schematics. For more information, see the [Ansible documentation](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html){: external} or [playbook creation](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_playbook.html){: external}.

## Referencing Ansible collections in your playbook
{: #schematics-collections}

Ansible collections are groups of reusable Ansible resources, such as playbooks, modules, and roles, that you can install and use in your playbook. Collections are available in the [Ansible Galaxy](https://galaxy.ansible.com/){: external} repository.
{: shortdesc}

Similar to [Ansible roles](https://cloud.ibm.com/docs/schematics?topic=schematics-ansible-roles-galaxy&format=markdown#main-file), collections require a specific folder structure in your GitHub repository.

Follow these steps to use collections in your Schematics playbook

1. Browse [Ansible Galaxy](https://galaxy.ansible.com/){: external} to find the collection that you want to use in your playbook.
2. Create a `requirements.yml` file to specify the collections you want to install from Ansible Galaxy. The file structure should follow the [Ansible documentation](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-collections). Here's an example by using the `community.kubernetes` collection.

    ```yaml
    collections:
      - name: community.kubernetes
        version: 0.9.0
    ```
    {: codeblock}

3. Add a `collections` folder to your GitHub repository, relative to your playbook, and place the `requirements.yml` file inside this folder.

    ```text
    ├── collections
            └── requirements.yml
    ├── playbook.yaml
    ├── README.md
    ```
    {: screen}

4. Reference a resource from your collection in your playbook. For more information, see the [Ansible documentation](https://docs.ansible.com/projects/ansible/2.9/user_guide/collections_using.html#using-collections-in-a-playbook){: external}. Ensure your playbook's folder structure adheres to the requirements and properly references the collections for seamless execution in Schematics.

## Preparing Your Ansible Playbook for Schematics
{: #plan-ansible-playbook}

Before running your Ansible playbook in Schematics, consider the following points:
{: shortdesc}

- Store your Ansible playbook in a GitHub or GitLab repository.
- Be aware of the limitations when specifying target hosts for your Ansible resource inventory. For more information, refer to the guidelines on [Creating resource inventories for Schematics actions](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown).
- Ensure that your playbooks are compatible with an Ansible version that is supported in Schematics. To check supported versions, run the [`ibmcloud schematics version`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-version) command.
- Optionally, explore Ansible playbook capabilities in Schematics by using one of the [IBM-provided Ansible playbooks](https://github.com/Cloud-Schematics?q=topic%3Aansible-playbook).

## Next steps
{: #create-playbook-nextsteps}

After understanding the prerequisites and preparation steps for your Ansible playbook, the next step is to [create a Schematics action](https://cloud.ibm.com/docs/schematics?topic=schematics-action-working&format=markdown). This process involves specifying your Ansible playbook, configuring the resource inventory, and setting up any necessary credentials or variables. Follow the guide on creating a Schematics action to proceed.