Lab Guide: Creating a Collection with the VS Code Extension

A guide to using the Ansible extension for Visual Studio Code to scaffold a new Ansible collection and playbook project.

Lab briefing

ansible-creator is a Command-Line Interface (CLI) tool designed for effortlessly scaffolding all your Ansible content. Whether you are initializing an Ansible collection or creating the framework for specific plugins, this tool streamlines the process with efficiency and precision based on your requirements.

ansible-creator is also integrated into the VS Code user interface through the Ansible extension for VS Code for even a smoother experience when developing content.

In this exercise, you will create an Ansible collection and a playbook using the Ansible extension’s wizard in VS Code.

Learning objectives

After completing this module, you will be able to:

Scaffold a new Ansible collection using the ansible-creator CLI
Use the Ansible VS Code extension to create collection and playbook projects
Compare CLI-generated and VS Code-generated collection structures

VS Code editor inside the lab environment

Lab guide: Hands-on tasks

In this exercise you will learn how to create, test, and deploy an Ansible collection using the ansible-creator tool through the Ansible extension for VS Code.

For this lab, all necessary tools and dependencies are pre-installed and configured for you.

Task 0: Create a collection using the ansible-creator CLI

Lets start by running ansible-creator in the command line to scaffold a collection, with the directory structure and several file templates to speed up our content development. In the following tasks we will do the same using the Ansible extension in VS Code.

Open the VS Code Terminal by clicking the Terminal on the top VS Code menu, then New Terminal option. If you already have a Terminal open in VS Code you can reuse that one.
Scaffold a CLI collection with ansible-creator: Using ansible-creator initialize a collection called mynamespace.my_cli_collection in the /home/rhel/myansibleproject/collections/ansible_collections directory:
```
ansible-creator init collection mynamespace.my_cli_collection /home/rhel/myansibleproject/collections/ansible_collections
```
Inspect the generated collection structure and files:
```
ls -lha /home/rhel/myansibleproject/collections/ansible_collections/mynamespace/my_cli_collection
```
You should see the scaffolded collection directory structure including files like galaxy.yml, README.md, LICENSE, and directories like plugins/, tests/, and meta/.
Congrats: You created a default collection. Move to the next tasks to see how to do this in VS Code and how to customize it.

Task 1: Explore the Ansible extension

First, let’s explore the Ansible extension for VS Code.

Check the installed extensions section in VS Code, look for the Ansible extension and click the blue Reload Window button to update to the latest version if you didn’t do it in the previous step.
After the window reloads, locate and open the Ansible extension icon on the sidebar of VS Code and click on it. You will see the Ansible sidebar with 3 sections: (1) Ansible Development Tools, (2) Ansible Lightspeed, and (3) Ansible Lightspeed Feedback.
Collapse the Lightspeed sections to simplify the view, as we won’t be using Lightspeed features for this lab.

Task 2: Create a collection project

Next, you will scaffold a new Ansible collection.

Open the Collection project creator by clicking the Collection project link in the Ansible Development Tools section.

Fill out the collection details in the new tab that opens. Use the following information:

Namespace:
```
mynamespace
```
Collection:
```
mycollection
```

Init path:

/home/rhel/myansibleproject/collections/ansible_collections/mynamespace/mycollection

Check the box for Install collection from source code (editable mode)
Create the collection by clicking the blue Create button.

After a few moments, you should see the creation details appear in the Logs box.

------- ansible-creator logs ---------
    Note: collection project created at /home/rhel/myansibleproject/collections/
          ansible_collections/mynamespace/mycollection


------- ansible-dev-environment logs -------
Note: Created virtual environment: /home/rhel/myansibleproject/collections/ansible_collections/mynamespace/mycollection/.venv
Note: Installed collections include: ansible.utils and mynamespace.mycollection
Note: All python requirements are installed.
Note: All required system packages are installed.
Note: A virtual environment was specified but has not been activated.
Note: Please activate the virtual environment:
source /home/rhel/myansibleproject/collections/ansible_collections/mynamespace/mycollection/.venv/bin/activate

Task 3: Create a playbook project

Now, you will create a separate playbook project.

Open the Playbook project creator by clicking the Playbook project link in the Ansible extension sidebar.
Fill out the playbook project details in the new tab. Use the following information:
- Destination directory:
  /home/rhel/myansibleproject
- Namespace:
  mynamespace
- Collection:
  mysecondcollection
Create the project by clicking the Create button. After a couple of seconds, you should see a success message in the logs.
```
--- ansible-creator logs ---
Note: playbook project created at /home/rhel/myansibleproject
```

Task 4: Open the mycollection folder

Due to a lab infrastructure and VS Code limitation, you will now manually open the folder where your new collection content was created.

Open the file Explorer by clicking the Explorer icon (the icon with two files) in the VS Code left sidebar.
Open the collection folder by clicking the (1) Open Folder button. In the path field, paste the following path (2) and click the blue OK button (3).
```
/home/rhel/myansibleproject/collections/ansible_collections/mynamespace/mycollection/
```
View the scaffolded files once the VS Code screen reloads. You will see the complete directory structure and all the files created by the Ansible extension for your new collection in the left sidebar.

Task 5: Compare the CLI-generated with the VS Code–generated collections

Same layout
Same defaults
Same metadata files

Next steps

You have successfully explored how ansible-creator and VS Code work together to scaffold a collection. Please click the Next button below to proceed to the next module.