Ansible yum Module: Manage RPM Packages on RHEL/CentOS (Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible yum and dnf modules. Install, update, remove RPM packages, manage repositories, pin versions, and handle package groups on RHEL.

The ansible.builtin.yum and ansible.builtin.dnf modules manage RPM packages on Red Hat-based systems (RHEL, CentOS, Fedora, AlmaLinux, Rocky Linux). This guide covers installation, updates, removal, repository management, and best practices.

yum vs dnf: Which Module to Use?

System	Package Manager	Ansible Module
RHEL 7, CentOS 7	yum	`ansible.builtin.yum`
RHEL 8/9, CentOS Stream 8/9	dnf	`ansible.builtin.dnf`
AlmaLinux 8/9, Rocky Linux 8/9	dnf	`ansible.builtin.dnf`
Fedora	dnf	`ansible.builtin.dnf`

> Tip: Use ansible.builtin.package for cross-platform playbooks — it auto-detects the package manager.

Install Packages

Single Package

- name: Install nginx
  ansible.builtin.yum:
    name: nginx
    state: present

Multiple Packages

- name: Install web server stack
  ansible.builtin.yum:
    name:
      - nginx
      - php-fpm
      - php-mysqlnd
      - redis
    state: present

Specific Version

- name: Install specific version
  ansible.builtin.yum:
    name: nginx-1.24.0-1.el9
    state: present

# Or with version comparison
- name: Install minimum version
  ansible.builtin.yum:
    name: "nginx >= 1.24"
    state: present

Latest Version

- name: Install or update to latest
  ansible.builtin.yum:
    name: nginx
    state: latest

From a URL or Local RPM

- name: Install from URL
  ansible.builtin.yum:
    name: https://example.com/myapp-1.0.0.rpm
    state: present
    disable_gpg_check: true

- name: Install local RPM
  ansible.builtin.yum:
    name: /tmp/myapp-1.0.0.rpm
    state: present

Update Packages

Update Specific Package

- name: Update nginx to latest
  ansible.builtin.yum:
    name: nginx
    state: latest

Update All Packages

- name: Update all packages (yum update)
  ansible.builtin.yum:
    name: '*'
    state: latest

# Security updates only
- name: Apply security updates
  ansible.builtin.yum:
    name: '*'
    state: latest
    security: true

Update with Exclusions

- name: Update all except kernel
  ansible.builtin.yum:
    name: '*'
    state: latest
    exclude:
      - kernel*
      - centos-release*

Remove Packages

- name: Remove package
  ansible.builtin.yum:
    name: httpd
    state: absent

- name: Remove multiple packages
  ansible.builtin.yum:
    name:
      - httpd
      - mod_ssl
      - mod_php
    state: absent

Package Groups

# Install a package group
- name: Install Development Tools
  ansible.builtin.yum:
    name: "@Development Tools"
    state: present

# DNF syntax
- name: Install development tools (dnf)
  ansible.builtin.dnf:
    name: "@development-tools"
    state: present

# Remove a group
- name: Remove development tools
  ansible.builtin.yum:
    name: "@Development Tools"
    state: absent

Repository Management

Enable/Disable Repos During Install

- name: Install from EPEL
  ansible.builtin.yum:
    name: htop
    enablerepo: epel
    state: present

- name: Install from specific repo only
  ansible.builtin.yum:
    name: nginx
    enablerepo: nginx-stable
    disablerepo: '*'
    state: present

Add a Repository

- name: Add EPEL repository
  ansible.builtin.yum:
    name: epel-release
    state: present

# Or use yum_repository module for custom repos
- name: Add custom repository
  ansible.builtin.yum_repository:
    name: myapp
    description: My Application Repository
    baseurl: https://rpm.example.com/el$releasever/$basearch/
    gpgcheck: true
    gpgkey: https://rpm.example.com/RPM-GPG-KEY-myapp
    enabled: true

- name: Add Nginx repo
  ansible.builtin.yum_repository:
    name: nginx-stable
    description: Nginx Stable Repository
    baseurl: http://nginx.org/packages/centos/$releasever/$basearch/
    gpgcheck: true
    gpgkey: https://nginx.org/keys/nginx_signing.key
    enabled: true
    module_hotfixes: true

Remove a Repository

- name: Remove custom repository
  ansible.builtin.yum_repository:
    name: myapp
    state: absent

DNF Module (RHEL 8/9)

The dnf module has the same interface as yum with additional features:

- name: Install with dnf
  ansible.builtin.dnf:
    name: nginx
    state: present

# DNF modules (modularity)
- name: Enable PHP 8.2 module stream
  ansible.builtin.dnf:
    name: '@php:8.2'
    state: present

# Install with specific module profile
- name: Install Node.js 20
  ansible.builtin.dnf:
    name: '@nodejs:20/common'
    state: present

DNF Modules (Modularity)

- name: Reset PHP module
  ansible.builtin.command: dnf module reset php -y
  changed_when: true

- name: Enable PHP 8.2 stream
  ansible.builtin.command: dnf module enable php:8.2 -y
  changed_when: true

- name: Install PHP packages
  ansible.builtin.dnf:
    name:
      - php
      - php-fpm
      - php-mysqlnd
      - php-opcache
    state: present

Cross-Platform Package Management

- name: Install web server (cross-platform)
  ansible.builtin.package:
    name: nginx
    state: present
  # Works on yum, dnf, apt, zypper, etc.

# Or use conditionals
- name: Install on RHEL
  ansible.builtin.yum:
    name: "{{ rhel_packages }}"
    state: present
  when: ansible_os_family == 'RedHat'

- name: Install on Debian
  ansible.builtin.apt:
    name: "{{ debian_packages }}"
    state: present
  when: ansible_os_family == 'Debian'

Cache Management

# Clean yum cache
- name: Clean yum cache
  ansible.builtin.command: yum clean all
  changed_when: true

# Or with the module
- name: Clean cache and install
  ansible.builtin.yum:
    name: myapp
    state: latest
    update_cache: true

Real-World Patterns

Complete Server Setup

- name: Configure RHEL web server
  hosts: webservers
  become: true
  vars:
    packages:
      - nginx
      - php-fpm
      - php-mysqlnd
      - redis
      - certbot
      - python3-certbot-nginx

  tasks:
    - name: Install EPEL
      ansible.builtin.yum:
        name: epel-release
        state: present

    - name: Install packages
      ansible.builtin.yum:
        name: "{{ packages }}"
        state: present

    - name: Start and enable services
      ansible.builtin.systemd:
        name: "{{ item }}"
        state: started
        enabled: true
      loop:
        - nginx
        - php-fpm
        - redis

Pin Package Version

- name: Install specific version
  ansible.builtin.yum:
    name: nginx-1.24.0-1.el9
    state: present
    allow_downgrade: true

- name: Prevent package from being updated
  ansible.builtin.yum:
    name: yum-plugin-versionlock
    state: present

- name: Lock package version
  ansible.builtin.command: yum versionlock add nginx
  changed_when: true

FAQ

What is the difference between yum and dnf modules in Ansible?

The yum module is for RHEL 7/CentOS 7 systems. The dnf module is for RHEL 8+/Fedora and includes support for modularity streams. Both have the same basic interface. Use ansible.builtin.package for cross-platform compatibility.

How do I install a specific package version with yum?

Specify the version in the name: name: nginx-1.24.0-1.el9. Add allow_downgrade: true if you need to downgrade. Use yum versionlock to prevent automatic updates.

How do I update all packages except the kernel?

Use name: '' with state: latest and exclude: ['kernel'] to update everything while skipping kernel packages.

Should I use yum, dnf, or package module?

Use ansible.builtin.package for cross-platform playbooks. Use yum or dnf when you need module-specific features like enablerepo, exclude, or modularity streams.

How do I add a custom yum repository?

Use the ansible.builtin.yum_repository module to create repo files in /etc/yum.repos.d/. Specify name, baseurl, gpgcheck, gpgkey, and enabled parameters.

Conclusion

yum for RHEL 7/CentOS 7, dnf for RHEL 8+/Fedora
package for cross-platform playbooks
state: present = install, latest = update, absent = remove
Use yum_repository module to manage repos
Always use become: true for package operations

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton