Chapter 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 example site.yml file. Add the following example code into the playbook file and save the file. The playbook consists of a single play that executes a ping to your local machine. --- - name: My first play hosts: localhost tasks: - name: Ping my hosts ansible.builtin.ping: Ansible-lint runs 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-playbook runs the playbook on your local machine using Ansible Core. ansible-navigator runs 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 Run Ansible Playbook via Run playbook via ansible-playbook . 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 Run Ansible Playbook via Run playbook via ansible-navigator run . 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 to a play to step into the play results. The example playbook only contains one play. Enter 0 to view the status of the tasks executed in the play. Type the number 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.io if you have not already done so. Note If you are running Ansible development tools on a container inside VS Code and you want to pull execution environments or the devcontainer to use as an execution environment, you must log in to registry.redhat.io from a terminal prompt within the devcontainer inside 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: USD 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: USD[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: USD ansible-navigator run <playbook_name.yml> -eei <execution_environment_name> For example, to execute a playbook called site.yml on 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.

Commands:
--- - name: My first play hosts: localhost tasks: - name: Ping my hosts ansible.builtin.ping:
podman pull registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9
- name: hosts: localhost tasks: - name: ansible.builtin.ping:
ansible-navigator run <playbook_name.yml> -eei <execution_environment_name>
ansible-navigator run site.yml --eei ee-minimal-rhel8