Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

foreman_network

Puppet Module to configure network interfaces, routes and resolv.conf with Foreman ENC network interface data
Project URLRSS FeedReport issues

338 downloads

182 latest version

4.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.3.0 (latest)
  • 1.2.0
released Dec 5th 2023
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'markt-foreman_network', '1.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add markt-foreman_network
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install markt-foreman_network --version 1.3.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

markt/foreman_network — version 1.3.0 Dec 5th 2023

puppet-foreman_network

Table of Contents

Overview

This module configures network interfaces, network routes and resolv.conf from Foreman ENC (external node classifier) node parameters.

Basically it parses the foreman_interfaces and domainname node parameters from foreman and pass it to other puppet modules to configure the settings.

More information about foreman: https://theforeman.org/

Information about Puppet ENC (external node classifier): https://puppet.com/docs/puppet/latest/nodes_external.html

NOTE: This module is only compatible with systems based on RHEL7 and RHEL8. It does not provide native support for NetworkManager, legacy network components are required.

Usage

All parameters for the module are contained within the main class, so for any function of the module, set the options you want. All configuration parameters can be assigned hiera. The default values are also lookuped up by hiera. See the common usages below for examples.

Install and enable foreman_network

include foreman_network

Declare foreman_network

To get foreman_network up and running just declare the class.

class { 'foreman_network': }

Declare the class with default values:

class { 'foreman_network':
  nameservers                      => [],
  nameservers_merge                => true,
  manage_resolv_conf               => true,
  route_overrides                  => {},
  manage_network_interface_restart => true,
  manage_if_from_facts_only        => true,
  resolv_conf_path                 => '/etc/resolv.conf',
  resolver_options                 => [],
  debug                            => false,
  searchpath_merge                 => true,
  searchpath                       => [],
}

Using Hiera with default values:

foreman_network:
  nameservers: []
  nameservers_merge: true
  manage_resolv_conf: true
  route_overrides: {}
  manage_network_interface_restart: true
  manage_if_from_facts_only: true
  resolv_conf_path: /etc/resolv.conf
  resolver_options: []
  debug: false
  searchpath_merge: true
  searchpath: []

Configure nameservers

IMPORTANT: When the boot mode of the primary interface from foreman is a DHCP, the resolv.conf will be always unmanaged even when the parameter manage_resolv_conf is true.

Additional nameservers

Foreman passes 2 nameservers via node parameters: dns_primary (eg. 1.1.1.1) and dns_secondary (eg. 2.2.2.2).

With the following configuration additional nameservers will be added via an unique merge:

class { 'foreman_network':
  nameservers_merge  => true,
  nameservers        => [
    '1.1.1.1',
    '8.8.8.8',
    '4.4.4.4'
  ],
}

Using Hiera:

foreman_network:
  nameservers_merge: true
  nameservers:
    - 8.8.8.8
    - 4.4.4.4

The result in /etc/resolv.conf will be:

[...]
nameserver 1.1.1.1
nameserver 2.2.2.2
nameserver 8.8.8.8
nameserver 4.4.4.4
[...]

Custom nameservers

Use custom nameservers and ignore foreman nameservers with the following configuration

class { 'foreman_network':
  nameservers_merge  => false,
  nameservers        => [
    '8.8.8.8',
    '4.4.4.4'
  ],
}

Using Hiera:

foreman_network:
  nameservers_merge: false
  nameservers:
    - 8.8.8.8
    - 4.4.4.4

The result in /etc/resolv.conf will be:

[...]
nameserver 8.8.8.8
nameserver 4.4.4.4
[...]

Configure resolv options

Add some resolver options to /etc/resolv.conf

class { 'foreman_network':
  resolver_options => [
    'timeout:1',
    'rotate'
  ],
}

Using Hiera:

foreman_network:
  resolver_options:
    - timeout:1
    - rotate

If a top scope variable $resolver_options exists (e.g. from Foreman ENC) it will be merged into your defined options here. This way you can tune your settings according to your infrastructure.

Overwrite network routes

IMPORTANT: When the boot mode of the primary interface from foreman is a DHCP, all routes for this interface will be ignored IMPORTANT: When NetworkManager is enabled no static routes will be set

Add static route and overwrite the default gateway on interface eth0

class { 'foreman_network':
  route_overrides => {
    '0.0.0.0/0'   => {
      'ensure'    => 'present',
      'gateway'   => '10.241.60.253',
      'interface' => 'eth0',
      'netmask'   => '255.255.255.0',
      'network'   => '10.241.60.0',
    },
    '10.1.2.0/24' => {
      'ensure'    => 'present',
      'gateway'   => '10.1.2.254',
      'interface' => 'eth0',
      'netmask'   => '255.255.255.0',
      'network'   => '10.1.2.0',
    },
  }
}

Using Hiera:

foreman_network:
  route_overrides:
    0.0.0.0/24:
      ensure: present
      gateway: 10.241.60.253
      interface: eth0
      netmask: 255.255.255.0
      network: 10.241.60.0 
    10.1.2.0/24:
      ensure: present
      gateway: 10.1.2.254
      interface: eth0
      netmask: 255.255.255.0
      network: 10.1.2.0

Reference

See REFERENCE.md

Limitations

For a list of supported operating systems, see metadata.json

Development

This module uses puppet_litmus for development and acceptance testing.

Setup testing and development environment (MacOSX)

Install required software with brew

brew cask install docker
brew cask install puppetlabs/puppet/pdk
brew cask install puppet-bolt
brew install rbenv
rbenv init
echo 'eval "$(rbenv init -)"' >> $HOME/.zshrc
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
rbenv install 2.6.5

Install all needed gem dependencies:

./scripts/prepare_test_env.sh

Running acceptance tests

Create test environment:

./scripts/create_test_env.sh

Run the acceptance tests:

./scripts/run_tests.sh

Remove the test environment:

./scripts/remove_test_env.sh

Running unit tests

pdk test unit

Release Process

scripts/make-release

git push