README.md

Ansible Role jm1.cloudy.grub

This role helps with configuring GRUB from Ansible variables. Role variable grub_config defines a list of tasks which will be run by this role. Each task calls an Ansible module similar to tasks in roles or playbooks except that only few keywords such as when are supported. For example, to enable IOMMU for PCI devices (and remove other parameters), define variable grub_config in group_vars or host_vars as such:

grub_config:
- # Enable IOMMU for PCI devices
  # Ref.: https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
  ansible.builtin.lineinfile:
    path: /etc/default/grub
    regexp: '^GRUB_CMDLINE_LINUX_DEFAULT='
    line: 'GRUB_CMDLINE_LINUX_DEFAULT="iommu=pt intel_iommu=on"'

Once all tasks have been run and if anything has changed, then the GRUB configuration will be (re)generated and the system will be rebooted automatically to apply the changes.

Tested OS images

• Cloud image (amd64) of Debian 10 (Buster)
• Cloud image (amd64) of Debian 11 (Bullseye)
• Cloud image (amd64) of Debian 12 (Bookworm)
• Cloud image (amd64) of Debian 13 (Trixie)
• Cloud image (amd64) of CentOS 7 (Core)
• Cloud image (amd64) of CentOS 8 (Stream)
• Cloud image (amd64) of CentOS 9 (Stream)
• Cloud image (amd64) of Fedora Cloud Base 40
• Cloud image (amd64) of Ubuntu 18.04 LTS (Bionic Beaver)
• Cloud image (amd64) of Ubuntu 20.04 LTS (Focal Fossa)
• Cloud image (amd64) of Ubuntu 22.04 LTS (Jammy Jellyfish)
• Cloud image (amd64) of Ubuntu 24.04 LTS (Noble Numbat)

Available on Ansible Galaxy in Collection jm1.cloudy.

Requirements

This role uses module(s) from collection jm1.ansible. To install this collection you may follow the steps described in README.md using the provided requirements.yml.

Variables

Name	Default value	Required	Description
distribution_id	depends on operating system	false	List which uniquely identifies a distribution release, e.g. [ 'Debian', '10' ] for Debian 10 (Buster)
grub_config	[]	false	List of tasks to run 1 2 3, e.g. to edit /etc/default/grub on Debian

Dependencies

None.

Example Playbook

To enable IOMMU for PCI devices:

- hosts: all
  become: true
  vars:
    # Variables are listed here for convenience and illustration.
    # In a production setup, variables would be defined e.g. in
    # group_vars and/or host_vars of an Ansible inventory.
    # Ref.:
    # https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
    # https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
    grub_config:
    - # Enable IOMMU for PCI devices
      # Ref.: https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
      ansible.builtin.lineinfile:
        path: /etc/default/grub
        regexp: '^GRUB_CMDLINE_LINUX_DEFAULT='
        line: 'GRUB_CMDLINE_LINUX_DEFAULT="iommu=pt intel_iommu=on"'
  roles:
  - name: Manage GRUB2 configuration
    role: jm1.cloudy.grub
    tags: ["jm1.cloudy.grub"]

To enable Predictable Network Interface Names:

- hosts: all
  become: true
  vars:
    # Variables are listed here for convenience and illustration.
    # In a production setup, variables would be defined e.g. in
    # group_vars and/or host_vars of an Ansible inventory.
    # Ref.:
    # https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
    # https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
    grub_config:
    - # Enable Predictable Network Interface Names
      # Ref.: https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/
      lineinfile:
        path: /etc/default/grub
        regexp: '^GRUB_CMDLINE_LINUX_DEFAULT='
        line: 'GRUB_CMDLINE_LINUX_DEFAULT="biosdevname=1 net.ifnames=1"'
  roles:
  - name: Manage GRUB2 configuration
    role: jm1.cloudy.grub
    tags: ["jm1.cloudy.grub"]

To open consoles on tty0 and ttyS0 and enable verbose output which helps with debugging e.g. OpenStack instances:

- hosts: all
  become: true
  vars:
    # Variables are listed here for convenience and illustration.
    # In a production setup, variables would be defined e.g. in
    # group_vars and/or host_vars of an Ansible inventory.
    # Ref.:
    # https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
    # https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
    grub_config:
    - # Open consoles on tty0 and ttyS0 and enable verbose output
      # Inspired by Debian's OpenStack images
      # Ref.: https://cdimage.debian.org/cdimage/openstack/
      lineinfile:
        path: /etc/default/grub
        regexp: '^GRUB_CMDLINE_LINUX_DEFAULT='
        line: >-
          GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200 earlyprintk=ttyS0,115200 consoleblank=0
          systemd.show_status=true"
  roles:
  - name: Manage GRUB2 configuration
    role: jm1.cloudy.grub
    tags: ["jm1.cloudy.grub"]

For instructions on how to run Ansible playbooks have look at Ansible's Getting Started Guide.

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)

Footnotes

1. Useful Ansible modules in this context could be blockinfile, copy, file, lineinfile and template. ↩

2. Tasks will be executed with jm1.ansible.execute_module which supports keyword when only. ↩

3. Tasks will be executed with jm1.ansible.execute_module which supports modules and action plugins only. Some Ansible modules such as ansible.builtin.meta and ansible.builtin.{include,import}_{playbook,role,tasks} are core features of Ansible, in fact not implemented as modules and thus cannot be called from jm1.ansible.execute_module. Doing so causes Ansible to raise errors such as MODULE FAILURE\nSee stdout/stderr for the exact error. In addition, Ansible does not support free-form parameters for arbitrary modules, so for example, change from - debug: msg="" to - debug: { msg: "" }. ↩