ansible / ansible-dev-tools

Ansible automation developer tools

Ansible Development Tools (ADT)

The ansible-dev-tools python package provides an easy way to install and discover the best tools available to create and test ansible content.

The curated list of tools installed as part of the Ansible automation developer tools package includes:

ansible-core: Ansible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems.

ansible-builder: Ansible Builder is a tool that automates the process of building execution environments using the schemas and tooling defined in various Ansible Collections and by the user.

ansible-creator: The fastest way to generate all your ansible content!

ansible-lint: Checks playbooks for practices and behavior that could potentially be improved.

ansible-navigator A text-based user interface (TUI) for Ansible.

ansible-sign: Utility for signing and verifying Ansible project directory contents.

molecule: Molecule aids in the development and testing of Ansible content: collections, playbooks and roles

pytest-ansible: A pytest plugin that enables the use of ansible in tests, enables the use of pytest as a collection unit test runner, and exposes molecule scenarios using a pytest fixture.

tox-ansible: The tox-ansible plugin dynamically creates a full matrix of python interpreter and ansible-core version environments for running integration, sanity, and unit for an ansible collection both locally and in a Github action. tox virtual environments are leveraged for collection building, collection installation, dependency installation, and testing.

ansible-dev-environment: A pip-like install for Ansible collections.

Installation

python3 -m pip install ansible-dev-tools

A VsCode compatible devcontainer is also available which is a great way to develop ansible content. The image name is community-ansible-dev-tools.

Usage

In addition to installing each of the above tools, ansible-dev-tools provides an easy way to show the versions of the content creation tools that make up the current development environment.

$ adt --version
ansible-builder                          <version>
ansible-core                             <version>
ansible-creator                          <version>
ansible-dev-environment                  <version>
ansible-dev-tools                        <version>
ansible-lint                             <version>
ansible-navigator                        <version>
ansible-sign                             <version>
molecule                                 <version>
pytest-ansible                           <version>
tox-ansible                              <version>

Developer Notes

The ansible-dev-tools package also offers an Ansible Devtools server which can be launched with adt server. Currently, this server only supports REST APIs for ansible-creator.

Refer to the server code for available endpoints.

Note: This is primarily for backend integrations and is not intended to be an user-facing functionality.

Documentation

For more information, please visit our documentation page.

ansible-dev-tools's Issues

Incorporating Ansible developer tools into ci workflows

Incorporating Ansible developer tools into ci workflows

• Use monolithic GHA to check PRs
• Run unit and sanity tests plus lint
• Publishing collections to Galaxy

ansible-community + collections missing from pipx install

When I use pipx to install ansible-dev-tools like this:

sudo pipx install --include-deps --global ansible-dev-tools

I get everything except the site package ansible-collections is missing. This is demonstrated by:

pab-laptop[107]$ ansible-galaxy collection list
usage: ansible-galaxy [-h] [--version] [-v] TYPE ...

Perform various Role and Collection related operations.

positional arguments:
  TYPE
    collection   Manage an Ansible Galaxy collection.
    role         Manage an Ansible Galaxy role.

options:
  --version      show program's version number, config file location, configured module search path, module location,
                 executable location and exit
  -h, --help     show this help message and exit
  -v, --verbose  Causes Ansible to print more debug messages. Adding multiple -v will increase the verbosity, the
                 builtin plugins currently evaluate up to -vvvvvv. A reasonable level to start is -vvv, connection
                 debugging might require -vvvv. This argument may be specified multiple times.
ERROR! - None of the provided paths were usable. Please specify a valid path with --collections-path

If I then do:

sudo pipx uninstall --global ansible-dev-tools
sudo pipx install --include-deps --global ansible

then I get:

pab-laptop[111]$ ansible-galaxy collection list

# /opt/pipx/venvs/ansible/lib/python3.10/site-packages/ansible_collections
Collection                               Version
---------------------------------------- -------
amazon.aws                               8.0.1  
ansible.netcommon                        6.1.3  
ansible.posix                            1.5.4  
ansible.utils                            4.1.0  
ansible.windows                          2.4.0  
...

Looking at the differences it appears that installing ansible includes the app ansible-community, which is not present when installing ansible-dev-tools.

installed package ansible 10.1.0, installed using Python 3.10.12
  These apps are now globally available
    - ansible
    - ansible-community    <===
    - ansible-config
    - ansible-connection
    - ansible-console
    - ansible-doc
    - ansible-galaxy
    - ansible-inventory
    - ansible-playbook
    - ansible-pull
    - ansible-test
    - ansible-vault
done!

vs:

