Creating an Ansible playbook

To create your Ansible playbook for use with Schematics, follow these prerequisites and the general steps.

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

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

Referencing Ansible collections in your playbook

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 repository.

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

Follow these steps to use collections in your Schematics playbook

Browse Ansible Galaxy to find the collection that you want to use in your playbook.
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
```
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
```
Reference a resource from your collection in your playbook. For more information, see the Ansible documentation. 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

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

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.
Ensure that your playbooks are compatible with an Ansible version that is supported in Schematics. To check supported versions, run the ibmcloud schematics version command.
Optionally, explore Ansible playbook capabilities in Schematics by using one of the IBM-provided Ansible playbooks.

Next steps

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