zehweh / puppet-netplan

Netplan Module for Ubuntu 18.04.

puppet-netplan

Table of Contents

1. Description
2. Requirements
3. Usage
4. Open vSwitch
5. Miscellaneous

Description

The netplan module manages and applies netplan configuration.

Requirements

• Puppet >= 4.0
• puppetlabs/stdlib
• puppetlabs/concat

Usage

Example with include / Hiera

To use the module with Hiera, you can include the netplan class in your Puppet code:

include netplan

Then, define the netplan configuration in your Hiera YAML file:

netplan::version: 2
netplan::renderer: networkd
netplan::purge_config: true
netplan::ethernets:
    eno1:
      dhcp4: yes
      addresses:
        - 192.168.0.125/16
      nameservers:
        search: [foo.local, bar.local]
        addresses: [8.8.8.8, 4.4.4.4]
      routes:
        - to: 10.10.0.1/16
          via: 10.20.0.1

Example using class

Alternatively, you can use the netplan class directly in your Puppet code:

  class { 'netplan':
    config_file   => '/etc/netplan/01-custom.yaml',
    ethernets     => {
      'ens5' => {
        'dhcp4' => false
      }
    },
    bridges       => {
       'br0' => {
          'dhcp4' => true,
          'interfaces' => [ens5]
       }
    },
    netplan_apply => true,
  }

Open vSwitch

The external_ids and other_config settings in the openvswitch property allow you to pass arbitrary configurations directly to Open vSwitch. To achieve this, you must use the configuration as a string and pay attention to proper indentation.

Example:

Suppose you want to configure Open vSwitch as follows:

    ens13:
      openvswitch:
        external-ids:
          iface-id: mylocaliface
        other-config:
          disable-in-band: false

To pass this configuration as a string in your Hiera file, follow this format:

    ens13:
      openvswitch:
        external_ids: |-1
                   iface-id: mylocaliface
        other_config: |-1
                   disable-in-band: false

Ensure that you maintain the correct indentation while providing the configuration as a string to ensure proper parsing by netplan.

Miscellaneous

For detailed information about each parameter, refer to the Netplan Documentation. The documentation for this module is based on the Netplan official reference.

puppet-netplan's Issues

can't configure certain point-to-point gre tunnels

The following gre configuration isn't handled properly by the netplan module:

    tun1:
      mode: "gre"
      local: "1.1.1.1"
      remote: "2.2.2.2"
      ttl: 255 # required when we need to route traffic through the tunnel
      addresses:
        - "172.31.0.1/32"
      mtu: 1440
      routes:
        - to: "172.31.0.2/32"
          scope: "link"

There are 3 issues with the needed configuration.
1- support for "ttl" value isn't present
2- on link route isn't supported as the "via" param is considered mandatory.
3- the "scope" value is ignore and not provided to netplan config file.

How to support extensive customer routes

Hi,
For $reasons we have various groups of servers with dozens of routes, which can change often enough that hard coding the list is going to result in issues.
Our current solution is a template which lips a list of addresses and inserts appropriate entries.
Looking at the code it doesn't look like the routes can be supplied separately or augmented dynamically.
I am looking at hacking in an extra routes option I can feed more dynamic data to, but wondered if there was an existing way - or an upstream acceptable change - I could leverage.
Thanks,
Karl

Defining default route fails

You can not define a default route with this module, like:

ens19:
dhcp4: false
optional: true
addresses:
- '192.168.0.11/24'
routes:
- to: '0.0.0.0/0'
via: '192.168.0.1'
nameservers:

because the string '0.0.0.0/0' is not recognized as a n IP address:

