User’s guide

Introduction

The role installs packages, creates and configures files, services, and handlers. This provides a simple, but flexible framework to apply basic Ansible modules. A substantial part of the control-flow will be determined by the structure of the data. Some attributes of the dictionaries trigger Ansible modules to modify configuration files, configure services and create handlers.

The role can be used with any supported OS to install and configure arbitrary applications. The role is tested with supported releases of FreeBSD and Ubuntu. It can be expected that other BSD and Linux distributions, that support the Ansible modules mentioned below, should work with minimal changes. Red Hat and Debian ansible_os_family should work out of the box.

Ansible modules package, apt, yum, and snap are used to install Linux packages. In FreeBSD, modules pkgng and portinstall are used to install FreeBSD packages and ports.

Ansible modules file, template, copy, replace, patch, lineinfile, blockinfile, and ini_file are used to configure files. The module mount is used to mount and unmount paths, and to configure fstab. Module service is used to manage both Linux and FreeBSD services.

The directory contrib comprises examples on how to install and configure various applications and how to create the handlers and templates. Some of them are commented Examples.

The user of this role is expected to master at least the following Ansible topics

Feel free to share your feedback and report issues. The contributions to the project are welcome.

Installation

The most convenient way how to install an Ansible role is to use Ansible Galaxy CLI ansible-galaxy. The utility comes with the standard Ansible package and provides the user with a simple interface to the Ansible Galaxy’s services. For example, take a look at the current status of the role

shell> ansible-galaxy role info vbotka.config_light

and install it

shell> ansible-galaxy role install vbotka.config_light

Install the collections community.general and ansible.posix

shell> ansible-galaxy collection install ansible.posix
shell> ansible-galaxy collection install community.general

Optionally install package ansible-lint if you want to enable the validation of created handlers and assembled data.

See also

  • To install specific versions from various sources see Installing content
  • Take a look at other roles shell> ansible-galaxy search --author=vbotka

Playbook

Below is a simple playbook that calls this role (10) at a single host srv.example.com (2)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
shell> cat config-light.yml
- hosts: srv.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: yes
  become_user: root
  become_method: sudo
  roles:
    - vbotka.config_light

Note

gather_facts: true (3) must be set to gather facts needed to evaluate OS-specific options of the role. For example to install packages the variable ansible_os_family is needed to select the appropriate Ansible module.

See also

Debug

To see additional debug information enable debug output in the configuration

cl_debug: true

, or set the extra variable in the command:

shell> ansible-playbook config-light.yml -e 'cl_debug=true'

Note

The debug output of this role is optimized for the yaml callback plugin. Set this plugin, for example, in the environment shell> export ANSIBLE_STDOUT_CALLBACK=yaml.

Tags

The tags provide a very useful tool to run selected tasks of the role. To see what tags are available list the tags of the role with the command

1
2
3
4
5
6
7
 shell> ansible-playbook config-light.yml --list-tags

 playbook: config-light.yml

   play #1 (srv.example.com): srv.example.com        TAGS: []
   TASK TAGS: [always, cl_debug, cl_files, cl_packages, cl_sanity,
   cl_services, cl_setup, cl_states, cl_vars]

For example, display the list of the variables and their values with the tag cl_debug (when debug is enabled cl_debug: true). With this tag specified -t cl_debug all imported tasks before the task debug.yml will also run because of the tag always when sanity testing is enabled cl_sanity: true (default) and setup is enabled cl_setup: true (default).

shell> ansible-playbook config-light.yml -t cl_debug

See what packages will be installed

shell> ansible-playbook config-light.yml -t cl_packages --check

Install packages and exit the play

shell> ansible-playbook config-light.yml -t cl_packages

See also

Variables

The Default variables control the options of the role. Most important are the variables that control the collection of the configuration data. For example, in each project, customize the directory cl_dird where the files with the configuration data are stored.

See the particular sections below on how to configure the creation of handlers, installation of the packages or ports, and management of files and services. Most options are available in the section Files. See the particular subsections on how to create the configuration data for the Ansible modules that serve the options. Review hints in the Examples.

See also

Note

The names of the dictionaries in the configuration files cl_dird/*.d/* are not used by the role and can be any arbitrary string that is a valid name of an Ansible variable. The name must be unique in the particular option (directory files.d, packages.d, …).

Best practice

Check syntax of setup

Check syntax of the playbook

shell> ansible-playbook pb.yml --syntax-check

Check syntax of setup and display variables

shell> ansible-playbook pb.yml -t cl_setup -e cl_debug=true --check --diff

If you want to see the values of the variables enable debug output cl_debug=true.

Setup

Collect variables, create handlers, check sanity, and display variables. When you take a look at tasks/main.yml you’ll see that the first four groups of the tasks (setup, vars, sanity, and debug) are tagged always. As a result, when you apply any of the four tags (cl_setup, cl_vars, cl_sanity, and cl_debug) all four groups of the tasks, and only these four groups of the tasks, will be executed. All four commands below are equivalent to the command

shell> ansible-playbook pb.yml -t cl_setup,cl_vars,cl_sanity,cl_debug
  • Create variables. Take a look at directory conf-light/assemble/ what files were created

    shell> ansible-playbook pb.yml -t cl_vars
    
  • Test sanity. Then disable this task cl_sanity: false to speedup the playbook

    shell> ansible-playbook pb.yml -t cl_sanity
    
  • Create handlers. Take a look at directory roles/vbotka.config_light/handlers what handlers were created. Run this task once to create the handlers. Then disable this task cl_setup: false to speedup the playbook

    shell> ansible-playbook pb.yml -t cl_setup
    
  • Display variables. Then disable this task cl_debug: false to speedup the playbook

    shell> ansible-playbook pb.yml -t cl_debug
    

Validation

Create the variables cl_assemble_validate and cl_handlers_validate if you want to enable validation of the created handlers and assembled data. See defaults/main.yml. You’ll have to install the package yamllint.

Check syntax

Check syntax of the complete playbook

shell> ansible-playbook pb.yml --syntax-check

Manage packages

Dry-run the management of packages

shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true -CD

Manage packages

shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true

Then disable the installation cl_install=false to speedup the playbook.

Manage states of files

Dry-run the management of files’ states

shell> ansible-playbook pb.yml -t cl_states -CD

Set the states (existence and attributes) of the files

shell> ansible-playbook pb.yml -t cl_states

Manage configuration files

Dry-run the configuration of files

shell> ansible-playbook pb.yml -t cl_files -CD

Create and modify files

shell> ansible-playbook pb.yml -t cl_files

Manage services

Dry-run the configuration of services

shell> ansible-playbook pb.yml -t cl_services -CD

Configure services

shell> ansible-playbook pb.yml -t cl_services

Idempotency

The role and the configuration data in the examples are idempotent. When the application is installed and configured there should be no changes reported by ansible-playbook when running the playbook repeatedly. Disable setup, sanity, debug, and install to speedup the execution when running the playbook periodically to audit the configuration

shell> ansible-playbook pb.yml -e cl_setup=false \
                               -e cl_sanity=false \
                               -e cl_debug=false \
                               -e cl_install=false