Chapter 9. Creating a collection for distributing roles

Procedure

1. Open VS Code.
2. Navigate to the directory where you want to create your roles collection.
3. Click the Ansible icon in the VS Code activity bar to open the Ansible extension.

4. Select Get started in the Ansible content creator section.

   The Ansible content creator tab opens.

5. In the Create section, click Ansible collection project.

   The Create new Ansible project tab opens.

6. In the form in the Create Ansible project tab, enter the following:

   • Namespace: Enter a name for your namespace, for example company_namespace.
   • Collection: Enter a name for your collection, for example, myapp_network.

   • Init path: Enter the path to the directory where you want to scaffold your new collection.

     If you enter an existing directory name, the scaffolding process overwrites the contents of that directory. The scaffold process only allows you to use an existing directory if you enable the Force option.

     • If you are using the containerized version of Ansible development tools, the destination directory path is relative to the container, not a path in your local system. To discover the current directory name in the container, run the pwd command in a terminal in VS Code. If the current directory in the container is workspaces, enter workspaces/<current_project>/collections.
     • If you are using a locally installed version of Ansible Dev tools, enter the full path to the directory, for example /user/<username>/path/to/<collection_directory>.
7. Click Create.

Procedure

1. If necessary, rename the directory that contains your role to reflect its content, for example, acl_config or tacacs.

   Roles in collections cannot have hyphens in their names. Use the underscore character (_) instead.

2. Copy the roles directories from your standalone role into the roles/ directory in your collection.

   For example, in a collection called myapp_network, add your roles to the myapp_network/roles/ directory.

3. Copy any plug-ins from your standalone roles into the plugins directory/ for your new collection. The collection directory structure resembles the following.

   company_namespace
   └── myapp_network
       ├── ...
       ├── galaxy.yml
       ├── docs
       ├── extensions
       ├── meta
       ├── plugins
       ├── roles
       │   ├── acl_config
       │   │   ├── README.md
       │   │   ├── defaults
       │   │   ├── files
       │   │   ├── handlers
       │   │   ├── meta
       │   │   ├── tasks
       │   │   ├── templates
       │   │   ├── tests
       │   │   └── vars
       │   └── tacacs
       │       ├── README.md
       │       ├── default
       │       ├── files
       │       ├── handlers
       │       ├── meta
       │       ├── tasks
       │       ├── templates
       │       ├── tests
       │       └── vars
       │   ├── run
       ├── ...
       ├── tests
       └── vars

   The run role is a default role directory that is created when you scaffold the collection.

4. Update your playbooks to use the fully qualified collection name (FQDN) for your new roles in your collection.

   Note

   Not every standalone role will seamlessly integrate into your collection without modification of the code. For example, if a third-party standalone role from Galaxy that contains a plug-in uses the module_utils/ directory, then the plug-in itself has import statements.

Procedure

1. To create a new role, copy the default run role directory that was scaffolded when you created the collection.
2. Define the tasks that you want your role to perform in the tasks/main.yml file. If you are creating a role to reuse tasks in an existing playbook, copy the content in the tasks block of your playbook YAML file. Remove the whitespace to the left of the tasks. Use ansible-lint in VS Code to check your YAML code.
3. If your role depends on another role, add the dependency in the meta/main.yml file.

Procedure

1. To add documentation for a role, navigate to the role directory.
2. Open the README.md file in an editor. This file was added in the role directory when you scaffolded your collection directory.

3. Provide the following information in the README.md files for every role in your collection:

   • Role description: A brief summary of what the role does
   • Requirements: List the collections, libraries, and required installations
   • Dependencies

   • Role variables: Provide the following information about the variables your role uses.

     • Description
     • Defaults
     • Example values
     • Required variables

   • Example playbook: Show an example of a playbook that uses your role. Use comments in the playbook to help users understand where to set variables.

     The README.md file in controller_configuration.ad_hoc_command_cancel is an example of a role with standard documentation.

4. To add documentation for your roles collection, navigate to the collection directory.

5. In the README.md file for your collection, provide the following information:

   • Collection description: Describe what the collection does.
   • Requirements: List required collections.
   • List the roles as a component of the collection.
   • Using the collection: Describe how to run the components of the collection.
   • Add a troubleshooting section.
   • Versioning: Describe the release cycle of your collection.

Procedure

1. Create a namespace for your collection in private automation hub. See Creating a namespace in the Managing automation content guide.
2. Optional: Add information to your namespace. See Adding additional information and resources to a namespace in the Managing automation content guide.
3. Upload your roles collections tarballs to your namespace. See Uploading collections to your namespaces in the Managing automation content guide.
4. Approve your collection for internal publication. See Uploading collections to your namespaces in the Managing automation content guide.