network_interface

WARNING: This role can be dangerous to use. If you lose network connectivity to your target host by incorrectly configuring your networking, you may be unable to recover without physical access to the machine.

This roles enables users to configure various network components on target machines. The role can be used to configure:

Ethernet interfaces
Bridge interfaces
Bonded interfaces
VLAN tagged interfaces
Network routes

Requirements

This role requires Ansible 1.4 or higher, and platform requirements are listed in the metadata file.

Role Variables

The variables that can be passed to this role and a brief description about them are as follows:

Variable	Required	Default	Comments
`network_ether_interfaces`	No	`[]`	The list of ethernet interfaces to be added to the system.
`network_bridge_interfaces`	No	`[]`	The list of bridge interfaces to be added to the system.
`network_bond_interfaces`	No	`[]`	The list of bonded interfaces to be added to the system.
`network_vlan_interfaces`	No	`[]`	The list of vlan interfaces to be added to the system.

The different types of interfaces can be configured with following variables:

Ethernet

Variable	OS	Is Required
device	*	Yes
type	RedHat	Optional
ADDR VARS	*	-

Bond

Variable	OS	Is Required
device	*	Yes
bond_mode	*	Yes
bond_slaves	Debian	Yes
bond_slaves	RedHat	For Auto Config
type	RedHat	For Manual Config
BOND VARS	*	-

Bond Slave (manual config)

Variable	OS	Is Required
device	*	Yes
master	*	Yes
type	RedHat	Optional

Bridge

Variable	OS	Is Required
device	*	Yes
bridge_ports	*	Optional
type	RedHat	For Manual Config
?	Debian	For Manual Config
BRIDGE VARS	*	-

Bridge Port (manual config)

Variable	OS	Is Required
device	*	Yes
bridge	RedHat	For Manual Config
type	RedHat	Optional

VLAN

Variable	OS	Is Required
device	*	Yes
vlan	Redhat	For Manual Config
vlan_physdev	RedHat	Optional
vlan_id	RedHat	Optional
reorder_hdr	RedHat	Optional

ADDR VARS

Variable	OS
bootproto	*
address	*
netmask	*
gateway	*
cidr	Debian
network	Debian
broadcast	Debian
ipv6_options	Debian
ipv6_address	*
ipv6_gateway	*
name	RedHat
nm_controlled	RedHat
defroute	RedHat
stp	RedHat
mtu	RedHat
firewalld_zone	RedHat
route	Debian
dns_nameservers	Debian
dns_search	Debian
dns_domain	Debian
options	Debian
hwaddress	*

BOND VARS

Variable	OS
bond_miimon	*
bond_lacp_rate	Debian
bond_xmit_hash_policy	*
bond_downdelay	*
bond_updelay	*
bond_use_carrier	*
bond_primary	*
bond_primary_reselect	Debian
bond_bond_ad_select	Debian
bond_arp_interval	Debian
bond_arp_ip_target	Debian
bond_arp_validate	Debian
bond_num_grat_arp	Debian
bond_num_unsol_na	Debian
bond_active_slave	Debian
bond_extra_opts	RedHat

BRIDGE VARS

Variable	OS
bridge_ageing	Debian
bridge_bridgeprio	Debian
bridge_fd	Debian
bridge_gcint	Debian
bridge_hello	Debian
bridge_maxage	Debian
bridge_maxwait	Debian
bridge_pathcost	Debian
bridge_portprio	Debian
bridge_stp	Debian
bridge_waitport	Debian

Combinations

Every type of interface can be configured using network_ether_interfaces using the variables of the following:

ethernet
vlan
bond
bond slave
bridge
bridge port
vlan+ethernet
bond+ethernet
bridge+ethernet
bond+bridge port
ethernet+bridge port
vlan+bridge port

Examples

Debian (not RedHat) network configurations can optionally use CIDR notation for IPv4 addresses instead of specifying the address and subnet mask separately. It is required to use CIDR notation for IPv6 addresses on Debian.

