Installation and Usage

ansible-creator provides two main functionalities: init and add. The init command allows you to initialize an Ansible project, while add command allows you to add resources to an existing ansible project.

Installation

Recommendation

The recommended approach to install ansible-creator is using the ansible-dev-tools package. Ansible Development Tools aims to streamline the setup and usage of several tools needed in order to create Ansible content. It combines critical Ansible development packages into a unified Python package.

# This also installs ansible-core if it is not already installed
pip3 install ansible-dev-tools

To install ansible-creator, use the following pip command:

pip install ansible-creator

CLI Usage

The Command-Line Interface (CLI) for ansible-creator provides a straightforward and efficient way to interact with the tool. Users can initiate actions, such as initializing Ansible Collections and other Ansible Projects, through concise commands. The CLI is designed for simplicity, allowing users to execute operations with ease and without the need for an extensive understanding of the tool's intricacies. It serves as a flexible and powerful option for users who prefer command-line workflows, enabling them to integrate ansible-creator seamlessly into their development processes.

If command line is not your preferred method, you can also leverage the GUI interface within VS Code's Ansible extension that offers a more visually intuitive experience of ansible-creator. See content creation.

Command line completion

ansible-creator has experimental command line completion for common shells. Please ensure you have the argcomplete package installed and configured.

pip install argcomplete --user
activate-global-python-argcomplete --user

General Usage

Get an overview of available commands and options by running:

ansible-creator --help

Initialize projects

Initialize Ansible collection project

The init collection command enables you to initialize an Ansible collection project. Use the following command template:

ansible-creator init collection <collection-name> <path>

Positional Arguments

Parameter	Description
collection-name	The collection name in the format <namespace>.<name>.
path	The destination directory for the collection project.

Optional Arguments

Short flag	Long flag	Flag argument	Description
-f	--force		Force re-initialize the specified directory as an Ansible collection. This flag is deprecated and will be removed soon. (default: False)
-o	--overwrite		Overwrites existing files or directories. (default: False)
-no	--no-overwrite		Restricts the overwriting operation for files or directories. (default: False)
	--json		Output messages as JSON (default: False)
--la	--log-append	bool	Append to log file. (choices: true, false) (default: true)
--lf	--log-file	file	Log file to write to. (default: ./ansible-creator.log)
--ll	--log-level	level	Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset)
--na	--no-ansi		Disable the use of ANSI codes for terminal color. (default: False)
-h	--help		Show this help message and exit
-v	--verbosity		Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0)

Example

ansible-creator init collection testns.testname $HOME/collections/ansible_collections

This command will scaffold the collection testns.testname at /home/ansible-dev/collections/ansible_collections/testns/testname

Generated Ansible Collection Structure

Running the init collection command generates an Ansible collection project with a comprehensive directory structure. Explore it using:

$ tree -lla /home/ansible-dev/collections/ansible_collections/testns/testname
.
├── CHANGELOG.rst
├── changelogs
│   └── config.yaml
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING
├── .devcontainer
│   ├── devcontainer.json
│   ├── docker
│   │   └── devcontainer.json
│   └── podman
│       └── devcontainer.json
├── devfile.yaml
├── docs
│   ├── docsite
│   │   └── links.yml
│   └── .keep
├── extensions
│   ├── eda
│   │   └── rulebooks
│   │       └── rulebook.yml
│   └── molecule
│       ├── integration_hello_world
│       │   └── molecule.yml
│       └── utils
│           ├── playbooks
│           │   ├── converge.yml
│           │   └── noop.yml
│           └── vars
│               └── vars.yml
├── galaxy.yml
├── .github
│   └── workflows
│       ├── release.yml
│       └── test.yml
├── .isort.cfg
├── LICENSE
├── MAINTAINERS
├── meta
│   └── runtime.yml
├── plugins
│   ├── action
│   │   ├── sample_action.py
│   │   └── __init__.py
│   ├── cache
│   │   └── __init__.py
│   ├── lookup
│   │   ├── sample_lookup.py
│   │   └── __init__.py
│   ├── filter
│   │   ├── sample_filter.py
│   │   └── __init__.py
│   ├── inventory
│   │   └── __init__.py
│   ├── modules
│   │   ├── sample_module.py
│   │   ├── sample_action.py
│   │   └── __init__.py
│   ├── module_utils
│   │   └── __init__.py
│   ├── plugin_utils
│   │   └── __init__.py
│   ├── sub_plugins
│   │   └── __init__.py
│   ├── test
│   │   ├── sample_test.py
│   │   └── __init__.py
├── .pre-commit-config.yaml
├── .prettierignore
├── pyproject.toml
├── README.md
├── roles
│   └── run
│       ├── defaults
│       │   └── main.yml
│       ├── files
│       │   └── .keep
│       ├── handlers
│       │   └── main.yaml
│       ├── meta
│       │   └── main.yml
│       ├── README.md
│       ├── tasks
│       │   └── main.yml
│       ├── templates
│       │   └── .keep
│       ├── tests
│       │   └── inventory
│       ├── vars
│       │   └── main.yml
├── tests
│   ├── .gitignore
│   ├── integration
│   │   ├── __init__.py
│   │   ├── targets
│   │   │   └── hello_world
│   │   │       └── tasks
│   │   │           └── main.yml
│   │   └── test_integration.py
│   └── unit
│       └── .keep
└── .vscode
    └── extensions.json

Note:

The scaffolded collection includes a sample_filter filter plugin, along with a molecule scenario and an integration test target for it, that can be run using pytest. This serves as an example for you to refer when writing tests for your Ansible plugins and can be removed when it is no longer required.

