DEBOPS.APT_INSTALL(5)

NAME
debops.apt_install - Manage APT packages using Ansible

SYNOPSIS

debops run service/apt_install [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.apt_install Ansible role is meant to be used as an easy way to install APT packages on hosts that don't require more extensive configuration which would require a more extensive, custom Ansible role. The role itself exposes several Ansible default variables which can be used to specify custom lists of packages on different levels of Ansible inventory (global, per-group or per-host).

GETTING STARTED

  Initial configuration

The role comes with a small set of APT packages, useful on pretty much any Debian or Ubuntu host. Some of the packages are installed conditionally, depending on different Ansible facts - for example, firmware packages are installed on rack servers, which may contain network cards that require custom firmware loaded by the kernel for proper operation.

The role is not meant to be used as a dependency of other roles, but you can use it like that if you want to take advantage of the custom lookup template that uses conditional package installation depending on installed operating system, its release or available archive areas.

The difference between debops.apt and debops.apt_install Ansible roles is that the former role is used to configure the APT package manager itself, and latter just installs packages using APT package manager, depending on its configuration.

  Similar Ansible roles

There are more comprehensive Ansible roles that install packages:

•   ypid.packages <https://github.com/ypid/ansible-packages> - provides an advanced framework meant to allow installation of packages according to different host classes, with a large selection of packages. The role is focused on workstations, live systems and server environments.

  Example inventory

The debops.apt_install role is included by default in the common.yml DebOps playbook. You don't need to configure anything in the inventory to enable it.

The role provides a set of default variables to specify what packages should be installed on hosts, depending on the inventory level:

apt_install__packages
    This variable should be used in ansible/inventory/group_vars/debops_all_hosts/apt_install.yml file and is meant to specify packages present on all hosts in the inventory.

apt_install__group_packages
    This variable should be used in ansible/inventory/group_vars/<group-name>/apt_install.yml files and is meant to contain packages that should be installed on hosts in different Ansible groups. Only one level of this variable is supported, so you should be careful about your inventory design. Or, you can use it as a master list that contains different per-group variables.

apt_install__host_packages
    This variable should be used in ansible/inventory/host_vars/<hostname>/apt_install.yml files and is meant to contain list of packages that should be installed on specific hosts.

  Example playbook

debops.apt_install is designed to be used from a playbook or a role as role dependency. Here's an example configuration:

---
- name: Install APT packages
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_apt_install' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ apt_install__apt_preferences__dependent_list }}'
    - role: apt_install
      tags: [ 'role::apt_install', 'skip::apt_install' ]

DEFAULT VARIABLE DETAILS

Some of debops.apt_install default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  apt_install__debconf

These lists of YAML dictionaries can be used to add some values to the Debconf database. Each entry has the same keys as the ones used by the Ansible ansible.builtin.debconf module <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/debconf_module.html>. See its documentation for detailed parameter usage and syntax.

name
    Required. Name of the package to configure.

question
    A debconf configuration setting.

unseen
    Do not set 'seen' flag when pre-seeding.

value
    Value to set the configuration to.

vtype
    The type of the value supplied.

  Examples

Define the path to Matlab installation for matlab-support :

apt_install__debconf:
  - name: 'matlab-support'
    question: 'matlab-support/matlab-install-glob'
    value: '/usr/local/MATLAB/R2018b'
    vtype: 'string'

  apt_install__all_packages

This variable holds all YAML lists used by the corresponding Ansible lookup template passed to the apt module. Each element of this list can specify a name of the APT package to install, or a list of packages, or a YAML dictionary which defines conditions for the installation of the package(s).

The different dictionary keys that can be used to specify conditional installation:

name
    Required. Name of the APT package, or YAML list of package names to install.

state
    Optional. Specify if the given package(s) should be included in the list of packages to install (not the status of installation). If not specified or present, package(s) will be included, if absent, packages won't be included.

distribution
    Optional. Name or list of operating system distributions. If specified, a given package or list of packages will be installed only on these distributions.

release
    Optional. Name or list of distribution release names. If specified, a given package or list of packages will be installed only on systems with given OS releases.

area
    Optional. Name or list of package archive areas (main, non-free, restricted, etc.). If specified, role will check if a given archive area is enabled using Ansible local facts. The specified package(s) will be installed only when a given area is available. This can be used to avoid errors with missing packages on systems where non-free archive areas are not enabled.

whitelist
    Optional. This variable should reference a list of package names. The lookup template that filters the list of packages for installation will compare the names of selected packages against this list, and only packages which are included will be installed. This is used to provide an alternative, easier way to select packages for installation without the need to modify a huge, conditional list.

  Examples

Install packages on any OS release:

apt_install__packages:
  - 'package1'
  - 'package2'

Install packages only when specified OS release is present:

apt_install__packages:
  - name: 'package1'
    release: [ 'wheezy', 'trusty' ]

Install packages only when specified archive area is available:

apt_install__packages:
  - name: 'package1'
    area: 'non-free'

Install packages using Ansible fact condition:

apt_install__packages:
  - name: [ 'package1', 'package2' ]
    state: '{{ "present"
               if (ansible_virtualization_role == "guest")
               else "absent" }}'

  apt_install__alternatives

These YAML lists can be used to configure special symlinks (for example, editor, x-terminal-emulator, pager) which can point to different applications that provide similar functionality using the update-alternatives command. Each list element is a YAML dictionary with specific parameters:

name
    Required. Name of the symlink which should be configured.

path
    Optional. Absolute path to the application which should be symlinked. To see available alternatives, you can run the command:

    update-alternatives --display <name>

    If the path parameter is not specified, the role will configure a given symlink to select an application automatically.

link
    Optional. Absolute path to the file which should be symlinked. This is rarely needed.

priority
    Optional. Set a priority for a given application package. This is rarely needed.

  Examples

Configure Emacs to be the default system editor:

apt_install__alternatives:
  - name: 'editor'
    path: '/usr/bin/emacs24'

Let the system decide automatically what editor to use as default:

apt_install__alternatives:
  - name: 'editor'

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others