power_network_bridge – Manages a Virtual Network Bridge on an IBM Power HMC managed system

Synopsis 

Retrieves information about all Virtual Network Bridges on the managed system.

Creates a Virtual Network Bridge backed by one or two Shared Ethernet Adapters.

Updates an existing Virtual Network Bridge identified by virtual_network_name.

Deletes a Virtual Network Bridge identified by virtual_network_name.

Requirements 

The below requirements are needed on the host that executes this module.

Python >= 3.9

Parameters 

hmc_host (True, str, None)
The IP address or hostname of the HMC.

hmc_auth (True, dict, None)
Username and Password credential of the HMC.

username (True, str, None)
Username of the HMC to login.

password (optional, str, None)
Password of the HMC.

system_name (True, str, None)
Name of the managed system (e.g. hmc-zz1).

Accepts an MTMS string (9009-42A*XXXXXXX) as well.

virtual_network_name (optional, str, None)
Name of an existing untagged Virtual Network on the managed system.

Required when state=present, state=update, or state=absent.

The network must have TaggedNetwork=false on the HMC.

Its VLAN ID is used as the bridge Port VLAN ID (PVID).

shared_ethernet_adapter (optional, dict, None)
Configuration block for the Virtual Network Bridge.

Required when state=present or state=update.

load_balancing (optional, bool, None)
Enable load-balancing across VIOSes.

Requires secondary_vios to be configured.

addition_pvid (optional, int, None)
The Port VLAN ID for the secondary load group, used when load_balancing=true.

When load_balancing is enabled the HMC creates a second LoadGroup element; this parameter sets its PortVLANID.

Must be between 1 and 4094 inclusive and must differ from the primary PVID derived from virtual_network_name.

Ignored when load_balancing=false.

jumbo_frames (optional, bool, None)
Enable 9000-byte jumbo frames on the Shared Ethernet Adapter.

Valid only when state=present.

large_send (optional, bool, None)
Enable TCP large-send offload on the Shared Ethernet Adapter.

Valid only when state=present or state=update.

qos_mode (optional, str, None)
Quality-of-service mode on the Shared Ethernet Adapter.

disabled turns off QoS.

loose applies best-effort QoS prioritisation.

strict enforces strict priority queuing.

primary_vios (optional, dict, None)
Primary VIOS that hosts the Shared Ethernet Adapter.

Required when state=present. Validated in code.

name (optional, str, None)
Name of the primary VIOS partition (e.g. VIOS-test-02).

Required when state=present.

Not allowed when state=update — the primary VIOS cannot be changed after bridge creation.

backing_device (optional, str, None)
Physical Ethernet adapter on the VIOS used as the SEA backing device (e.g. ent2).

Required by the HMC — the SEA cannot be created without a backing device.

Required when state=present. Can be changed via state=update.

high_availability_mode (optional, str, None)
High-availability mode for the primary SEA.

disabled turns off HA mode.

auto lets the HMC choose the active SEA automatically.

standby keeps this SEA in standby until the active fails.

Only valid when state=update and the live bridge has two VIOSes (FailoverEnabled=true).

secondary_vios (optional, dict, None)
Secondary VIOS for SEA failover.

When present on state=present, failover is automatically enabled.

When omitted on state=present, the bridge is created without failover.

On state=update, can be used to add a second VIOS to a single-VIOS bridge.

name (optional, str, None)
Name of the secondary VIOS partition (e.g. VIOS-test-01).

Required when secondary_vios is configured for state=present.

Required when state=update while enabling load-balancing or adding a new secondary VIOS to an existing single-VIOS bridge.

backing_device (optional, str, None)
Physical Ethernet adapter on the VIOS used as the secondary SEA backing device (e.g. ent3).

Required by the HMC when secondary_vios is configured.

Can be changed via state=update.

high_availability_mode (optional, str, None)
High-availability mode for the secondary SEA.

disabled turns off HA mode.

auto lets the HMC choose the active SEA automatically.

standby keeps this SEA in standby until the active fails.

Only valid when state=update and the live bridge has two VIOSes (FailoverEnabled=true).

tagged_virtual_networks (optional, list, None)
List of load-group assignments, each mapping a LoadGroup PVID to the Virtual Network names that should be linked to it.

Only valid when state=update.

Each list entry is a single-key dict where the key is the LoadGroup Port VLAN ID (integer) and the value is a list of existing tagged Virtual Network names, e.g. [{72: ['vn1', 'vn2']}, {75: ['vn3']}].

Networks already linked to the target LoadGroup are silently skipped (idempotent).

Each Virtual Network must already exist on the managed system and must have TaggedNetwork=true.

state (True, str, None)
facts retrieves information about all Virtual Network Bridges.

present creates the Virtual Network Bridge if it does not already exist.

update modifies an existing Virtual Network Bridge identified by virtual_network_name. Updatable fields are failover_enabled, load_balancing, jumbo_frames, large_send, qos_mode, addition_pvid (when enabling load-sharing), per-VIOS high_availability_mode, and tagged_virtual_networks (per LoadGroup, keyed by PVID).

absent deletes the Virtual Network Bridge identified by virtual_network_name.

Examples 

- name: Get all Virtual Network Bridge facts
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    state: facts

- name: Create a Virtual Network Bridge with failover (two VIOSes)
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    virtual_network_name: <virtual_network_name>
    shared_ethernet_adapter:
      load_balancing: false
      jumbo_frames: false
      large_send: false
      qos_mode: loose
      primary_vios:
        name: <primary_vios_name>
        backing_device: <primary_backing_device>
      secondary_vios:
        name: <secondary_vios_name>
        backing_device: <secondary_backing_device>
    state: present

