Commit 027f215c authored by Torsten Nielsen's avatar Torsten Nielsen
Browse files

Update README.md and add bootstrap files.

parent b8e8786d
# How to install and set up Ansible on (Ubuntu) Linux.
## TL;DR
Clone this repository to a folder of choice and run the bootstrap script:
$ cd ~
$ git clone git@gitlab.au.dk:ansible/ansible_howto.git ansible
$ cd ansible
$ ./bootstrap-setup.sh
$ rm -fr .git
Use the files `init.vim` and `nanorc` to help setup your editor of choice or just delete them.
## Different ways to install Ansible
Ansible is based on Python (not Perl), but still regarding install, "There's more than one way to do it" [TMTOWTDI](https://en.wikipedia.org/wiki/There%27s_more_than_one_way_to_do_it)
......@@ -8,6 +20,8 @@ There are a number of ways to install Ansible (on Ubuntu):
- System wide install using (deb) packages (with or without PPA): [Install Ansible on Ubuntu using apt](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu)
- Using [Python pip](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-with-pip) to install (globally, as user or in virtual environment)
## System wide installs (all users) using deb-packages
Use std. package from Ubuntu (installs version 2.9.6 on focal/20.04 at time of writing):
......@@ -15,30 +29,32 @@ Use std. package from Ubuntu (installs version 2.9.6 on focal/20.04 at time of w
$ sudo apt update
$ sudo apt install ansible
[Ansible docs' install guide for Ubuntu](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu) also suggests the use of a [PPA](https://launchpad.net/~ansible/+archive/ubuntu/ansible), but [this PPA](https://launchpad.net/~ansible/+archive/ubuntu/ansible) does not support Ubuntu 20.04 aka "Focal", so if you are using a newer Ubuntu version, take at look at the [other PPAs](https://launchpad.net/~ansible) and maybe choose [ansible-3](https://launchpad.net/~ansible/+archive/ubuntu/ansible-3):
[Ansible docs' install guide for Ubuntu](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu) also suggests the use of a [PPA](https://launchpad.net/~ansible/+archive/ubuntu/ansible), but [this PPA](https://launchpad.net/~ansible/+archive/ubuntu/ansible) does not support Ubuntu 20.04 aka "Focal", so if you are using a newer Ubuntu version, take at look at the [other PPAs](https://launchpad.net/~ansible) and maybe choose [ansible-3](https://launchpad.net/~ansible/+archive/ubuntu/ansible-3):/
$ sudo apt update
$ sudo apt install software-properties-common
$ sudo add-apt-repository --yes --update ppa:ansible/ansible-3
$ sudo add-apt-repository --yes --update ppa:ansible/ansible
$ sudo apt install ansible
The [PPA version for Ubuntu 20.04 focal](https://launchpad.net/~ansible/+archive/ubuntu/ansible?field.series_filter=focal) has recently (at time of writing - Nov 2021) been updated to version 4.8, so it's very up to date.
Since Ansible version 2.10 the default install has changed to a more modular install. Where Ansible used to include everything (and the kitchen sink), it now has a lean 'base' install, which has again changed to a 'core' install from version 4.x.x and up. Besides the base (or core) install, there are community and vendor collections, with their own versioning.
Se more here: [Ansible 3.0.0 blog post](https://blog.while-true-do.io/ansible-release-3-0-0/) and [Ansible.com blog post](https://www.ansible.com/blog/ansible-3.0.0-qa) or [Ansible 3 Release Notes](https://github.com/ansible-community/ansible-build-data/blob/main/3/CHANGELOG-v3.rst) or [Ansible 4 Release Notes](https://github.com/ansible-community/ansible-build-data/blob/c4ab2b13b7dca1ac14c49e5f56e5185fba500d87/4/CHANGELOG-v4.rst)
# How to set up and use Python virtual environments for Ansible
> Python provides different ways to create virtual environment. In this guide Python virtual environments provided by the `venv` module is used. An more featureful alternative could be [virtualenv](https://virtualenv.pypa.io/en/stable/) as demonstrated in the [Ansible doc](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-in-a-virtual-environment-with-pip). Maybe take a look at [Pyenv](https://github.com/pyenv/pyenv).
> Python provides different ways to create virtual environments. In this guide Python virtual environments provided by the `venv` module are used. An more featureful alternative could be [virtualenv](https://virtualenv.pypa.io/en/stable/) as demonstrated in the [Ansible doc](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-in-a-virtual-environment-with-pip). Install `python3-virualenv` to use that. Maybe take a look at [Pyenv](https://github.com/pyenv/pyenv).
Why use Python virtual environments for Ansible development?
### Why use Python virtual environments for Ansible development?
------------------------------------------------------------
Virtual environments create an isolated structure of lightweight directories separated from actual Python system directories. That means you can have different sets of Python environments, each with different versions of modules, files, or configurations. If Ansible is installed using pip, then it can be a hassle to upgrade and older version has to be uninstalled first.
Virtual environments create an isolated structure of lightweight directories separated from actual Python system directories. That means you can have different sets of Python environments, each with different versions of modules, files, or configurations. If Ansible is installed using pip, then it can be a hassle to upgrade and the older version (often) has to be uninstalled first.
Ansible is based on Python and leverages many Python modules and plugins. When you test something new, it could require you to update a module that your Ansible installation depends on. Upgrading a component that your production environment depends on defeats the purpose of testing. Still, you can have different versions of Ansible and other important Python modules in a dedicated test directory with a virtual environment.
Ansible is based on Python and leverages many Python modules and plugins. When you test something new, it could require you to update a module, that your Ansible installation depends on. Upgrading a component that your production environment depends on defeats the purpose of testing. Still, you can have different versions of Ansible and other important Python modules in a dedicated test directory with a virtual environment.
Get set up
----------
## Get set up with Ansible in virtual environment
-------------------------------------------------
Verify the installed Python version and path:
......@@ -50,14 +66,22 @@ Verify the installed Python version and path:
/usr/bin/python3
Create a directory structure for the virtual environments:
# Default remote (sudo) user - often overwritten in playbook
remote_user = administrator
# Save logfiles
log_path = var/logs/ansible.log
local_tmp = var/tmp
host_key_checking = false
retry_files_enabled = false
gather_timeout = 10
$ mkdir -p ~/ansible/python-venvs
$ cd !$
Create a new Python virtual environment
---------------------------------------
### Create a new Python virtual environment
-------------------------------------------
Create a virtual environment using the `python3 -m venv <environment-name>` command. You can give any name to your Python virtual environment. I want to try the `Ansible 2.9` version, so I named it in a way to identify the directory easily:
......@@ -66,8 +90,8 @@ Create a virtual environment using the `python3 -m venv <environment-name>` comm
ansible2.9.6
Activate a Python virtual environment
-------------------------------------
### Activate a Python virtual environment
-----------------------------------------
After creating a virtual environment, you must enter the environment manually. This changes your active environment variables from your current shell to those required for Python to create a virtual environment:
......@@ -79,8 +103,8 @@ Next, upgrade the preferred installer program (`pip`) inside your virtual enviro
(ansible2.9.6)$ python3 -m pip install --upgrade pip
Install Ansible in a virtual environment
----------------------------------------
### Install Ansible in a virtual environment
--------------------------------------------
With your virtual environment set up and active, you can install a dedicated version of Ansible into it. This example installs version 2.9.6, but you can install any version that's current (or in development):
......@@ -106,8 +130,8 @@ Anything installed using pip is going in the venv folder for the active virtual
Just like Ansible can be installed in different ways. The Ansible configuration define, where things like inventory, roles and collections should go.
Ansible Configuration
---------------------
## Ansible Configuration
-----------------------
While running an Ansible command, the command looks for its configuration file in a predefined order, as follows:
......@@ -131,19 +155,29 @@ Example configuration:
[defaults]
# Paths to search for collections and roles, colon separated
collections_paths = ~/ansible/collections
roles_path = roles:myroles # put your own roles in separate folder
collections_paths = collections
collections_scan_sys_path = false
# create hosts files under inventory
roles_path = roles:myroles # (optionally) put your own roles in separate folder
# create hosts files under inventories
inventory = inventories
# Default remote (sudo) user - often overwritten in playbook
remote_user = administrator
# Save logfiles
log_path = var/logs/ansible.log
local_tmp = var/tmp
host_key_checking = false
retry_files_enabled = false
gather_timeout = 10
private_key_file = ~/.ssh/ansible_key # generate and distribute key with ssh
host_key_checking = False # Mainly for convenience enable for more secure setup
retry_files_enabled = False # Enable if you want this
# Default Ansible remote user - if nothing is set in playbook
remote_user = ansible # user with sudo privileges on managed system
# A bit of fun
nocows = false
cowselection = unipony-smaller
nocolor = false
[privilege_escalation]
#Change the defaults if needed and/or overwrite in playbook/CLI
......@@ -165,16 +199,52 @@ Modules, Roles and Collections can be found at [Ansible Galaxy](https://galaxy.a
An example (community) collection to install could be [Ansible Community Docker](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html#plugins-in-community-docker) using the method in [Ansible doc Collection](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html).
You can also install Ansible roles and collections into a specific local path using '-p'.
Default paths can be set in `ansible.cfg`, but Ansible roles and collections can also be installed into a specific local path using '-p'.
(ansible2.9.6)$ cd ~/ansible
(ansible2.9.6)$ ansible-galaxy collection list
...
(ansible2.9.6)$ ansible-galaxy collection install community.docker -p collections
Process install dependency map
Starting collection install process
Installing 'community.docker:1.9.1' to '/home/auXXX/ansible/collections/ansible_collections/community/docker'
/
Collections and Roles can be used across different versions of Ansible, but if you need special versions or want to isolate some, that don't work with certain versions of Ansible, then it would make sence to isolate them in their own folders.
Collections and Roles can be used across different versions of Ansible, but if you need special versions or want to isolate some, that don't work with certain versions of Ansible, then it would make sence to isolate them in their own folders. I split roles across the downloaded (from Galaxy and elsewhere) in roles, and versioned (using git) roles, that I'm working on in myroles. Both rotes and collections can be installed using a `requirements.yaml` file.
`requirements.yaml`:
---
collections:
- name: community.general
source: https://galaxy.ansible.com
roles:
- name: geerlingguy.java
source: htts://galaxy.ansible.com
- name: nvjacobo.caddy
source: https://galaxy.ansible.com
- name: au_umask
src: https://gitlab.au.dk/ansible/au_umask.git
version: origin/master
scm: git
- name: au_cups
src: https://gitlab.au.dk/ansible/au_cups.git
version: origin/master
scm: git
- name: au_config
src: https://gitlab.au.dk/ansible/au_config.git
version: origin/master
scm: git
Install the collections and roles in `requirements.yaml`:
$ ansible-galaxy install -r requirements.yaml
Install Ansible Lint
--------------------
......@@ -184,6 +254,17 @@ Install Ansible Lint
(ansible2.9.6)$ python3 -m pip install "ansible-lint[community,yamllint]"
Install ansible command shell completion
----------------------------------------
Install argcomplete: `python3-argcomplete` or use `pip3 install argcomplete` from [PyPI](https://pypi.org/project/argcomplete/).
Configure argcomplete (global):
$ sudo apt install python3-argcomplete
$ sudo activate-global-python-argcomplete3
Installing bash completion script /etc/bash_completion.d/python-argcomplete.sh
Deactivate a Python virtual environment
---------------------------------------
......@@ -204,14 +285,57 @@ After deactivating the first virtual environment, try creating another Python vi
(ansible3.4.0)$ python3 -m pip install wheel
(ansible3.4.0)$ python3 -m pip install ansible==3.4.0
Official releases of Ansible:
-----------------------------
Go to [PyPI Ansible](https://pypi.org/project/ansible/), [PyPI Ansible-core](https://pypi.org/project/ansible-base/) for the 4.x.y release or [PyPI Ansible-core](https://pypi.org/project/ansible-core/) to complement 3.x.y Ansible releases. Have a look at the [Ansible Roadmap](https://docs.ansible.com/ansible/latest/roadmap/ansible_roadmap_index.html).
Wrap up
-------
Python virtual environments give you the freedom to test whatever version of modules, plugins, and Python packages you need. That includes vital sysadmin software like Ansible, so you can test new Ansible features without disturbing your system install.
Setting up Editors for YAML and/or Ansible
------------------------------------------
A very simple setup for vim (`~/.vimrc`) or neovim (`~/.config/nvim/init.vim`):
syntax on
filetype plugin indent on
"Get the 2-space YAML as the default
"cuc CUrrent Column highlighting
"cul CUrrent Line highlighting
autocmd FileType yaml setlocal autoindent expandtab ts=2 sw=2 cuc cul
Simple config for nano editor (`~/.nanorc`):
set autoindent
set tabsize 2
set tabstospaces
Note for users of the VS Code editor (and friends)
--------------------------------------------------
There is a [VS Code plugin for Ansible](https://marketplace.visualstudio.com/items?itemName=redhat.ansible). The plugin can also be used by other [OpenVSX](https://open-vsx.org/) compatible editors like [Onivim](https://www.onivim.io/) or [VS Codium](https://vscodium.com/).
For an extra bit of fun
-----------------------
Install cowsay to add a bit of fun to your Ansible output:
$ sudo apt install cowsay
$ cowsay Hello!
________
< Hello! >
--------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
Modified from: [Source](https://www.redhat.com/sysadmin/python-venv-ansible?sc_cid=7013a000002pezWAAQ)
[defaults]
# Paths to search for collections and roles
collections_path = collections
collections_scan_sys_path = false
roles_path = roles:myroles
# Create hosts files under inventories
inventory = inventories
# Default remote (sudo) user - often overwritten in playbook
remote_user = administrator
# Save logfiles
log_path = var/logs/ansible.log
local_tmp = var/tmp
host_key_checking = false
retry_files_enabled = false
gather_timeout = 10
# A bit of fun
nocows = false
#cow_selection = unipony-smaller
cow_selection = tux
nocolor = false
[privilege_escalation]
become = true
become_method = sudo
become_user = root
become_ask_pass = false
# For more example settings
# https://github.com/ansible/ansible/blob/stable-2.11/examples/ansible.cfg
# or use
# ansible-config list
#!/bin/bash
echo "Install packages.........."
echo "--------------------------"
sudo apt update
sudo apt install python3-venv python3-pip python3-argcomplete cowsay
sudo activate-global-python-argcomplete3
cowsay -f unipony-smaller "Done installing!"
# source /etc/bash_completion.d/python-argcomplete.sh
echo ""
echo "-----------------------------"
cowsay "Creating directory structure"
echo "-----------------------------"
mkdir -p python-venvs collections roles myroles inventories playbooks host_vars group_vars var/{tmp,logs}
touch var/logs/ansible.log
echo -e "[local]\nlocalhost ansible_connection=local\n" > inventories/hosts
mv ping-test.yaml playbooks/ping-test.yaml
echo ""
echo "---------------------------"
cowsay "Installing Ansible in venv"
echo "---------------------------"
python3 -m venv python-venvs/ansible4
. python-venvs/ansible4/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install wheel
python3 -m pip install ansible
#python3 -m pip install argcomplete
echo ""
echo "---------------------------"
echo "Ansible version:"
echo "---------------------------"
ansible --version
echo "---------------------------"
echo ""
echo ""
echo "To activate the python venv and ansible run:"
echo "\$ . python-venvs/ansible4/bin/activate"
echo ""
echo "Load the python venv via .bashrc by running:"
echo '$ echo "$ . python-venvs/ansible4/bin/activate" >> ~/.bashrc'
echo ""
echo ""
echo "If the ansible.cfg is in place, and you have a requirements.yaml file,"
echo "then you can install the required collections and roles using:"
echo "\$ ansible-galaxy install -r requirements.yaml"
echo ""
echo "Now you can test the installation by running:"
echo ""
echo "\$ ansible -m ping local --user \$(whoami)"
echo ""
echo "Change the remote_user in ansible.cfg to avoid giving --user option"
echo ""
echo "Other things to try:"
echo "\$ ansible-inventory --list --yaml"
echo "\$ ansible-playbook playbooks/ping-test.yaml"
echo "\$ ansible -m setup local"
syntax on
filetype plugin indent on
"Get the 2-space YAML as the default
autocmd FileType yaml setlocal autoindent expandtab ts=2 sw=2 cuc cul
set autoindent
set tabsize 2
set tabstospaces
---
collections:
- name: community.general
source: https://galaxy.ansible.com
roles:
- name: geerlingguy.java
source: htts://galaxy.ansible.com
- name: nvjacobo.caddy
source: https://galaxy.ansible.com
- name: au_umask
src: https://gitlab.au.dk/ansible/au_umask.git
version: origin/master
scm: git
- name: au_cups
src: https://gitlab.au.dk/ansible/au_cups.git
version: origin/master
scm: git
- name: au_config
src: https://gitlab.au.dk/ansible/au_config.git
version: origin/master
scm: git
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment