README.md 16.2 KB
Newer Older
Torsten Nielsen's avatar
Torsten Nielsen committed
1
2
# How to install and set up Ansible on (Ubuntu) Linux.

3
4
5
6
7
8
9
10
11
12
## 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

13
Use the files `init.vim`, `nanorc` and `micro_settings.json` to help setup your editor of choice or just delete them. See the section on editors at the end of this document: [Setting up Editors](#setting-up-editors-for-yaml-or-ansible).
14

Torsten Nielsen's avatar
Torsten Nielsen committed
15
16
17
18
## 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)

19
A couple of ways to install Ansible (on Ubuntu):
Torsten Nielsen's avatar
Torsten Nielsen committed
20
21
22

- 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)

23
- Using [Python pip](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-with-pip) to install (either globally, for a user or in a virtual environment)
24

Torsten Nielsen's avatar
Torsten Nielsen committed
25
26
27
28
29
30
31
## 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):

    $ sudo apt update
    $ sudo apt install ansible

32
[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)
Torsten Nielsen's avatar
Torsten Nielsen committed
33
34
35

    $ sudo apt update
    $ sudo apt install software-properties-common
36
    $ sudo add-apt-repository --yes --update ppa:ansible/ansible
37
    $ sudo apt install ansible
Torsten Nielsen's avatar
Torsten Nielsen committed
38

39
Since Ansible version 2.10 the default install has changed to a more modular install. Ansible used to include everything (and the kitchen sink), it now has a lean 'base' or 'core' installation. From version 4.x.x and up it is named 'core'. Besides the base or core install, there are both community and vendor supplied 'collections', with their own versioning.
Torsten Nielsen's avatar
Torsten Nielsen committed
40
41
42

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)

Torsten Nielsen's avatar
Torsten Nielsen committed
43
44
For [The latest version](https://pypi.org/project/ansible/) and [code](https://github.com/ansible/ansible) or even the [roadmap of Ansible](https://docs.ansible.com/ansible/devel/roadmap/ansible_roadmap_index.html).

Torsten Nielsen's avatar
Torsten Nielsen committed
45
46
# How to set up and use Python virtual environments for Ansible

Torsten Nielsen's avatar
Torsten Nielsen committed
47
> Python provides different ways to create virtual environments. In this guide Python virtual environments provided by the `venv` module are used. A 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).
Torsten Nielsen's avatar
Torsten Nielsen committed
48

49
### Why use Python virtual environments for Ansible development?
Torsten Nielsen's avatar
Torsten Nielsen committed
50
51
------------------------------------------------------------

52
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 (globally) using pip, then it can be a hassle to upgrade and the older version (often) has to be uninstalled first.
Torsten Nielsen's avatar
Torsten Nielsen committed
53

54
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.
Torsten Nielsen's avatar
Torsten Nielsen committed
55

56
57
## Get set up with Ansible in virtual environment
-------------------------------------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
58

Torsten Nielsen's avatar
Torsten Nielsen committed
59
Install the Python programs (on Ubuntu):
Torsten Nielsen's avatar
Torsten Nielsen committed
60

61
    $ sudo apt install python3-pip python3-venv python3-argcomplete cowsay
Torsten Nielsen's avatar
Torsten Nielsen committed
62
63
64
65
66
67
    $ python3 -V
    Python 3.8.10
    
    $ which python3
    /usr/bin/python3

68
Create a directory structure for Ansible and the virtual environments (`python-vens`). This layout is just one of many ways to set it up - Se [Ansible best practices](https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#directory-layout) for other ways:
69

70
71
72
73
74
75
    $ cd ~
    $ mkdir ansible
    $ cd ansible
    $ 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
Torsten Nielsen's avatar
Torsten Nielsen committed
76
77


78
79
### Create a new Python virtual environment
-------------------------------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
80
81
82

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:

83
84
    $ python3 -m venv python-venvs/ansible2.9.6
    $ ls python-venvs
Torsten Nielsen's avatar
Torsten Nielsen committed
85
86
87
    ansible2.9.6


88
89
### Activate a Python virtual environment
-----------------------------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
90
91
92

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:

93
    $ source python-venvs/ansible2.9.6/bin/activate
Torsten Nielsen's avatar
Torsten Nielsen committed
94
95
96
    (ansible2.9.6)$ python3 -V
    Python 3.6.8

97
Next, upgrade the preferred installer program (`pip`) inside your (active) virtual environment:
Torsten Nielsen's avatar
Torsten Nielsen committed
98
99
100

    (ansible2.9.6)$ python3 -m pip install --upgrade pip

101
102
### Install Ansible in a virtual environment
--------------------------------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
103
104
105
106
107

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):

    (ansible2.9.6)$ python3 -m pip install ansible==2.9.6
    (ansible2.9.6)$ which ansible