To run the hello_world integration test, follow these steps:

• Git initialize the repository containing the scaffolded collection with git init.
• pip install ansible-dev-tools.
• Invoke pytest from collection root.

Initialize Ansible playbook project

The init playbook command enables you to initialize an Ansible playbook project. Use the following command template:

ansible-creator init playbook <collection-name> <path>

Collection Positional Arguments

Parameter	Description
collection-name	The name for the playbook adjacent collection in the format <namespace>.<name>.
path	The destination directory for the playbook project.

Collection Optional Arguments

Short flag	Long flag	Flag argument	Description
-f	--force		Force re-initialize the specified directory as an Ansible collection. This flag is deprecated and will be removed soon. (default: False)
-o	--overwrite		Overwrites existing files or directories. (default: False)
-no	--no-overwrite		Restricts the overwriting operation for files or directories. (default: False)
	--json		Output messages as JSON (default: False)
--la	--log-append	bool	Append to log file. (choices: true, false) (default: true)
--lf	--log-file	file	Log file to write to. (default: ./ansible-creator.log)
--ll	--log-level	level	Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset)
--na	--no-ansi		Disable the use of ANSI codes for terminal color. (default: False)
-h	--help		Show this help message and exit
-v	--verbosity		Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0)

Example:

ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project

This command will scaffold the new Ansible playbook project at /home/user/ansible-projects/playbook-project.

Generated Ansible playbook project Structure

Running the init playbook command generates an Ansible playbook project with a comprehensive directory structure. Explore it using:

$ tree -la /home/user/ansible-projects/playbook-project
.
├── ansible.cfg
├── ansible-navigator.yml
├── collections
│   ├── ansible_collections
│   │   └── myorg
│   │       └── myproject
│   │           ├── README.md
│   │           └── roles
│   │               └── run
│   │                   ├── README.md
│   │                   └── tasks
│   │                       └── main.yml
│   └── requirements.yml
├── .devcontainer
│   ├── devcontainer.json
│   ├── docker
│   │   └── devcontainer.json
│   └── podman
│       └── devcontainer.json
├── devfile.yaml
├── .github
│   ├── ansible-code-bot.yml
│   └── workflows
│       └── tests.yml
├── inventory
│   ├── group_vars
│   │   ├── all.yml
│   │   └── web_servers.yml
│   ├── hosts.yml
│   └── host_vars
│       ├── server1.yml
│       ├── server2.yml
│       ├── server3.yml
│       ├── switch1.yml
│       └── switch2.yml
├── linux_playbook.yml
├── network_playbook.yml
├── README.md
├── site.yml
└── .vscode
    └── extensions.json

It also comes equipped with Github Action Workflows that use ansible-content-actions for testing and publishing the collection. For details on how to use these, please refer to the following:

• Using the testing workflow
• Using the release workflow

Please ensure that you review any potential TO-DO items in the scaffolded content and make the necessary modifications according to your requirements.

Initialize execution environment project

The init execution_env command enables you to initialize an Ansible execution environment project. Use the following command template:

ansible-creator init execution_env <path>

Example:

ansible-creator init execution_env $HOME/ansible-projects/ee-project

This command will scaffold the new execution environment playbook project at /home/user/ansible-projects/ee-project.

For a comprehensive guide covering all EE configuration options (Galaxy servers, collections, build steps, token security, and more), see the EE Scaffolding Guide.

Generated Ansible execution environment project Structure

Running the init execution_env command generates an Ansible execution environment project with a comprehensive directory structure. Explore it using:

$ tree -la /home/user/ansible-projects/ee-project
.
├── .github
│   └── workflows
│       └── ee-build.yml
├── .gitignore
├── README.md
└── execution-environment.yml

Add resources

The add subcommand allows users to scaffold content types like resources and plugins into an existing project. This feature is designed to streamline the development environment setup by automatically generating the necessary configuration files.

Resources General Usage

Get an overview of available commands and options by running:

ansible-creator add --help

Add Positional Arguments

Parameter	Description
resource	Add resources to an existing Ansible project.
plugin	Add a plugin to an Ansible collection.

Resource Optional Arguments

Short flag	Long flag	Flag argument	Description
-h	--help		Show this help message and exit.

Add resource to an existing project

The add resource command enables you to add a resource to an already existing project. Use the following command template:

ansible-creator add resource <resource-type> <path>

Resource Positional Arguments

Parameter	Description
devcontainer	Add devcontainer files to an existing Ansible project.
devfile	Add a devfile file to an existing Ansible project.
execution-environment	Add a sample execution-environment.yml file to an existing path.
play-argspec	Add playbook argspec examples file to an existing Ansible project.
role	Add a role to an existing Ansible collection.

Example of adding a resource

ansible-creator add resource devcontainer /home/user/..path/to/your/existing_project

This command will scaffold the devcontainer directory at /home/user/..path/to/your/existing_project

Add plugins to an existing ansible collection

The add plugin command enables you to add a plugin to an existing collection project. Use the following command template:

ansible-creator add plugin <plugin-type> <plugin-name> <collection-path>

Plugin Positional Arguments

Parameter	Description
action	Add an action plugin to an existing Ansible Collection.
filter	Add a filter plugin to an existing Ansible Collection.
lookup	Add a lookup plugin to an existing Ansible Collection.
module	Add a generic module to an existing Ansible Collection.
test	Add a test plugin to an existing Ansible Collection.

Example of adding a plugin

ansible-creator add plugin action test_plugin /home/user/..path/to/your/existing_collection

This command will scaffold an action plugin at /home/user/..path/to/your/existing_collection