AnsibleByExample

Mastering Ansible-Creator: Scaffold Collections and Roles Fast

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-creator is the official scaffolding tool for Ansible content — it generates the directory structure, boilerplate files, and configuration for new collections, roles, and plugins. Instead of manually creating dozens of files and directories, one command gives you a properly structured project ready for development.

Installation

# Install via pip
pip3 install ansible-creator

# Verify
ansible-creator --version
ansible-creator --help

# Installs ansible-creator + ansible-lint + molecule + ansible-navigator
pip3 install ansible-dev-tools

Create a New Collection

Basic Initialization

ansible-creator init collection my_namespace.my_collection

This generates:

my_namespace/my_collection/
├── CHANGELOG.rst
├── README.md
├── galaxy.yml
├── docs/
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   ├── module_utils/
│   ├── action/
│   ├── filter/
│   ├── inventory/
│   ├── lookup/
│   └── README.md
├── roles/
├── tests/
│   ├── integration/
│   ├── unit/
│   └── sanity/
│       └── ignore-2.17.txt
├── playbooks/
└── extensions/

With Custom Output Path

ansible-creator init collection my_namespace.my_collection \
  --init-path ~/projects/ansible-collections/

Force Reinitialize

ansible-creator init collection my_namespace.my_collection --force

Create a Role

ansible-creator init role my_role

Generates standard role structure:

my_role/
├── README.md
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/
    └── main.yml

Role Inside a Collection

cd my_namespace/my_collection/
ansible-creator init role roles/my_role

Add Plugins to Existing Collection

Add a Module

ansible-creator add plugin module --name my_module \
  --path my_namespace/my_collection/

Add a Filter Plugin

ansible-creator add plugin filter --name my_filter \
  --path my_namespace/my_collection/

Add a Lookup Plugin

ansible-creator add plugin lookup --name my_lookup \
  --path my_namespace/my_collection/

Command Reference

CommandDescription
init collection <namespace.name>Create new collection
init role <name>Create new role
add plugin moduleAdd module to collection
add plugin filterAdd filter plugin
add plugin lookupAdd lookup plugin
add plugin actionAdd action plugin

Global Options

OptionDescription
--init-path <dir>Output directory
--forceOverwrite existing files
--no-ansiDisable colored output
--log-file <file>Write logs to file
--log-level <level>Set log verbosity
--jsonOutput in JSON format
-vIncrease verbosity

Visual Studio Code Integration

The Ansible extension for VS Code includes ansible-creator integration:

Visual Studio Code Ansible Content Creator

VS Code Command Palette

  1. Open VS Code
  2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
  3. Type "Ansible: Init" to see available scaffolding commands:
    • Ansible: Init Collection — Create new collection
    • Ansible: Init Role — Create new role

Install the Extension

code --install-extension redhat.ansible

The extension provides:

  • Scaffolding via command palette
  • Autocomplete for galaxy.yml, meta/main.yml
  • Syntax highlighting for all Ansible files
  • Built-in linting with ansible-lint

Collection Development Workflow

1. Scaffold

ansible-creator init collection myorg.myapp
cd myorg/myapp

2. Configure galaxy.yml

namespace: myorg
name: myapp
version: 1.0.0
readme: README.md
authors:
  - Your Name <you@example.com>
description: My custom Ansible collection
license:
  - GPL-3.0-or-later
repository: https://github.com/myorg/ansible-collection-myapp
dependencies:
  ansible.builtin: ">=2.16"

3. Add a Module

ansible-creator add plugin module --name configure_app

Edit plugins/modules/configure_app.py:

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

DOCUMENTATION = r'''
---
module: configure_app
short_description: Configure myapp settings
description:
  - Manages configuration for myapp
options:
  config_path:
    description: Path to configuration file
    type: str
    required: true
  settings:
    description: Settings to apply
    type: dict
    required: true
'''

def main():
    module = AnsibleModule(
        argument_spec=dict(
            config_path=dict(type='str', required=True),
            settings=dict(type='dict', required=True),
        )
    )
    # Module logic here
    module.exit_json(changed=True, msg="Configuration applied")

if __name__ == '__main__':
    main()

4. Test

# Sanity tests
ansible-test sanity --docker

# Unit tests
ansible-test units --docker

# Integration tests
ansible-test integration --docker

5. Build and Publish

# Build collection archive
ansible-galaxy collection build

# Publish to Galaxy
ansible-galaxy collection publish myorg-myapp-1.0.0.tar.gz --api-key YOUR_KEY

CI/CD Integration

GitHub Actions

name: Collection CI
on: [push, pull_request]
jobs:
  sanity:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install ansible-core ansible-lint
      - run: ansible-lint
      - run: ansible-test sanity --docker

Conclusion

ansible-creator eliminates the tedious boilerplate of setting up Ansible collections and roles. Use init collection for new collections, init role for standalone roles, and add plugin to scaffold modules and plugins with proper documentation templates. Combined with VS Code's Ansible extension, you get a complete development environment — scaffold, write, lint, test, and publish all from one workflow. Start every new Ansible project with ansible-creator to get the structure right from day one.

All Tutorials