AnsibleByExample

Creating Ansible Collection Using ansible-creator and VS Code Ansible Extension

BeginnerautomationAnsibleansible-creatorIT automation
2024-01-015By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Introduction

Ansible Collections are the standard way to package and distribute Ansible content — modules, roles, plugins, and playbooks — as reusable units. The ansible-creator tool (part of the Ansible Development Tools) scaffolds a complete collection structure with all the required files, saving you from creating the directory tree manually.

This guide covers both the CLI and VS Code GUI approaches to creating collections.

Prerequisites

Install ansible-creator

pip install ansible-creator

Verify installation:

ansible-creator --version

Install VS Code Ansible Extension (Optional)

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "Ansible" by Red Hat
  4. Click Install

The extension includes ansible-creator integration with a graphical interface.

Method 1: CLI with ansible-creator

Initialize a New Collection

ansible-creator init collection myorg.myapp --init-path ./collections

This creates the full collection structure:

collections/myorg/myapp/
├── CHANGELOG.rst
├── changelogs/
│   └── config.yaml
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── filter/
│   ├── inventory/
│   ├── lookup/
│   ├── module_utils/
│   └── modules/
├── README.md
├── roles/
├── tests/
│   ├── integration/
│   └── unit/
└── playbooks/

CLI Options

OptionDescription
--init-pathDirectory to create the collection in
--forceOverwrite existing collection (re-scaffold)
--verbosityOutput detail level (0-3)
--log-fileWrite output to a log file

Example with All Options

ansible-creator init collection myorg.network_utils \
  --init-path ~/projects/collections \
  --verbosity 2 \
  --log-file /tmp/collection-init.log

Method 2: VS Code GUI

Step 1: Open the Ansible Creator

  1. Open VS Code and click the Ansible icon in the Activity Bar
  2. Click "Get Started" in the Ansible Creator section
  3. The System Requirements box shows the status of ansible, Python, and ansible-creator

VS Code Ansible Content Creator

Ensure all requirements display green ticks before proceeding.

Step 2: Fill the Interactive Form

  1. Click "Initialize a collection"
  2. Enter the namespace (e.g., myorg)
  3. Enter the collection name (e.g., myapp)
  4. Select the initialization path using the folder icon
  5. Set verbosity level
  6. Optionally enable "Log output to a file"
  7. Check "Force" to re-scaffold an existing collection
  8. Click "Create"

VS Code Ansible Content Creator Form

Step 3: Open and Develop

  1. Click "Open Collection" to add it to your workspace
  2. The galaxy.yml file opens automatically
  3. Start developing your collection content

VS Code Ansible Content Creator Result

The VS Code extension provides syntax highlighting, auto-completion, linting, and go-to-definition for your collection code.

Understanding galaxy.yml

The galaxy.yml file is your collection's metadata:

namespace: myorg
name: myapp
version: 1.0.0
readme: README.md
authors:
  - Your Name <your.email@example.com>
description: A collection for managing myapp deployments
license:
  - GPL-3.0-or-later
license_file: ''
tags:
  - deployment
  - myapp
  - automation
dependencies:
  ansible.utils: ">=2.0.0"
repository: https://github.com/myorg/ansible-collection-myapp
documentation: https://docs.example.com/myorg/myapp
homepage: https://example.com/myapp
issues: https://github.com/myorg/ansible-collection-myapp/issues
build_ignore:
  - .gitignore
  - changelogs/.plugin-cache.yaml

Adding Content to Your Collection

Custom Module

Create plugins/modules/deploy.py:

#!/usr/bin/python
from ansible.module_utils.basic import AnsibleModule

DOCUMENTATION = r'''
---
module: deploy
short_description: Deploy application to target host
description:
  - Manages application deployment with version control
options:
  version:
    description: Application version to deploy
    type: str
    required: true
  path:
    description: Deployment target path
    type: str
    default: /opt/myapp
author:
  - Your Name (@yourname)
'''

EXAMPLES = r'''
- name: Deploy v2.1.0
  myorg.myapp.deploy:
    version: "2.1.0"
    path: /opt/myapp
'''

def main():
    module = AnsibleModule(
        argument_spec=dict(
            version=dict(type='str', required=True),
            path=dict(type='str', default='/opt/myapp'),
        ),
    )
    # Module logic here
    module.exit_json(changed=True, msg=f"Deployed version {module.params['version']}")

if __name__ == '__main__':
    main()

Custom Role

cd collections/myorg/myapp/roles
ansible-galaxy role init webserver

Custom Filter Plugin

Create plugins/filter/utils.py:

class FilterModule:
    def filters(self):
        return {
            'to_app_config': self.to_app_config,
        }

    def to_app_config(self, data, env='production'):
        return {
            'environment': env,
            'settings': data,
            'generated': True,
        }

Usage in playbooks:

- name: Generate config
  ansible.builtin.debug:
    msg: "{{ my_settings | myorg.myapp.to_app_config('staging') }}"

Testing Your Collection

Unit Tests

cd collections/myorg/myapp
python -m pytest tests/unit/ -v

Integration Tests

ansible-test integration --docker default

Sanity Tests

ansible-test sanity --docker default

Building and Publishing

Build the Collection

cd collections/myorg/myapp
ansible-galaxy collection build

This creates myorg-myapp-1.0.0.tar.gz.

Install Locally

ansible-galaxy collection install myorg-myapp-1.0.0.tar.gz

Publish to Ansible Galaxy

ansible-galaxy collection publish myorg-myapp-1.0.0.tar.gz --api-key YOUR_API_KEY

Publish to Private Automation Hub

ansible-galaxy collection publish myorg-myapp-1.0.0.tar.gz \
  --server https://hub.example.com/api/galaxy/content/published/ \
  --api-key YOUR_TOKEN

Using Collections in Playbooks

Install from Galaxy

ansible-galaxy collection install myorg.myapp

Requirements File

# requirements.yml
collections:
  - name: myorg.myapp
    version: ">=1.0.0"
  - name: ansible.windows
  - name: community.general

ansible-galaxy collection install -r requirements.yml

Use in Playbooks

- name: Deploy with custom collection
  hosts: web_servers
  collections:
    - myorg.myapp
  tasks:
    - name: Deploy application
      deploy:
        version: "2.1.0"

Or use the FQCN (recommended):

- name: Deploy application
  myorg.myapp.deploy:
    version: "2.1.0"

Conclusion

The ansible-creator tool eliminates the tedious manual setup of collection directory structures. Whether you prefer the CLI for scripted workflows or the VS Code GUI for interactive development, the result is a properly scaffolded collection ready for custom modules, roles, plugins, and testing. Once built, publish to Ansible Galaxy or a private Automation Hub to share your collection with your team or the community.

All Tutorials