installed package ansible-dev-tools 24.6.1, installed using Python 3.10.12
  These apps are now globally available
    - ade
    - adt
    - ansible
    - ansible-builder
    - ansible-config
    - ansible-connection
    - ansible-console
    - ansible-creator
    - ansible-doc
    - ansible-galaxy
    - ansible-inventory
...

I'm currently working around this by installing both, but replacing the global links so that anything in ansible comes from there rather than from ansible-dev-tools.

Ansible developers tools (ansible-dev-tools) Docs

Tasks

Beta Give feedback

1. Introduction
2. Home page
3. Installation
4. Contributor Guide
5. User Guide

Moved to user guide

• Getting Started
• Creating collections of automation content
• Testing roles
• Using content best practices for reliable, consistent automation
• Incorporating Ansible developer tools into ci workflows

RFE: Add a named volume for image storage for docker

https://github.com/ansible/community-ansible-dev-tools-image/blob/b7bcf9cba923d400d913114a1b25ce3069d47c60/.devcontainer/podman/devcontainer.json#L19

The initial implmentation only covered podman

Home Page

Ansible Developer Tools (brief - this is the documentation home page)

• (highlight) Single point for installation
• (highlight) Combination of tools vetted and used by previous content authors
• (highlight) The SDK reflects the tools used by certified and validated content developers
• (highlight) Introduces tools that a developer may be less familiar with
• (tools - what and how they are used together and for what purpose)
• (author) 1-2 paragraphs for each tool highlighting key functionality, can probably be harvested from existing READMEs and dos.
• Identify how each tool is valuable during local interactive development, local testing. and then in a CI pipeline (linting and testing)
• (highlight) Same tools and outcomes locally and in CI
• (note) include the extension in the enumeration of the tools. Although it is not packaged with the python of rpm pkg, it is an integral part of the experience

pipx support

Hello! I use Python with pyenv, so that I can switch among versions when necessary, this means that my pip installs are not "permanent" and as such, if I install ansible-dev-tools with pip I'll need to jump around versions or duplicate installs.

If I try using pipx with pipx install ansible-dev-tools, adt becomes available but not ansible-lint and its friends.

Support for pipx would be great to isolate the tool from the installation itself.

Contributor Guide

Contributor Guide

• Code of conduct and general how to contribute to the project.
• Communications channels (matrix, forum, meetings etc)
• Developer/ PR guidelines (if needed)

Name change `ansible-dev-tools`

The CLI will change to adt

Referred to formally as Ansible automation developer tools

Delete the 1.0.0 release and tag, leaving that for January

Releases before then should < 1.0.0

Support specifying specific ansible version

I really love the path this repo is taking things. One requirement that I deal with in our Ansible environment is needing to develop for specific versions of ansible. It would be great if we could install ansible-dev-tools (and better yet just have the devcontainers built) targeting a specific ansible-core version. I would think only major versions are needed for my use case but being able to target minor would be useful as well.

User Guide Docs

User Guide will have two sections:

• links to tool docs etc. Link to the ecosystem docs and each repo
• Common operations using 2 or more tools (cross tools)

Cross tool Common operations are described in the task list.

Tasks

Beta Give feedback

1. Building a new collection
2. Testing a user-facing role within a collection
3. Ensuring content best practices
4. Set up CI
5. Publishing a collection

BUG: Using this image as an EE docs lead to ansible-builder failure for dnf path

Team,

The docs suggest creating an execution-environment.yml with the following:

---
version: 3

images:
  base_image:
    name: ghcr.io/ansible/community-ansible-dev-tools:latest

dependencies:
  galaxy: requirements.yml
  python: requirements.txt

However, this looks to create the following error during the build where ansible-builder is expecting to find /usr/bin/dnf, but it appears the image is using /usr/bin/microdnf instead:

3.069 /output/scripts/assemble: line 163: /usr/bin/dnf: No such file or directory
------
Dockerfile:57
--------------------
  55 |     COPY _build/requirements.txt requirements.txt
  56 |     RUN $PYCMD /output/scripts/introspect.py introspect --user-pip=requirements.txt --write-bindep=/tmp/src/bindep.txt --write-pip=/tmp/src/requirements.txt
  57 | >>> RUN /output/scripts/assemble
  58 |
  59 |     # Final build stage
--------------------
ERROR: failed to solve: process "/bin/sh -c /output/scripts/assemble" did not complete successfully: exit code: 127

Adding the following to the execution-environment.yml resolves it:

options:
  package_manager_path: /usr/bin/microdnf

[RFE] Provide a way to identify if individual packages are installed or not

Add a command line option to check if the packages that part of CDK are installed or not and provide a way to identify which packages are not installed.

oc command does not work in a FIPS enabled cluster

