Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

netplan

Manage netplan via Puppet
Project URLRSS FeedReport issues

816 downloads

233 latest version

5.0 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

  • 2.0.0 (latest)
  • 1.0.0
  • 0.1.3
  • 0.1.2
  • 0.1.1 (deleted)
  • 0.1.0
released Jan 3rd 2024
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, 2019.8.x
  • Puppet >= 6.21.0 < 9.0.0
  • ,

Start using this module

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

Add this module to your Puppetfile:

mod 'jmckenzie-netplan', '2.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add jmckenzie-netplan
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install jmckenzie-netplan --version 2.0.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

jmckenzie/netplan — version 2.0.0 Jan 3rd 2024

netplan

Table of Contents

  1. Description
  2. Setup - The basics of getting started with netplan
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.
  5. Development - Guide for contributing to the module

Description

This module is used to install and manage netplan.

Since netplan configuration files are simple YAML documents, the module provides a simple 1-to-1 mapping from a Puppet hash to netplan YAML.

Setup

What netplan affects

  • Netplan YAML files under /etc/netplan/

Beginning with netplan

To get started with netplan, you simply need to include the main class

include netplan

Usage

This module is best used by supplying data via Hiera. Generating netplan YAML files with resource statements, although possible, can result in very complex manifests.

The below example shows both methods, although it's strongly recommended to just use Hiera to form your netplan config.

Please note, the netplan::config resource automatically adds the top-level network key to generated YAML files. You only need to define the settings under that key.

Basic usage

Make sure to include netplan somewhere in your manifest. By default, this will only ensure that netplan is installed.

include netplan

You may want to merge netplan::configs from multiple hiera YAML files. Do this by including the deep merge lookup option

lookup_options:
  netplan::configs:
    merge: 'deep'

Provide Hiera data to build your inteneded netplan YAML file.

netplan::configs:
  example-config:
    settings:
      version: 2
      renderer: networkd
      ethernets:
        eth0:
          dhcp4: true

And here is the same config using a netplan::config resource instead

netplan::config { 'example-config': 
  settings => {
    version => 2,
    renderer => networkd,
    ethernets => {
      eth0 => {
        dhcp4 => true,
      },
    },
  },
}

Purge un-managed configs

You can control whether to purge un-managed configs under /etc/netplan/ using the main class.

Resource-like declaration

class {'netplan':
  purge_configs => true,
  purge_ignore  => '90-NM*', # Optionally ignore specific patterns when purging
}

Hiera

netplan::purge_configs: true
netplan::purge_ignore: '90-NM*' # Optionally ignore specific patterns when purging

Control priority of netplan YAML files

Netplan reads all YAML files under /etc/netplan/ and merges them to generate a single config. The order in which they are read determines the final config, if the same key appears in multiple files.

You can change the priority of a generated file as follows:

netplan::configs:
  example-config:
    priority: 10
    settings:
      version: 2
      renderer: networkd
  example-config-2:
    priority: 20
    settings:
      ethernets:
        eth0:
          dhcp4: true

The above will result in the following under /etc/netplan/

  • 10-example-config.yaml
  • 20-example-config-2.yaml

Disable automatic netplan apply

By default, this module will run netplan apply once resources have been applied. This may not be desirable in some situations. You can disable this with the following

class { 'netplan':
  apply => false,
}

Or do the same using Hiera

netplan::apply: false

Disabling netplan::apply will cause netplan get to be run instead. This acts as a form of validation check even though the config isn't applied immediately.

Please note that even when netplan::apply is disabled, to netplan YAML is still written to /etc/netplan/, so a reboot could cause network loss if the config is wrong.

Limitations

This module doesn't perform any comprehensive validation for the generated netplan YAML. It can only ensure the generated file is in YAML syntax. i.e. The ownus is on the sysadmin to ensure the generated config is valid for use with netplan.

Development

Please submit your contributions and issues to GitHub: https://github.com/jps-help/puppet-netplan