108
    ~/python-venv/ansible2.9.6/bin/ansible
Torsten Nielsen's avatar
Torsten Nielsen committed
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

Verify your new installation:

    (ansible2.9.6)$ ansible --version
    ansible 2.9.6
        config file = None
        configured module search path = ['/home/auXXX/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
        ansible python module location = /home/auXXX/ansible/python-venvs/ansible2.9.6/lib/python3.6/site-packages/ansible
        executable location = /home/auXXX/ansible/python-venvs/ansible2.9.6/bin/ansible
        python version = 3.6.9 (default, Jan 26 2021, 15:33:00) [GCC 8.4.0]


Ansible was not able to locate a config file - we'll fix that shortly. The Ansible executable and python modules are located in the virtual environment, but the Ansible module search path is outside.

Anything installed using pip is going in the venv folder for the active virtual environment.


126
Since Ansible can be installed in different ways. The [Ansible configuration](https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html) defines, where things like inventory, roles and collections should go.
Torsten Nielsen's avatar
Torsten Nielsen committed
127

128
129
## Ansible Configuration
-----------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
130
131
132
133
134
135
136
137

While running an Ansible command, the command looks for its configuration file in a predefined order, as follows:

    ANSIBLE_CFG: This environment variable is used, provided it is set
    ansible.cfg: This is located in the current directory
    ~/.ansible.cfg: This is located in the user's home directory
    /etc/ansible/ansible.cfg

138
An example slightly different from the examples given in [Ansible User Guide](https://docs.ansible.com/ansible/latest/user_guide/sample_setup.html)
Torsten Nielsen's avatar
Torsten Nielsen committed
139

140
If we use '~/ansible' as "current" or "working" directory, when we interact with Ansible, it makes sence to put `ansible.cfg` here. This way we could have different subfolders with diffent setups.
Torsten Nielsen's avatar
Torsten Nielsen committed
141
142

    $ cd ~/ansible
143
144
    $ ls -F 
    ansible.cfg  collections/  inventories/  myroles/  playbooks/  python-venvs/  roles/ host_vars/ group_vars/
Torsten Nielsen's avatar
Torsten Nielsen committed
145
146
147
148

Example configuration:
----------------------

149
150
Create a new file `ansible.cfg` with contents similar to:

Torsten Nielsen's avatar
Torsten Nielsen committed
151
152
    [defaults]

153
154
    # Paths to search for collections and roles
    collections_path = collections
155
    collections_scan_sys_path = false
Torsten Nielsen's avatar
Torsten Nielsen committed
156

157
    roles_path = roles:myroles
158

159
    # Create hosts files under inventories
160
    inventory = inventories
Torsten Nielsen's avatar
Torsten Nielsen committed
161

162
163
164
165
166
167
168
169
170
    # 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
Torsten Nielsen's avatar
Torsten Nielsen committed
171
172
    gather_timeout = 10

173
174
    # A bit of fun
    nocows = false
175
176
    #cow_selection = unipony-smaller
    cow_selection = tux
177
    nocolor = false
Torsten Nielsen's avatar
Torsten Nielsen committed
178
179

    [privilege_escalation]
180
181
182
183
    become = true
    become_method = sudo
    become_user = root
    become_ask_pass = false
Torsten Nielsen's avatar
Torsten Nielsen committed
184
185
186
187
188
189
190
191
192
193

    # For more example settings
    # https://github.com/ansible/ansible/blob/stable-2.11/examples/ansible.cfg
    # or use
    # ansible-config list


Install Ansible roles or collections
------------------------------------

194
195
Modules, Roles and Collections can be found at [Ansible Galaxy](https://galaxy.ansible.com/home).

Torsten Nielsen's avatar
Torsten Nielsen committed
196
197
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).

198
Default paths can be set in `ansible.cfg`, but Ansible roles and collections can also be installed into a specific local path using '-p'.
Torsten Nielsen's avatar
Torsten Nielsen committed
199

200
    (ansible2.9.6)$ cd ~/ansible
201
202
    (ansible2.9.6)$ ansible-galaxy collection list
    ...
Torsten Nielsen's avatar
Torsten Nielsen committed
203
204
205
206
207
208
    (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'
    /

209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
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

Torsten Nielsen's avatar
Torsten Nielsen committed
244

245
246
247
248
249
250
251
252
Install Ansible Lint
--------------------

[Ansible Lint](https://ansible-lint.readthedocs.io/en/latest/) helps "linting" the yaml files as well as jinja2 templates.

    (ansible2.9.6)$ python3 -m pip install "ansible-lint[community,yamllint]"


253
254
255
256
257
258
259
260
261
262
263
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

264

Torsten Nielsen's avatar
Torsten Nielsen committed
265
266
267
268
269
Deactivate a Python virtual environment
---------------------------------------

Once you're finished working inside your Python virtual environment (or it's time to switch to another Python virtual environment), you can deactivate it:

270
    (ansible2.9.6)$ deactivate  
Torsten Nielsen's avatar
Torsten Nielsen committed
271

272
273
Create another Python virtual environment for Ansible 3.4.0
-----------------------------------------------------------
Torsten Nielsen's avatar
Torsten Nielsen committed
274
275
276
277
278

After deactivating the first virtual environment, try creating another Python virtual environment to understand the power this technology grants you. In this new environment, you can install Ansible 3.4.0 [or any other version](https://pypi.org/project/ansible/#history):

    $ cd ~/ansible
    $ python3 -m venv python-venvs/ansible3.4.0
279
    $ . python-venvs/ansible3.4.0/bin/activate #BASH: '.' same as source
Torsten Nielsen's avatar
Torsten Nielsen committed
280
281
282
283
    (ansible3.4.0)$ python3 -m pip install --upgrade pip
    (ansible3.4.0)$ python3 -m pip install wheel
    (ansible3.4.0)$ python3 -m pip install ansible==3.4.0

284
285
286
287
288
289

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).

Torsten Nielsen's avatar
Torsten Nielsen committed
290
291
292
293
294
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.

295
296
Setting up Editors for YAML or Ansible
--------------------------------------
297

298
299
300
### Vim or Neovim

A very simple setup for vim (`~/.vimrc`) or neovim (`~/.config/nvim/init.vim` or alternatively [$XDG_CONFIG_HOME/nvim/init.vim](https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html) ):
301
302
303
304
305
306
307
308

    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

309
### Nano editor
310

311
Simple config for nano editor (`~/.config/nano/nanorc`):
312
313
314
315
316

    set autoindent
    set tabsize 2
    set tabstospaces

317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
A more elaborate example config for nano is included i this repo: `nanorc`.

### Micro editor

There is a [new editor micro](https://micro-editor.github.io/), with sane defaults. It has mouse-support and even "understands" yaml right out of the box. It's programmed in Go and has extensions written in Lua.

    $ sudo apt install micro
    $ micro -plugin install nordcolors
    $ ls ~/.config/micro/plug/nordcolors/
    colorschemes  help  LICENSE  nordcolors.lua  pics  README.md  repo.json

A small config for micro editor (`~/.config/micro/settings.json`):

    {
        "ft:yaml": {
            "tabsize": 2
        }
    }


"Inside" the micro editor, try `Ctrl-e` and on the new cmd-line: `set colorscheme <Space> <TAB>` or try `Ctrl-g` (again to get out of help) and `Ctrl-q` to quit. 
338

339
340
Note for users of the VS Code editor (and friends)
--------------------------------------------------
341

342
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/).
Torsten Nielsen's avatar
Torsten Nielsen committed
343

344
345
346
For an extra bit of fun
-----------------------

Torsten Nielsen's avatar
Torsten Nielsen committed
347
Install cowsay to add a bit of fun to your Ansible output (can be disabled in `ansible.cfg`):
348
349
350
351
352
353
354
355
356
357
358
359
360

    $ sudo apt install cowsay
    $ cowsay Hello!
    ________
    < Hello! >
    --------
            \   ^__^
            \  (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||


361
362
363
364
365
Next Step:
----------

Hopefully you are now ready to [start using Ansible](https://docs.ansible.com/ansible/latest/user_guide/index.html#getting-started)

366
Modified from: [Source](https://www.redhat.com/sysadmin/python-venv-ansible?sc_cid=7013a000002pezWAAQ)