Working with Ansible

Prerequisites

• Create an Ansible playbook and store the playbook in a GitHub or GitLab repository. Or you can try to use one of the IBM-provided Ansible playbooks.
• Make sure that you have the permissions to create the Schematics action.

Ensure the location and the url endpoint are pointing to the same region when you create or update the Schematics workspaces and actions. For more information about location and endpoint, see Where is the information stored?

To create an Ansible playbook

1. Log in to IBM Cloud console.

2. Click the Menu icon > Platform Automation > Schematics > Ansible > Create playbook.

   • Configure your action.
     1. Enter a playbook Name and an Description for your action. Note that the name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores.
     2. Optional, enter the Tags that you want to add to your action. Tags help in quick search operation of your action.
     3. Select the Resource group where you want to create the action.
     4. Select the Location where you want to create the action. The location determines where your action runs and action data are stored. You can choose a geography, such as North America, or a location, such as Frankfurt or London. If you select a geography, Schematics decides on a location within this geography based on availability. Be sure that you can store your action data in this location as you cannot change the location after the action is created. For more information, see where is the information stored? Note that the location of your action is independent from the location of your IBM Cloud resource where you want to run your Ansible playbook.
     5. Click Create. Your action is created with a Normal state, and you are directed to the Details section.

3. In the Ansible playbook section, click Edit icon to import your Ansible playbook.

   1. Enter the GitHub or GitLab repository URL where your Ansible playbook is stored. The URL can point to the master branch, any other branch, or a subdirectory. If your repository stores multiple playbooks, you must select the playbook that you want to run. A Schematics action can point to one playbook at a time. To run multiple playbooks, you must create a separate action for each playbook.

      • Example for master branch - https://github.com/myorg/myrepo
      • Example for other branches - https://github.com/myorg/myrepo/tree/mybranch
      • Example for subdirectory - https://github.com/mnorg/myrepo/tree/mybranch/mysubdirectory

      Don't have a playbook that you can use? Try out one of your sample playbooks.

   2. Optional, if you want to use a private GitHub repository, enter your personal access token. The personal access token is used to authenticate private GitHub repository to access your Ansible playbook. For more information about how to create an access token, see creating a personal access token for the command line. If you need see the allowed and blocked file extensions for cloning from the Git repository.

   3. Review the default Ansible version that is used to run your playbook. This version cannot be changed. If you use your own Ansible playbook, make sure that your playbook uses the specified Ansible version. For example, Ansible v2.9.23.

   4. Click Retrieve playbooks to connect to your repository and retrieve all Ansible playbooks from your Git repository.

   5. Select the playbook that you want to run. A Schematics action can point to one playbook at a time. To run multiple playbooks, you must create a separate action for each playbook.

   6. Select the Verbosity level. The verbosity level determines the depth of information that is written to the logs when your Ansible playbook is executed. The supported values are 0 (Normal), 1 (verbose), 2 (More Verbose), 3 (Debug), 4 (Connection Debug). For example, if you want to debug your playbook or want to include a detailed summary for each task that Ansible runs, select a high verbosity level. You can view the logs when your playbook runs.

   7. Optional, click the Advanced options to define input variables that you want to pass to the playbook. Input variables must be entered in key-value pairs. If the variable contains sensitive information, enable the Sensitive option so that the value is hidden for the users after the action is created. If you use one of the IBM-provided Ansible playbooks, all input variables can be found in the readme.md file.

   8. Click Save to save the action details.

4. Configure your resource inventory. The resource inventory includes all target hosts where you want to run your Ansible playbook.

   1. In the Choose your inventory section, click the Edit icon.
   2. From the resource inventory table, select an existing resource inventory. If you do not have a resource inventory yet, click Create Inventory to create one. For more information about creating resource inventories, see Creating static inventory files or Dynamically building resource inventories from Schematics workspaces.
   3. Action supports SSH and WinRM types of inventory connection tab to connect to your remote host.
      • Select SSH tab to enter the username and IBM Cloud resource inventory private SSH key that you want to use to connect to your target hosts. All hosts must be configured with the matching public SSH key so that Schematics can connect to your hosts and run your playbook.
        • Select the Bastion host access is required, for the bastion host access. To use a different SSH key to connect to your bastion host, deselect the Use the same key for bastion host option. For more information about SSH keys, see Adding an SSH key.
      • Select WinRM tab, for the communication between the client and the server. Currently, WinRM supports only Windows system with the public IPs and do not support Bastion host.
        • Provide the Username and the Password of your Windows system with the public IP.
   4. Click Save.

   For more information about creating inventories in for Schematics actions, see static inventory and dynamic inventory

5. Click Check action to verify your action details. The Jobs page opens automatically and you can view the results in the logs. This check verifies that your playbook can be run in Schematics. To change your action settings, return to the action's Settings page and click the edit icon.

6. Click Run action to run the action. You can monitor the progress of an action by reviewing the logs on the Jobs page. Every 30 seconds the job logs are automatically refreshed.

   You cannot delete or stop a running job of your Schematics action. To change your action, wait for the job to complete, then change your settings, and click Check action or Run action again.

State diagram flow

The following table represents the actions state workflow.

Action state workflow

Action	State diagram	Description
Create		When the user creates an action, initially the state of an action is in Draft state. If user provides the template during create or after create, then action goes to Pending state. If the template processing is success, action goes to Normal state. If the template manager sets disable to stop the usage, then action goes to Disable state. If there is an error in template processing, action goes to Critical state.
Delete		When the user selects to delete an existing action, initially action goes into Pending state. If the template deletion fails action goes to Critical state.
Update		When the user clicks an existing action to update the template repository, immediately action goes to pending state. If the template processing is success, action goes to the Normal state. If the user tries to set the template repository to disable, action goes to the Disabled state. Finally, if the template processing fails, action goes to Critical state.