IPv4 example with CIDR notation:

      cidr: 192.168.10.18/24
      # OPTIONAL: specify a gateway for that network, or auto for network+1
      gateway: auto

IPv4 example with classic IPv4:

      address: 192.168.10.18
      netmask: 255.255.255.0
      network: 192.168.10.0
      broadcast: 192.168.10.255
      gateway: 192.168.10.1

If you want to use a different MAC Address for your Interface, you can simply add it.

      hwaddress: aa:bb:cc:dd:ee:ff

On some rare occasion it might be good to set whatever option you like. Therefore it is possible to use

      options:
          - "up /execute/my/command"
          - "down /execute/my/other/command"

and the IPv6 version

      ipv6_options:
          - "up /execute/my/command"
          - "down /execute/my/other/command"

Configure eth1 and eth2 on a host with a static IP and a dhcp IP. Also define static routes and a gateway.

    - hosts: myhost
      roles:
        - role: network
          network_ether_interfaces:
           - device: eth1
             bootproto: static
             cidr: 192.168.10.18/24
             gateway: auto
             route:
              - network: 192.168.200.0
                netmask: 255.255.255.0
                gateway: 192.168.10.1
              - network: 192.168.100.0
                netmask: 255.255.255.0
                gateway: 192.168.10.1
           - device: eth2
             bootproto: dhcp

Note: it is not required to add routes, default route will be added automatically.

Configure a bridge interface with multiple NIcs added to the bridge.

    - hosts: myhost
      roles:
        - role: network
          network_bridge_interfaces:
            - device: br1
              type: bridge
              cidr: 192.168.10.10/24
              bridge_ports: [eth1, eth2]

              # Optional values
              bridge_ageing: 300
              bridge_bridgeprio: 32768
              bridge_fd: 15
              bridge_gcint: 4
              bridge_hello: 2
              bridge_maxage: 20
              bridge_maxwait: 0
              bridge_pathcost: "eth1 100"
              bridge_portprio: "eth1 128"
              bridge_stp: "on"
              bridge_waitport: "5 eth1 eth2"

Note: Routes can also be added for this interface in the same way routes are added for ethernet interfaces.

Configure a bond interface with an "active-backup" slave configuration.

    - hosts: myhost
      roles:
        - role: network
          network_bond_interfaces:
            - device: bond0
              address: 192.168.10.128
              netmask: 255.255.255.0
              bond_mode: active-backup
              bond_slaves: [eth1, eth2]

              # Optional values
              bond_miimon: 100
              bond_lacp_rate: slow
              bond_xmit_hash_policy: layer3+4

Configure a bonded interface with "802.3ad" as the bonding mode and IP address obtained via DHCP.

    - hosts: myhost
      roles:
        - role: network
          network_bond_interfaces:
            - device: bond0
              bootproto: dhcp
              bond_mode: 802.3ad
              bond_miimon: 100
              bond_slaves: [eth1, eth2]
              bond_ad_select: 2

Configure a VLAN interface with the vlan tag 2 for an ethernet interface

    - hosts: myhost
      roles:
        - role: network
          network_ether_interfaces:
           - device: eth1
             bootproto: static
             cidr: 192.168.10.18/24
             gateway: auto
          network_vlan_interfaces:
           - device: eth1.2
             bootproto: static
             cidr: 192.168.20.18/24

It's also possible to configure all types of interfaces manually.

network_ether_interfaces:
  - device: eth0
    master: bond0
  - device: eth1
    master: bond0
  - device: bond0
    type: Bond
    bond_mode: 802.3ad

Configure a bridge interface on a bond interface. The bond must be configured.

network_bond_interfaces:
  - device: bond0
    bridge: br0
    bond_mode: 802.3ad
    bond_miimon: 100
    bond_slaves: [eth0, eth1]

network_bridge_interfaces:
  - device: br0
    type: Bridge
    address: 192.168.10.18
    netmask: 255.255.255.0
    gateway: 192.168.10.1
    bridge_ports: [bond0]