puppet agent -t
Info: Using configured environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Retrieving locales
Info: Loading facts
Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Netplan::Ethernets[ens19]: parameter 'routes' index 0 entry 'to' expects a Stdlib::IP::Address = Variant[Stdlib::IP::Address::V4 = Variant[Stdlib::IP::Address::V4::CIDR = Pattern[/\A([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}/([1-9]|[12][0-9]|3[0-2])?\z/], Stdlib::IP::Address::V4::Nosubnet = Pattern[/\A([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/]], Stdlib::IP::Address::V6 = Variant[Stdlib::IP::Address::V6::Full = Pattern[/\A[[:xdigit:]]{1,4}(:[[:xdigit:]]{1,4}){7}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/], Stdlib::IP::Address::V6::Compressed = Pattern[/\A:(:|(:[[:xdigit:]]{1,4}){1,7})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){1}(:|(:[[:xdigit:]]{1,4}){1,6})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){2}(:|(:[[:xdigit:]]{1,4}){1,5})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){3}(:|(:[[:xdigit:]]{1,4}){1,4})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){4}(:|(:[[:xdigit:]]{1,4}){1,3})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){5}(:|(:[[:xdigit:]]{1,4}){1,2})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){6}(:|(:[[:xdigit:]]{1,4}){1,1})(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){7}:(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/], Stdlib::IP::Address::V6::Alternative = Pattern[/\A([[:xdigit:]]{1,4}:){6}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){5}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){4}(:[[:xdigit:]]{1,4}){0,1}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){3}(:[[:xdigit:]]{1,4}){0,2}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){2}(:[[:xdigit:]]{1,4}){0,3}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A([[:xdigit:]]{1,4}:){1}(:[[:xdigit:]]{1,4}){0,4}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/, /\A:(:[[:xdigit:]]{1,4}){0,5}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}(/(1([01][0-9]|[2][0-8])|[1-9][0-9]|[1-9]))?\z/], Stdlib::IP::Address::V6::Nosubnet = Variant[Stdlib::IP::Address::V6::Nosubnet::Full = Pattern[/\A[[:xdigit:]]{1,4}(:[[:xdigit:]]{1,4}){7}\z/], Stdlib::IP::Address::V6::Nosubnet::Compressed = Pattern[/\A:(:|(:[[:xdigit:]]{1,4}){1,7})\z/, /\A([[:xdigit:]]{1,4}:){1}(:|(:[[:xdigit:]]{1,4}){1,6})\z/, /\A([[:xdigit:]]{1,4}:){2}(:|(:[[:xdigit:]]{1,4}){1,5})\z/, /\A([[:xdigit:]]{1,4}:){3}(:|(:[[:xdigit:]]{1,4}){1,4})\z/, /\A([[:xdigit:]]{1,4}:){4}(:|(:[[:xdigit:]]{1,4}){1,3})\z/, /\A([[:xdigit:]]{1,4}:){5}(:|(:[[:xdigit:]]{1,4}){1,2})\z/, /\A([[:xdigit:]]{1,4}:){6}(:|(:[[:xdigit:]]{1,4}){1,1})\z/, /\A([[:xdigit:]]{1,4}:){7}:\z/], Stdlib::IP::Address::V6::Nosubnet::Alternative = Pattern[/\A([[:xdigit:]]{1,4}:){6}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A([[:xdigit:]]{1,4}:){5}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A([[:xdigit:]]{1,4}:){4}(:[[:xdigit:]]{1,4}){0,1}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A([[:xdigit:]]{1,4}:){3}(:[[:xdigit:]]{1,4}){0,2}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A([[:xdigit:]]{1,4}:){2}(:[[:xdigit:]]{1,4}){0,3}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A([[:xdigit:]]{1,4}:){1}(:[[:xdigit:]]{1,4}){0,4}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/, /\A:(:[[:xdigit:]]{1,4}){0,5}:([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])){3}\z/]]]] value, got String (file: /etc/puppet/code/environments/production/modules/netplan/manifests/init.pp, line: 70) on node xxxxx
Warning: Not using cache on failed catalog
Error: Could not retrieve catalog; skipping run

Change Permissions for netplan Directory

I have been implementing some 802.1x config and was wondering if it were possible to secure the permissions on the netplan directory as I have the client_key_password visible in the netplan file. I have made the following amendment to the init.pp file to ensure world readable bit is removed, which seems to work.

I thought it worth mentioning to get another perspective to make sure this isn't going break something elsewhere. I imagine it could be a little confusing for people that aren't dealing with 802.1x config, but it seems ideal to secure the password a little. I know that it's fairly useless having the password if you can't get the key, but seemed logical to protect it still.

  if $purge_config {
    File['/etc/netplan'] {
      purge   => true,
      recurse => true,
      force   => true,
      mode    => '740',
    }
  }

Would be good to any thoughts.
Thanks for the plugin
Cheers

Netplan apply fails due to no path specified

Error: Validation of Exec[netplan_apply] failed: 'netplan apply' is not qualified and no path was specified. Please qualify the command or specify a path. (file: /etc/puppet/code/environments/production/modules/netplan/manifests/init.pp, line: 42)

Netplan Apply should have a valid path, or be a path qualified command.

support for tunnel interfaces

netplan also support tunnels interfaces but this module doesn't.
See: https://netplan.io/reference#properties-for-device-type-tunnels

Unrecognized bond parameters

Hello. I am trying to use this module for an Ubuntu22 installation using 2 interfaces in bond. For the bond, I have the following in my server yaml

netplan::bonds:
    bond0:
      interfaces: [eth0, eth1]
      mtu: 9000
      parameters:
        mode: '802.3ad'
        mii-monitor-interval: '100'
        transmit-hash-policy: 'layer3+4'
        ad-select: 'count'
        lacp-rate: 'fast'

But out of all the parameters, only the mode: '802.3ad' is being recognized and applied to the netplan config properly. For the rest, I get the following error in the puppet run for the rest:

Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Netplan::Bonds[bond0]:
  parameter 'parameters' unrecognized key 'mii-monitor-interval'
  parameter 'parameters' unrecognized key 'transmit-hash-policy'
  parameter 'parameters' unrecognized key 'ad-select'
  parameter 'parameters' unrecognized key 'lacp-rate' (file: /etc/puppetlabs/code/environments/production/modules/netplan/manifests/init.pp, line: 136) on node host5.tbc.cloudsigma.com

I do see all those paramenters described in templates/bonds.epp of this module, but they do not seem to be recognized for some reason.

Am I doing something wrong declaring those parameters in my yaml? I have also tried declaring the parameters one by one, but the same error occurs.

As for my setup, I am using puppet7 with Foreman and version 2 of this module. The host server is an Ubuntu22 server installation

'via' field should not be mandatory if scope link is defined

netplan supports a configuration like this:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      match:
        macaddress: <foo>
      dhcp4: true
      routes:
        - to: 10.212.132.0/24
          scope: 'link'
          table: 1

This is not possible with this module, because the "via" field is mandatory. Really not sure what's the best way to fix it, but it should be possible to create a config like this

pdk validate is showing few errors

I noted few errors, which I'd like to clean.
please accept my PR to fix these minor issues.

auth parameters not recognised

'zehweh-netplan' version '1.0.0'
Puppet version 6.25.0
Ubuntu 20.04.3

Not sure if this is a bug or my syntax is off, but I can't find an accurate example in the documentation for my use-case.

With the below puppet hiera data:

netplan::version: 2
netplan::renderer: NetworkManager
netplan::ethernets:
  TEST-WIRED:
    dhcp4: true
    match:
      name: eth*
    auth:
      key-management: 802.1x
      method: tls
      identity: "%{trusted.certname}"
      ca-certificate: /etc/ssl/certs/ca-certificates.crt
      client-certificate: "/etc/puppetlabs/puppet/ssl/certs/%{trusted.certname}.pem"
      client-key: "/etc/puppetlabs/puppet/ssl/private_keys/%{trusted.certname}.pem"
      client-key-password: "null"