- name: Create a Virtual Network Bridge without failover (single VIOS)
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    virtual_network_name: <virtual_network_name>
    shared_ethernet_adapter:
      primary_vios:
        name: <primary_vios_name>
        backing_device: <primary_backing_device>
    state: present

- name: Update a Virtual Network Bridge (enable load-sharing, change QoS, set HA mode)
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    virtual_network_name: <virtual_network_name>
    shared_ethernet_adapter:
      load_balancing: true
      addition_pvid: <addition_pvid>
      jumbo_frames: false
      large_send: true
      qos_mode: loose
      primary_vios:
        high_availability_mode: auto
      secondary_vios:
        high_availability_mode: standby
    state: update

- name: Add tagged Virtual Networks to specific LoadGroups of an existing bridge
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    virtual_network_name: <virtual_network_name>
    shared_ethernet_adapter:
      tagged_virtual_networks:
        - 72: [<tagged_vn_name_1>, <tagged_vn_name_2>]
        - 75: [<tagged_vn_name_3>]
    state: update

- name: Delete a Virtual Network Bridge
  ibm.power_hmc.power_network_bridge:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: <username>
      password: <password>
    system_name: <managed_system_name>
    virtual_network_name: <virtual_network_name>
    state: absent

Return Values 

network_bridge_info (on success of C(facts), C(present), and C(update) states; not returned on C(absent), dict, )

Information about Virtual Network Bridges on the managed system.

network_bridges (, list, )

List of Virtual Network Bridges on the managed system. Returned only on facts.

bridge_uuid (, str, )

Unique identifier of the Virtual Network Bridge.

port_vlan_id (, str, )

Port VLAN ID of the primary LoadGroup (identifies the bridge).

failover_enabled (, str, )

Whether SEA failover is enabled on the bridge.

load_balancing_enabled (, str, )

Whether load-balancing across LoadGroups is enabled.

shared_ethernet_adapters (, list, )

List of Shared Ethernet Adapters backing the bridge.

device_name (, str, )

Device name of the Shared Ethernet Adapter on the VIOS.

backing_device_name (, str, )

Physical or virtual backing device used by the SEA.

is_primary (, str, )

Whether this SEA is the primary adapter.

jumbo_frames_enabled (, str, )

Whether jumbo frames are enabled on the SEA.

large_send (, str, )

Whether large send offload is enabled on the SEA.

qos_mode (, str, )

Quality-of-service mode of the SEA (disabled, loose, or strict).

high_availability_mode (, str, )

High-availability mode of the SEA (disabled, auto, or standby).

port_vlan_id (, str, )

Port VLAN ID associated with the SEA.

unique_device_id (, str, )

Unique device identifier of the SEA.

assigned_vios_href (, str, )

REST href of the VIOS that owns this SEA.

location_code (, str, )

Location code of the SEA.

thread_mode_enabled (, str, )

Whether thread mode is enabled on the SEA.

trunk_adapters (, list, )

Trunk adapters belonging to this SEA.

device_name (, str, ): Device name of the trunk adapter.
virtual_slot_number (, str, ): Virtual slot number of the trunk adapter.
mac_address (, str, ): MAC address of the trunk adapter (uppercase hex, no colons).
trunk_priority (, str, ): Trunk priority of the adapter.
port_vlan_id (, str, ): Port VLAN ID of the trunk adapter.
location_code (, str, ): Location code of the trunk adapter.
virtual_switch_id (, str, ): ID of the virtual switch the trunk adapter is connected to.

load_groups (, list, )

LoadGroups associated with the bridge.

port_vlan_id (, str, )

Port VLAN ID of the LoadGroup.

virtual_network_hrefs (, list, )

REST hrefs of the Virtual Networks linked to this LoadGroup.

trunk_adapters (, list, )

Trunk adapters belonging to this LoadGroup.

device_name (, str, ): Device name of the trunk adapter.
virtual_slot_number (, str, ): Virtual slot number of the trunk adapter.
mac_address (, str, ): MAC address of the trunk adapter (uppercase hex, no colons).
trunk_priority (, str, ): Trunk priority of the adapter.
port_vlan_id (, str, ): Port VLAN ID of the trunk adapter.
location_code (, str, ): Location code of the trunk adapter.
virtual_switch_id (, str, ): ID of the virtual switch the trunk adapter is connected to.

port_vlan_id (, int, )

Port VLAN ID of the bridge acted on. Returned on present and update.

status (, str, )

Result of the operation (created, updated, or unchanged).

failover_enabled (, bool, )

Whether SEA failover is enabled. Returned on present.

load_balancing_enabled (, bool, )

Whether load-balancing is enabled. Returned on present and update.

jumbo_frames (, bool, )

Whether jumbo frames are enabled on the SEA. Returned on present and update.

large_send (, bool, )

Whether large send offload is enabled on the SEA. Returned on present and update.

qos_mode (, str, )

Quality-of-service mode set on the SEA. Returned on present and update.

tagged_virtual_networks_added (, dict, )

Dict mapping each LoadGroup PVID (as string) to the list of Virtual Network names newly linked to that LoadGroup during the update. Returned on update.

Status 

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by community.

Authors

Navinakumar Kandakur (@nkandak1)

power_network_bridge – Manages a Virtual Network Bridge on an IBM Power HMC managed system

Synopsis

Requirements

Parameters

Examples

Return Values

Status

Authors

Synopsis 

Requirements 

Parameters 

Examples 

Return Values 

Status 