NOTE: This role needs work, it doesn't currently upgrade PyPI packages that have been installed using pipx and pipx is now the default install method so, for now, running rm -rf ~/.local/pipx/venvs/ansible before running this role is the best way to use it.
This repo contains an Ansible role designed to be run by a non-root user against a localhost running Debian Trixie, Debian Bookworm, Debian Bullseye, Ubuntu Noble or Ubuntu Jammy using the systems .deb installed version of Ansible in order to install or upgrade Ansible, Ansible Lint, Molecule and other Python Package Index (PyPI) packages using pipx.
This role is tested using GitLab CI on Debian Trixie, Debian Bookworm and Ubuntu Jammy.
Debian Bullseye only supports Ansible 8.7.0 as Ansible >=9.0.0 requires Python >=3.10.
See the defaults/main.yml file for the default variables, the vars/main.yml file for the preset variables and the meta/argument_specs.yml file for the variable specification.
Set the ans variable to true for the tasks in this role to be run, it defaults to false.
A optional list of Ansible collections, URLS and versions.
Each item in the list requires a name, for the name of the collection, a url, for the GitHub repo URL of the collection and a version, the version can be a version number or latest, for example:
ans_cols:
- name: community.general
url: https://github.com/ansible-collections/ansible.posix
version: latestNote that the url of the GitHub project is appended with /releases/latest to get the URL of the latest release, for example for community.general this is the latest version, see the GitHub releases page for all the versions available..
The ans_downgrade variable defaults to false, if it is set to true then this role will install older versions of PyPi packages Ansible Galaxy Collections even when newer system versions are present.
The ans_distro_check variable defaults to true, if it is set to false then this role will still run when ansible_facts.distribution is not Debian or Ubuntu and ansible_facts.distribution_release is not bullseye, bookworm or jammy, by default it won't as these are the only distros that have beed used for development and testing.
A boolean, force the use of ansible.builtin.command rather than community.general.pipx, this is sometime needed on older servers, ans_pipx_cmd defaults to false.
A list of dictionaries of Linux distros and the packages that should be present and absent for each distro.
If this role is run usidng sudo or as root these packages will be automatically installed, when it is run as a non-root user this role will fail if these packages are not present.
A list of Python Package Index (PyPI), package names, URLs and versions that will be installed as user packages if they are not already available as system packages, either using pip or pipx if the distro is Debian Bookworm.
Each item in the list requires a name for the name of the PyPI package, when the state is not set to absent a url for the URL of the project on the PyPI website and a version is also required, when pipx (rather than pip) is used the optional venv variable is used set fo the name of the existing virtual environment that package should be injected into, the version can be a version number or latest, the extras list and state are optional, in addition the optional type attribute is used for pipx, when it is not set app is assumed, the other option being lib for packages that don't provide applications, for example:
ans_pypi_pkgs:
- name: ansible
url: https://pypi.org/pypi/ansible
version: 7.3.0
- name: ansible-lint
url: https://pypi.org/pypi/ansible-lint
venv: ansible
version: latest
- name: jinja2-ansible-filters
type: lib
url: https://pypi.org/pypi/jinja2-ansible-filters
venv: ansible
version: "1.3.2"
- name: molecule-plugins
extras:
- docker
- podman
state: forcereinstall
url: https://pypi.org/pypi/molecule-plugins
venv: ansible
version: 23.0.0Only absent, present (the default) and forcereinstall are supported for state, use state: present and version: latest for the latest version, forcereinstall is necessary if the list of extras is changed, see the Installing "Extras" documentation.
When the state is not absent the url and version are required, when the state is absent only the name is required.
Note that the url is used to download a JSON file that lists all the versions of the package that are available, the URL for the JSON file is the url appended with /json, the URL without /json redirects to the project page, for example https://pypi.org/pypi/ansible-core redirects to https://pypi.org/project/ansible-core/.
An optional path for the non-root users bin directory, ans_user_bin defaults to {{ ansible_facts.env.HOME }}/.local/bin.
The role is designed to be run using the /usr/bin/ansible-playbook that is installed by the Debian or Ubuntu ansible package, the suggested method for doing this is via the localhost repo which contains a ansible.sh script that will download this role and run it, for example:
git clone https://git.coop/webarch/localhost.git
cd localhost
./ansible.sh --check # check what will be done
./ansible.sh --verbose # verbose install / updateWhen this role is run by a non-root user, it will symlink Ansible from ~/.local/bin, if ~/.local/bin is not found in the $PATH environmental variable and if the users $SHELL environmental variable ends in bash and ~/.bash_profile doesn't exist then one will be created (but it won't be touched if it already exists), see the files/bash_profile.sh file for it's content.
To manually update the $PATH add the following to your ~/.bash_profile or whichever file sets your $PATH environmental variable when you login:
PATH="${HOME}/.local/bin:${PATH}"
export PATH="${PATH}"After updating or creating a file containing your $PATH environmental variable you will need to either exit the shell and login again / reopen it or run source ~/.bash_profile, (replace ~/bash_profile which which ever path contains the settings).
When running ansible-lint there is a warning like this:
WARNING: PATH altered to include ~/.local/pipx/venvs/ansible/bin :: This is usually a sign of broken local setup, which can cause unexpected behaviors.
This is safe to ignore.
List the PyPI system packages present:
python3 -m pip list
python3 -m pip list --format=json | jqList the PyPI user packages present:
python3 -m pip list --user
python3 -m pip list --user --format=json | jq
python3 -m pip list --user --format=json | jq | jp "[].name" | yq -o=yaml -PM | awk '{ print $2 }'Delete all PyPi user packages on Debian Bullseye or Ubuntu Jammy:
python3 -m pip uninstall $(pip list --user | grep -v -e ^P -e ^- | awk '{ print $1 }' | xargs)Delete all PyPi user packages on Debian Bookworm (with jp, jq and yq installed):
python3 -m pip uninstall --break-system-packages \
$(pip list --user --format=json | jq | jp "[].name" | yq -o=yaml -PM | awk '{ print $2 }' | xargs)List the PyPI package extras present, this jq query has been copied from GitHub:
python3 -m pip inspect | jq '.installed[]|select(.metadata.name=="molecule-plugins").metadata.provides_extra'List the pipx packages present:
pipx list
pipx list --json | jqList the installed Ansible galaxy collections:
ansible-galaxy collection list
ansible-galaxy collection list --format=json | jq- Ansible Porting Guides that can help you in updating playbooks, plugins and other parts of your Ansible infrastructure from one version of Ansible to the next
The primary URL of this repo is https://git.coop/webarch/ansible however it is also mirrored to GitHub and available via Ansible Galaxy.
If you use this role please use a tagged release, see the release notes.
Originally, in 2019, this repo contained a few roles that have since been moved to other repos.
Copyright 2019-2024 Chris Croome, <[email protected]>.
This role is released under the same terms as Ansible itself, the GNU GPLv3.