netplan::wifis:
  TEST-WIFI:
    dhcp4: true
    match:
      name: wl*
    access-points:
      TEST1:
        auth:
          key-management: eap
          method: tls
          identity: "%{trusted.certname}"
          ca-certificate: /etc/ssl/certs/ca-certificates.crt
          client-certificate: "/etc/puppetlabs/puppet/ssl/certs/%{trusted.certname}.pem"
          client-key: "/etc/puppetlabs/puppet/ssl/private_keys/%{trusted.certname}.pem"
          client-key-password: "null"
netplan::config_file: '/etc/netplan/99-test-netplan.yaml'

I receive the following error when applying the catalogue:

Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Netplan::Ethernets[EBI-WIRED]:
parameter 'auth' unrecognized key 'key-management'
parameter 'auth' unrecognized key 'ca-certificate'
parameter 'auth' unrecognized key 'client-certificate'
parameter 'auth' unrecognized key 'client-key'
parameter 'auth' unrecognized key 'client-key-password' (file: /etc/puppetlabs/code/environments/jamesps_workstation_nac/modules/netplan/manifests/init.pp, line: 85) on node ubu20-n-495753433f.ebi.ac.uk

The same data structure works correctly when written directly to a file in /etc/netplan/ and our test client is able to authenticate.

Exec['netplan_apply'] notifies on any change with $netplan_apply=false

Right now Exec['netplan_apply'] executes on any change in the class because of class updates.

There are two options for avoiding it:

1. move this exec to the special class (e.g. netplan::apply) and notify this class. Notify of class netplan will not affect it.
2. make this exec optional and not create it if $netplan_apply=false.

Migrate to PDK

Thank you for your awesome work!

I can suggest only to migrate current codebase to Puppet Development Kit (PDK) which will be helpful overall.

Also, unit tests should be very useful.

More info:
https://puppet.com/docs/pdk/1.x/pdk.html
https://github.com/puppetlabs/pdk
https://puppet.com/download-puppet-development-kit
https://puppet.com/blog/develop-modules-faster-new-puppet-development-kit

release tags missing

In the Puppet Forge there are a number of releases listed (https://forge.puppet.com/modules/zehweh/netplan/readme).

But there in the git repository I do not see what code version (commit) corresponds to what release.

Thus I suggest that these commits should be tagged with the respective release version.

Add use-domains option to DHCP overrides

We would like to use the use-domains option as specified in https://netplan.io/reference/#dhcp-overrides, but that doesn't exist in this module yet:

Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Netplan::Ethernets[enp2s0]: parameter 'dhcp4_overrides' unrecognized key 'use_domains' (file: /etc/puppetlabs/code/environments/production/modules/netplan/manifests/init.pp, line: 85) on node ...

Can you add that parameter in? I can create a PR for it if you want me to.

Add support for new options from netplan 0.105

Netplan added support for wireguard tunnels in 0.100 and vxlan tunnels in 0.105. A tunnel ttl was also added in 0.103. There's also some additional fields for other interface types that have been added that aren't supported by this module. The reference does list the version the new fields were added in: https://netplan.io/reference

No way to add configuration snippets.

At the moment it looks like there's no way to add new configuration snippets to the overall netplan config - you get a single static definition via hiera, or you get a single definition at the point you define the class, but there's no way to add more configuration at a later point or anywhere else in the manifest.

I think, given the way that netplan works with later files in the config amending previous ones, it should be entirely possible to support this kind of thing - simply adding a new file with the desired amendments, which sorts later and hence overrides and amends the earlier config.

I'd suggest implementing this as a defined type, taking a priority value that would specify the ordering and then taking the same config hash that the main class takes, and would then output a file named /etc/netplan/<priority>-<title>.yaml.

I'll see if I can find time to write a pull request implementing this myself, but I don't know when I'll be able to get to it.