1. Home
  2. Ansible Tutorials & Courses
  3. Ansible yum_repository Module Tutorial + Examples

Ansible yum_repository Module Tutorial + Examples

Percy Grunwald's Profile Picture

Written by Percy Grunwald

— Last Updated April 2, 2024

Table of Contents

Ansible Course: Productive with Ansible (2024)
Ansible Course: Productive with Ansible (2024)
Go from Ansible beginner to Ansible pro with this full video course.

What does the Ansible yum_repository module do?

Ansible’s yum_repository module is used to manage repositories for the yum package manager. The most common use case for this module is adding a third party repository, such as Elasticsearch.

Before adding a repository with this module, you will usually need to add a GPG key with the rpm_key module as shown in the examples below.

Superuser (root) privileges are usually required to manage RPM keys and repositories, so become: true should be used in most cases.

- name: install elasticsearch rpm key
  rpm_key:
    key: https://artifacts.elastic.co/GPG-KEY-elasticsearch
    state: present
  become: true

- name: install elasticsearch 6.x rpm repository
  yum_repository:
    name: elasticsearch-6.x
    description: Elasticsearch repository for 6.x packages
    baseurl: https://artifacts.elastic.co/packages/6.x/yum
    gpgcheck: true
    gpgkey: https://artifacts.elastic.co/GPG-KEY-elasticsearch
  become: true

- name: install java & elasticsearch 6.x
  yum:
    name: "{{ item }}"
    state: present
    update_cache: true
  loop:
    - java-1.7.0-openjdk
    - elasticsearch
  become: true

This module is only relevant for RPM-based Linux distributions such as Red Hat Enterprise Linux and CentOS. For Debian-based distros such as Debian or Ubuntu, use the corresponding apt modules to manage keys and repositories, and install packages:

Examples

How to add a yum repository (+ RPM key) and install a package

The example below adapts the installation instructions for installing Elasticsearch with RPM into Ansible form.

How to import a RPM GPG key

Packages from Elastic are signed with their PGP key, so we should import the key with the rpm_key module:

- name: install elasticsearch rpm key
  rpm_key:
    key: https://artifacts.elastic.co/GPG-KEY-elasticsearch
    state: present
  become: true

How to add a yum repository

The instructions call for creating a file in /etc/yum.repos.d; this is what the yum_repository module will do automatically. Note that state: present is not required because that is the default state.

- name: install elasticsearch 6.x rpm repository
  yum_repository:
    name: elasticsearch-6.x
    description: Elasticsearch repository for 6.x packages
    baseurl: https://artifacts.elastic.co/packages/6.x/yum
    gpgcheck: true
    gpgkey: https://artifacts.elastic.co/GPG-KEY-elasticsearch
  become: true

How to install Elasticsearch 6.x (+ Java)

Now that the elasticsearch-6.x repo has been added, we can install the elasticsearch package with the yum module. yum will search all available repositories to look for the elasticsearch package and install it if not already installed.

Java is a prerequisite for elasticsearch and must be fully installed before attempting to install elasticsearch. Using the loop keyword rather than passing the list to name means that the command below will install java-1.7.0-openjdk before attempting to install elasticsearch:

- name: install java & elasticsearch 6.x
  yum:
    name: "{{ item }}"
    state: present
    update_cache: true
  loop:
    - java-1.7.0-openjdk
    - elasticsearch
  become: true

How to remove a yum repository and clean up the metadata cache

Removing a yum repository is as simple as passing the name and setting state: absent.

To ensure that the metadata cache is cleaned, you can run yum clean metadata with the command module. This can be set to run conditionally only when a package has actually been removed by using register on the task that removes the repo and when in the following command:

- name: remove elasticsearch 6.x repository
  yum_repository:
    name: elasticsearch-6.x
    state: absent
  become: true
  register: yum_repository_output

- name: clean yum metadata cache
  command: yum clean metadata
  args:
    warn: false
  when: yum_repository_output.changed
  become: true

Note that warn: false is recommended on the second task because Ansible will emit a warning if you try to run yum commands using the command module instead of the yum module:

[WARNING]: Consider using the yum module rather than running yum.  
  If you need to use command because yum is insufficient you can 
  add warn=False to this command task or set command_warnings=False 
  in ansible.cfg to get rid of this message.

How to capture yum_repository module output

Use the register keyword to capture the output of the yum_repository module.

- name: install elasticsearch 6.x rpm repository
  yum_repository:
    name: elasticsearch-6.x
    description: Elasticsearch repository for 6.x packages
    baseurl: https://artifacts.elastic.co/packages/6.x/yum
    gpgcheck: true
    gpgkey: https://artifacts.elastic.co/GPG-KEY-elasticsearch
  become: true
  register: yum_repository_output

- debug: var=yum_repository_output

The debug task above will output the following:

ok: [123.123.123.123] => {
    "yum_repository_output": {
        "changed": true,
        "diff": {
            "after": "[elasticsearch-6.x]\nbaseurl = https://artifacts.elastic.co/packages/6.x/yum\ngpgcheck = 1\ngpgkey = https://artifacts.elastic.co/GPG-KEY-elasticsearch\nname = Elasticsearch repository for 6.x packages\n\n",
            "after_header": "/etc/yum.repos.d/elasticsearch-6.x.repo",
            "before": "",
            "before_header": "/etc/yum.repos.d/elasticsearch-6.x.repo"
        },
        "failed": false,
        "repo": "elasticsearch-6.x",
        "state": "present"
    }
}

Further reading