DEBOPS.EXTREPO(5)

NAME
debops.extrepo - Manage external APT sources using Ansible

SYNOPSIS

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

debops run site --tags role::extrepo [playbook] ... [--limit group,host,...] [--diff] [--check] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

debops run site --skip-tags skip::extrepo [playbook] ... [--limit group,host,...] [--diff] [--check] [--tags-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The extrepo <https://packages.debian.org/sid/extrepo> Debian package provides an easy way to manage APT sources external to the Debian main archives. The list of supported APT sources <https://salsa.debian.org/extrepo-team/extrepo-data> is curated outside of the normal Debian release cycle and contains details about popular third-party APT repositories maintained by software vendors.

The debops.extrepo Ansible role can be used to manage third-party APT repositories via Ansible using the extrepo package. The role is written as complimentary to the debops.keyring role which provides a similar functionality.

GETTING STARTED

  Conflicts with other APT sources

Some packages from third-party repositories, for example Google Chrome, may install their own /etc/apt/sources.list.d/*.list configuration files on installation. This might result in a conflict, since extrepo .sources files define a specific GPG key for each external APT source. You might see an error message while running apt update, for example:

E: Conflicting values set for option Signed-By regarding source
   http://dl.google.com/linux/chrome/deb/ stable:
   /var/lib/extrepo/keys/google_chrome.asc !=
E: The list of sources could not be read.

There's currently nothing the debops.extrepo role can do about this. To fix these issues, you might need to comment out the additional APT sources installed by the software package. Some third-party packages support this situation and don't re-create the APT sources, others might not. YMMV.

  Example inventory

To install and configure extrepo on a given host, it should be included in a specific Ansible inventory group:

[debops_all_hosts]
hostname
[debops_service_extrepo]
hostname

By default the role does not enable any APT sources. Users can do that via Ansible inventory using the extrepo__*_sources variables. Other Ansible roles can also interface with the debops.extrepo role through the extrepo__dependent_sources variable used on the playbook level.

The repository components enabled by extrepo (main, contrib, non-free, etc.) are set using the ansible_local.apt.components Ansible local fact. You can use the debops.apt role to enable non-free components which might be needed for certain repositories, for example FastTrack repository <https://wiki.debian.org/FastTrack> with packaged GitLab.

To pick a specific version of a package from the APT repository, you can use the debops.apt_preferences role.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.extrepo role:

---
- name: Manage external APT sources
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_extrepo' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: extrepo
      tags: [ 'role::extrepo', 'skip::extrepo' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::extrepo
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.extrepo Ansible role:

•   Manual pages: extrepo(1p) <https://manpages.debian.org/extrepo(1p)>, sources.list(5) <https://manpages.debian.org/sources.list(5)>

•   Announcement about the extrepo package <https://grep.be/blog/en/computer/debian/Announcing_extrepo/>

•   Blog post <https://grep.be/blog/en/computer/debian/Software_available_through_Extrepo/> about some of the APT repositories available through extrepo

•   The extrepo-data repository <https://salsa.debian.org/extrepo-team/extrepo-data> which contains metadata about third-party APT sources

DEFAULT VARIABLE DETAILS

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

  extrepo__configuration

These variables define the contents of the /etc/extrepo/config.yaml configuration file. The original file is diverted to preserve its contents and avoid configuration changes during package upgrades.

  Examples

Override the selection of the repository components via Ansible inventory (the default is based on the debops.apt local facts):

extrepo__configuration:
  - name: 'policies'
    config:
      enabled_policies: [ 'main', 'contrib', 'non-free' ]

  Syntax

The variables are defined as lists of YAML dictionaries. Each dictionary defines a part of the final configuration file; configuration entries are merged together and rendered as a YAML document. Each configuration entry is defined using specific parameters:

name
    Required. An identifier for a particular configuration entry, not used in the configuration file itself. Entries with the same name parameter can be overridden by subsequent entries.

config
    Required. YAML dictionary with the extrepo configuration options.

state
    Optional. If not specified or present, a given configuration entry will be included in the generated configuration file. If absent, the configuration entry will be removed from the generated configuration file. If ignore, a given configuration entry will not be considered during template generation. This can be used to conditionally enable or disable configuration options.

  extrepo__sources

These lists define the names of the external APT sources available using the extrepo command, which should be configured on a host or a group of hosts. You can see the list of available APT sources by running the extrepo search command on the remote host after the extrepo package is installed.

  Examples

Configure access to the Debian FastTrack <https://fasttrack.debian.net/> repositories (the official Debian Backports repository might also be needed, see debops.apt role for details). In this example we use a simple syntax to specify a list of APT sources.

extrepo__sources:
  - 'fasttrack'
  - 'fasttrack_backports'

Enable the Elastic APT repository to get access to Elasticsearch, Kibana, Filebeat and other packages.

extrepo__sources:
  - 'elastic'

Make sure that the upstream Docker APT repository is disabled and enable the upstream Kubernetes repository.

extrepo__sources:
  - name: 'kubernetes'
    state: 'present'
  - name: 'docker-ce'
    state: 'absent'

  Syntax

You can specify a list of strings which define the names of the APT sources available via extrepo. To see the available APT sources, you can run the extrepo search command.

Alternatively, each list entry can be a YAML dictionary with specific parameters:

name
    Required. Name of the APT source to manage.

state
    Optional. If not specified or present, the specified APT source will be enabled via the extrepo command. If absent, the source file located in /etc/apt/sources.list.d/extrepo_name.sources will be removed.

AUTHOR
Maciej Delmanowski

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