Skip to content

Collection Development

Prerequisites

Create New Collection

Create new repository with minimal ansible environment 

git clone https://github.com/{USER}/{REPO} /var/git/{REPO}
cd ~/git/{REPO}

Update Ansible Environment

A minimal (clean) environment is provided to test collection and roles against a vanilla ansible installation - enforcing only settings which make testing easier.

ansible.env (1)

  1. 0644 {USER}:{USER}
###############################################################################
# Ansible Collection Test Environment Configuration
###############################################################################
# Change environment variable names based on collection name to prevent
# collisions.

# Ansible serving/caching directory for controller node (high read/writes).
export SRV_DEPLOY="${HOME}/.ansible"  # ${ANSIBLE_HOME}

# Ansible python virtual environment (high read/writes)
export SRV_VENV='/var/venv/{REPO}'

# SRV git repository root directory (high read only)
export SRV_GIT='/var/git/{REPO}'

###############################################################################
# Ansible Serve Config (2.18.1)
###############################################################################
# All configuration is done using environment variable per best practice. Check
# both core and community options when setting or changing values.
#
# Generated with:
#
#   ansible-config init -t all -f env > /tmp/ansible-env.cfg
#
# Environment options are:
# * Explicitly set
# * Not internal-only settings
# * Deprecated settings actively removed or noted with a TODO if in use
# * Use sh interpretation (0: False, 1: True; etc)
#
# Settings can be validated with (errors will be listed):
#
#   source ansible.env
#   source /run/venv/{REPO}/bin/activate
#   ansible-config --help
#   ansible-config dump -t all --only-changed

###############################################################################
# Ansible (Core) Common Options
###############################################################################
# Environment variables for core ansible release.
#
# Do not use 'ansible' user (as containers do not have this setup); also do not
# use custom SSH options as these are not used for podman.
#
# Reference:
# * https://docs.ansible.com/ansible/latest/reference_appendices/config.html

export ANSIBLE_CONFIG=''  # Do not use config files.
export ANSIBLE_DISPLAY_SKIPPED_HOSTS=0  # Do not display skipped hosts.
export ANSIBLE_DUPLICATE_YAML_DICT_KEY='error'  # Explicit duplicate errors.
export ANSIBLE_STDOUT_CALLBACK='debug'  # ansible-doc -t callback -l.
export ANSIBLE_USE_PERSISTENT_CONNECTIONS=1  # Persist SSH connections.

###############################################################################
# Ansible (Collection) Environment Options
###############################################################################
# Environment variables for non-core ansible collections.
#
# Reference:
# * https://docs.ansible.com/ansible/latest/collections/environment_variables.html#list-of-collection-env-vars

export ANSIBLE_ADMIN_USERS='root'  # Only enable root by default.
export ANSIBLE_PARAMIKO_RECORD_HOST_KEYS=0  # Ignore host keys.
export ANSIBLE_REMOTE_TMP='/tmp'  # Use RAMFS tmp, not (~/.ansible/tmp).
export ANSIBLE_SYSTEM_TMPDIRS='/tmp'  # Use RAMFS tmp, not (/var/tmp).

###############################################################################
# Activate Ansible Virtual Environment
###############################################################################
source "${SRV_VENV}/bin/activate"

One-time initialization

Initialization requires the FQCN, however the repository is typically flat. Create the skeleton template and move to repository base.

cd ~/git/{REPO}
source ansible.env
ansible-galaxy collection init --init-path . r_pufky.{COLLECTION}
mv -vn r_pufky/{COLLECTION}/* .
rm -rfv r_pufky
mkdir -p plugins/modules  #  Optional for Python modules.

Tip

Alternatively copy an existing collection and remove unused options. Be sure to update all remaining files.

Reference:

Enable Submodule Summaries and Out of Date Checks

Check out of date/uncommitted submodules on push to provide a better summary of submodule status (stored in .git/config).

Enable submodule summary on main repo commits/status. 

git config status.submodulesummary 1

Check for submodules out of date/uncommitted when pushing main repo. 

git config push.recurseSubmodules check

Reference: