create-ansible-playbook.md

copyright	lastupdated	keywords	subcollection
years 2017, 2025	2025-11-18	schematics ansible, schematics action, create schematics actions, run ansible playbooks	schematics

{{site.data.keyword.attribute-definition-list}}

Creating an Ansible playbook

{: #create-playbook}

To create your Ansible playbook for use with {{site.data.keyword.bpshort}}, follow these prerequisites and the general steps. {: shortdesc}

Want to use existing Ansible playbooks to get started? Try out one of the IBM-provided Ansible playbooks or browse existing Ansible collections and roles in Ansible Galaxy{: external} {: tip}

• Prepare your resource inventory where you intend to run your Ansible playbook. You can also use {{site.data.keyword.bpshort}}'s built-in Terraform capabilities to provision target hosts. For more information, see Infrastructure deployment with {{site.data.keyword.bpshort}} workspaces.
• Develop your Ansible playbook. Use one of the IBM-provided playbooks or explore existing roles and collections in Ansible Galaxy{: external}. Reference these roles 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{: external}.
• Upload your Ansible playbook, modules, roles, and collections to your GitHub repository.
• Create a {{site.data.keyword.bpshort}} action 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 {{site.data.keyword.bpshort}}. For more information, see the Ansible documentation{: external} or playbook creation{: 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{: external} repository. {: shortdesc}

Similar to Ansible roles, collections require a specific folder structure in your GitHub repository.

Follow these steps to use collections in your {{site.data.keyword.bpshort}} playbook

1. Browse Ansible Galaxy{: 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. Here's an example by using the community.kubernetes collection.

   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.

   ├── 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{: external}. Ensure your playbook's folder structure adheres to the requirements and properly references the collections for seamless execution in {{site.data.keyword.bpshort}}.

Preparing Your Ansible Playbook for {{site.data.keyword.bpshort}}

{: #plan-ansible-playbook}

Before running your Ansible playbook in {{site.data.keyword.bpshort}}, 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 {{site.data.keyword.bpshort}} actions.
• Ensure that your playbooks are compatible with an Ansible version that is supported in {{site.data.keyword.bpshort}}. To check supported versions, run the ibmcloud schematics version command.
• Optionally, explore Ansible playbook capabilities in {{site.data.keyword.bpshort}} by using one of the IBM-provided Ansible playbooks.

Next steps

{: #create-playbook-nextsteps}

After understanding the prerequisites and preparation steps for your Ansible playbook, the next step is to create a {{site.data.keyword.bpshort}} action. 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 {{site.data.keyword.bpshort}} action to proceed.