Red Hat SummitChapter 5. Writing and running a playbook with Ansible development tools
5.1. Setting up the Ansible configuration file for your playbook project
When you scaffolded your playbook project, an Ansible configuration file, ansible.cfg, was added to the root directory of your project.
If you have configured a default Ansible configuration file in /etc/ansible/ansible.cfg, copy any settings that you want to reuse in your project from your default Ansible configuration file to the ansible.cfg file in your project’s root directory.
To learn more about the Ansible configuration file, see Ansible Configuration Settings in the Ansible documentation.
5.2. Writing your first playbook
The instructions below describe how Ansible development tools help you to create and run your first playbook in VS Code.
Prerequisites
- You have installed and opened the Ansible VS Code extension.
- You have opened a terminal in VS Code.
-
You have installed
ansible-devtools.
Procedure
-
Create a new .yml file in VS Code for your playbook, for example
example_playbook.yml. Put it in the same directory level as the examplesite.ymlfile. Add the following example code into the playbook file and save the file. The playbook consists of a single play that executes a
pingto your local machine.--- - name: My first play hosts: localhost tasks: - name: Ping my hosts ansible.builtin.ping:Ansible-lintruns in the background and displays errors in the Problems tab of the terminal. There are no errors in this playbook:
- Save your playbook file.
5.3. Inspecting your playbook
The Ansible VS Code extension provides syntax highlighting and assists you with indentation in .yml files.
The following rules apply for playbook files:
- Every playbook file must finish with a blank line.
- Trailing spaces at the end of lines are not allowed.
- Every playbook and every play require an identifier (name).
5.3.1. Inline help
The Ansible extension also provides inline help when you are editing your playbook file.
If you hover your mouse over a keyword or a module name, the Ansible extension provides documentation:
If you begin to type the name of a module, for example
ansible.builtin.ping, the extension provides a list of suggestions.Select one of the suggestions to autocomplete the line.
5.4. Running your playbook
The Ansible VS Code extension provides two options to run your playbook:
-
ansible-playbookruns the playbook on your local machine using Ansible Core. -
ansible-navigatorruns the playbook in an execution environment in the same manner that Ansible Automation Platform runs an automation job. You specify the base image for the execution environment in the Ansible extension settings.
5.4.1. Running your playbook with ansible-playbook
Procedure
To run a playbook, right-click the playbook name in the Explorer pane, then select
. 
The output is displayed in the Terminal tab of the VS Code terminal. The ok=2 and failed=0 messages indicate that the playbook ran successfully.
5.4.2. Running your playbook with ansible-navigator
Prerequisites
- In the Ansible extension settings, enable the use of an execution environment in Ansible Execution Environment > Enabled.
- Enter the path or URL for the execution environment image in Ansible > Execution Environment: Image.
Procedure
To run a playbook, right-click the playbook name in the Explorer pane, then select
. The output is displayed in the Terminal tab of the VS Code terminal. The Successful status indicates that the playbook ran successfully.
Enter the number next to a play to step into the play results. The example playbook only contains one play. Enter
0to view the status of the tasks executed in the play.
Type the number next to a task to review the task results.
For more information on running playbooks with automation content navigator, see Executing a playbook from automation content navigator in the Automation content navigator creator guide Guide.
5.4.3. Working with execution environments
You can view the automation execution environments provided by Red Hat in the Red Hat Ecosystem Catalog.
Click on an execution environment for information on how to download it.
Log in to
registry.redhat.ioif you have not already done so.NoteIf you are running Ansible development tools on a container inside VS Code and you want to pull execution environments or the
devcontainerto use as an execution environment, you must log in toregistry.redhat.iofrom a terminal prompt within thedevcontainerinside VS Code.Using the information in the Red Hat Ecosystem Catalog, download the execution environment you need.
For example, to download the minimal RHEL 8 base image, run the following command:
$ podman pull registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9
You can build and create custom execution environments with ansible-builder. For more information about working with execution environments locally, see Creating and consuming execution environments.
After customizing your execution environment, you can push your new image to the container registry in automation hub. See Publishing an automation execution environment in the Creating and consuming execution environments documentation.
5.5. Debugging your playbook
5.5.1. Error messages
The following playbook contains multiple errors:
- name:
hosts: localhost
tasks:
- name:
ansible.builtin.ping:The errors are indicated with a wavy underline in VS Code. Hover your mouse over an error to view the details:
The errors are listed in the Problems tab of the VS Code terminal. Playbook files that contain errors are indicated with a number in the Explorer pane:
$[0].tasks[0].name None is not of type 'string' indicates that the playbook does not have a label.
5.6. Testing your playbooks
To test your playbooks in your project, run them in a non-production environment such as a lab setup or a virtual machine.
Automation content navigator (ansible-navigator) is a text-based user interface (TUI) for developing and troubleshooting Ansible content with execution environments.
Running a playbook using ansible-navigator generates verbose output that you can inspect to check whether the playbook is running the way you expected. You can specify the execution environment that you want to run your playbooks on, so that your tests replicate the production setup on Ansible Automation Platform:
To run a playbook on an execution environment, run the following command from the terminal in VS Code:
$ ansible-navigator run <playbook_name.yml> -eei <execution_environment_name>
For example, to execute a playbook called
site.ymlon the Ansible Automation Platform RHEL 9 minimum execution environment, run the following command from the terminal in VS Code.ansible-navigator run site.yml --eei ee-minimal-rhel8
The output is displayed in the terminal. You can inspect the results and step into each play and task that was executed.
For more information about running playbooks, refer to Running Ansible playbooks with automation content navigator in the Automation content navigator creator guide guide.