When running any oc command, the follow error is generated:
FIPS mode is enabled, but the required OpenSSL backend is unavailable.

Set versioning to CalVer

Before we get too far along here, let's swith this one to calver instead of semantic.

Introduction / README

Ansible developers tools (ansible-dev-tools) is an opinionated collection of tools that enable automation developers to create and test Ansible automation quickly and effectively. To clearly communicate what tools are available and support these objectives, the tools that makeup the ansible-dev-tools should be easy to install with one command.

The tools in the initial release of the ansible-dev-tools will be:

• ansible-lint (Ansible lint)
• molecule (Ansible Molecule)
• ansible-navigator (automation content navigator)
• pytest-ansible plugin
• tox-ansible plugin
• ade (Ansible development environment formerly pip4a)
• ansible-builder (execution environment builder)**
• ansible-sign
• ansible-creator (Ansible creator)
• Documentation to include the extension, even though it is not co-packaged

Getting started with Ansible Developer Tools

Getting started with Ansible Developer Tools

• Walk through the creation and release of a simple collection

Ensuring content best practices

This will live in the User Guide page.

Ensuring content best practices
Add a “regular” tox entry for lint, and use tox to run it, run sanity tests using tox-ansible

Please sort list of tools

ansible-dev-tools/docs/index.md

Line 27 in 4ef2e1e

- [ansible-core](https://github.com/ansible/ansible): Ansible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems.

RFE Add ansible-rule-book to ADT

#264

ansible-dev-environment missing in README

The Usage of ADT in README is not showing ansible-dev-environment in the list. This needs to be updated https://github.com/ansible/ansible-dev-tools#usage

RFE: Add ansible-rulebook

➜  /workdir ansible
ANSIBLE_DEV_TOOLS_CONTAINER  ansible-connection           ansible-galaxy               ansible-playbook             ansible-test
ansible                      ansible-console              ansible-inventory            ansible-pull                 ansible-vault
ansible-builder              ansible-creator              ansible-lint                 ansible-runner
ansible-config               ansible-doc                  ansible-navigator            ansible-sign

RFE: Change non-root user to user

For podman, the user is set to root, for docker it is set to podman. Which menas podman never uses the podman user :)

It might make more sense for the non-root user to just be "user"

Install docs are incorrect currently

The docs for ansible-dev-tools appears temporarily incorrect since there's not a release on pypi marked stable, the command pip install ansible-dev-tools fails, but pip install ansible-dev-tools==0.2.0a0 is successful.

Set up CI

This will live in the User Guide page.

Set up CI
Use the monolithic github action as a PR gate to set up a repo for running unit, sanity, lint

Creating collections of automation content

Creating collections of automation content

• Scaffold with creator
• ade (pip4a) to install it editable with python deps in a venv
• Lint
• Navigator

Bootstrap a new collection

This will live in the User Guide page.
Bootstrap a new collection
Use of creator to scaffold, ade (pip4a) to install it editable with python deps in a venv, use the extension with lint to author, playbook or navigator to run

Using content best practices for reliable, consistent automation

Using content best practices for reliable, consistent automation

• Add tox entry for lint
• Run sanity tests with tox-ansible

Testing a user-facing role within a collection

This will live in the User Guide page.

Testing a user-facing role within a collection
Use molecule to write a test, wrap molecule with pytest-ansible parameterization, use tox-ansible to run the scenario across all current python/ansible core versions

Installation page missing Creator

Creator tool is missing in the Installation page https://ansible.readthedocs.io/projects/dev-tools/installation/#usage-design-review.
Missing in the Included packages list https://ansible.readthedocs.io/projects/dev-tools/#included-packages

Testing roles

Testing roles

• Molecule
• wrap molecule with pytest-ansible parameterization
• tox-ansible to run the scenario across all current python/ansible core versions

Installation Guide

Installation

• Install, uninstall
• Upgrade - porting guide/changelogs (Github generated/ point to releases)

Build initial project and dependencies

Lay down the framework for a new python project

Deps:

ansible-lint
ansible-navigator
molecule
ansible-builder
pytest-ansible
tox-ansible
scaffolding tool (future)

Publishing a collection

This will live in the User Guide page.

Publishing a collection
Use the monolithic github action to push to galaxy, mention AH token refresh and how to set that up.

Update Ansible development tools documentation

This documentation article refers to "Ansible development tools" as "ADT" which is not approved under Red Hat brand guidelines.

Only "Ansible development tools" is allowed (see row 156 in this spreadsheet: https://docs.google.com/spreadsheets/d/1DLS_lS3VKidgZIvcLmLp9BoiqptkvqHWfe1D5FD2kfk/edit#gid=1375785039)

Please remove the use of ADT through this doc.

thanks!