The same as the above but completely manually.

network_ether_interfaces:
  - device: eth0
    master: bond0
  - device: eth1
    master: bond0
  - device: bond0
    type: Bond
    bridge: br0
    bond_mode: 802.3ad
    bond_miimon: 100
  - device: br0
    type: Bridge
    address: 192.168.10.18
    netmask: 255.255.255.0
    gateway: 192.168.10.1

Example of creating a vlan on a bond interface.

network_ether_interfaces:
  - device: bond0.201
    vlan: True
    address: 192.168.100.78
    netmask: 255.255.255.0
    gateway: 192.168.100.1

network_bond_interfaces:
  - device: bond0
    bond_mode: 802.3ad
    bond_miimon: 100
    bond_slaves: [eth0, eth1]

All the above examples show how to configure a single host, The below example shows how to define your network configurations for all your machines.

Assume your host inventory is as follows:

/etc/ansible/hosts

    [dc1]
    host1
    host2

Describe your network configuration for each host in host vars:

host_vars/host1

    network_ether_interfaces:
           - device: eth1
             bootproto: static
             address: 192.168.10.18
             netmask: 255.255.255.0
             gateway: 192.168.10.1
             route:
              - network: 192.168.200.0
                netmask: 255.255.255.0
                gateway: 192.168.10.1
    network_bond_interfaces:
            - device: bond0
              bootproto: dhcp
              bond_mode: 802.3ad
              bond_miimon: 100
              bond_slaves: [eth2, eth3]

host_vars/host2

    network_ether_interfaces:
           - device: eth0
             bootproto: static
             address: 192.168.10.18
             netmask: 255.255.255.0
             gateway: 192.168.10.1

If resolvconf package should be used, it is possible to add some DNS configurations

      dns-nameserver: [ "8.8.8.8", "8.8.4.4" ]
      dns-search: "search.mydomain.tdl"
      dns-domain: "mydomain.tdl"

You can add IPv6 static IP configuration on Ethernet, Bond or Bridge interfaces

      ipv6_address: "aaaa:bbbb:cccc:dddd:dead:beef::1/64"
      ipv6_gateway: "aaaa:bbbb:cccc:dddd::1"

Create a playbook which applies this role to all hosts as shown below, and run the playbook. All the servers should have their network interfaces configured and routed updated.

    - hosts: all
      roles:
        - role: network

This role can also optionally add network interfaces to firewalld zones. The core firewalld module (http://docs.ansible.com/ansible/latest/firewalld_module.html) can perform the same function, so if you make use of both modules then your playbooks may not be idempotent. Consider this case, where only the firewalld module is used:

network_interface role runs; with no firewalld_zone host var set then any ZONE line will be removed from ifcfg-*
firewalld module runs; adds a ZONE line to ifcfg-*
On the next playbook run, the network_interface role runs and removes the ZONE line again, and so the cycle repeats.

In order for this role to manage firewalld zones, the system must be running a RHEL based distribution, and using NetworkManager to manage the network interfaces. If those criteria are met, the following example shows how to add the eth0 interface to the public firewalld zone:

       - device: eth0
         bootproto: static
         address: 192.168.10.18
         netmask: 255.255.255.0
         gateway: 192.168.10.1
         firewalld_zone: public

Note: Ansible needs network connectivity throughout the playbook process, you may need to have a control interface that you do not modify using this method while changeing IP Addresses so that Ansible has a stable connection to configure the target systems. All network changes are done within a single generated script and network connectivity is only lost for few seconds.

Dependencies

python-netaddr

License

BSD

Author Information

This project was originally created by Benno Joy.

Debian upgrades by:

Martin Verges (croit, GmbH)

RedHat upgrades by:

Eric Anderson (Avi Networks, Inc.)
Luke Short (Red Hat, Inc.)
Wei Tie, (Cisco Systems, Inc.)

The full list of contributors can be found here.

martinverges / ansible.network_interface Goto Github PK

ansible.network_interface's Introduction