powervm_client_network_adapter – Create, update, delete, and query Client Network Adapters (CNAs) on PowerVM logical partitions and Virtual I/O Servers

Synopsis 

Creates a Client Network Adapter on a logical partition or VIOS and attaches it to a virtual network.

Updates settings of an existing Client Network Adapter such as MAC address, QoS, and 802.1Qbg settings.

Retrieves information about Client Network Adapters attached to a logical partition or VIOS.

Deletes a Client Network Adapter from a logical partition or VIOS.

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 log in.

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

Required for this module. Passwordless authentication is not supported because all operations use the HMC REST API.

system_name (True, str, None)
The name or MTMS (machine type model serial) of the managed system.

vm_name (optional, str, None)
The name of the logical partition to which the CNA belongs.

Mutually exclusive with vios_name.

One of vm_name or vios_name is required for all states.

vios_name (optional, str, None)
The name of the Virtual I/O Server to which the CNA belongs.

Mutually exclusive with vm_name.

When used with state=updated, state=absent, or state=detach_virtual_network, the VIOS must be shut down (not activated state). The module fails if the VIOS is running.

One of vm_name or vios_name is required for all states.

virtual_network_name (optional, str, None)
The name of the virtual network to attach to the CNA.

Required when state=present.

Optional when state=facts. If provided, filters results to CNAs associated with that virtual network.

Mutually exclusive with virtual_ethernet_adapter_id when state=facts.

Not used when state=updated or state=absent.

virtual_ethernet_adapter_id (optional, int, None)
The virtual slot number to assign to the CNA.

Optional when state=present. If not specified the HMC assigns one automatically.

Required when state=updated or state=absent. Identifies the adapter to modify or delete.

Optional when state=facts. If provided, filters results to the CNA on that slot.

Mutually exclusive with virtual_network_name when state=facts.

mac_address (optional, str, None)
The MAC address to assign to the adapter.

Optional when state=updated.

Use colon-separated format, e.g., B6:08:90:7C:A6:08.

os_mac_address_restrictions (optional, str, None)
Controls which MAC addresses the operating system is allowed to use on the adapter.

allow_all permits any MAC address.

deny_all blocks all OS MAC addresses.

allow_specified permits only the addresses listed in allowed_os_mac_addresses.

Optional when state=updated.

allowed_os_mac_addresses (optional, list, None)
List of MAC addresses the OS is permitted to use on the adapter.

Required when os_mac_address_restrictions=allow_specified.

Each entry should be in colon-separated format, e.g., B6:08:90:7C:A6:08.

Optional when state=updated.

qos_priority_enabled (optional, bool, None)
Whether Quality of Service (QoS) priority is enabled on the adapter.

Optional when state=updated.

qos_priority (optional, int, None)
The QoS priority value for the adapter (0-7).

Applicable when qos_priority_enabled=true.

Optional when state=updated.

vsi_type_id (optional, int, None)
The 802.1Qbg VSI Type ID for the adapter.

Optional when state=updated.

vsi_manager_id (optional, int, None)
The 802.1Qbg VSI Manager ID for the adapter.

Optional when state=updated.

vsi_type_version (optional, int, None)
The 802.1Qbg VSI Type Version for the adapter.

Optional when state=updated.

state (True, str, None)
present creates a new Client Network Adapter on the logical partition or VIOS.

updated modifies settings of an existing Client Network Adapter identified by virtual_ethernet_adapter_id. Supports updating the adapter MAC address, OS MAC address restrictions, QoS settings, and 802.1Qbg settings. Virtual network assignment cannot be changed with this state; use detach_virtual_network and present instead. When vios_name is specified, the VIOS must be in the not activated (shut-down) state, otherwise the module fails with an error.

absent deletes an existing Client Network Adapter from the logical partition or VIOS. Requires virtual_ethernet_adapter_id to identify the adapter to remove. When vios_name is specified, the VIOS must be in the not activated (shut-down) state, otherwise the module fails with an error.

detach_virtual_network detaches a virtual network from an existing Client Network Adapter identified by virtual_ethernet_adapter_id. Requires both virtual_ethernet_adapter_id and virtual_network_name. If the adapter has only one virtual network attached, the entire adapter is deleted. If the adapter has multiple virtual networks, the specified network’s link is removed from VirtualNetworks and its VLAN ID is stripped from TaggedVLANIDs. When vios_name is specified, the VIOS must be in the not activated (shut-down) state, otherwise the module fails with an error.

facts retrieves information about all Client Network Adapters on the logical partition or VIOS. If virtual_network_name is provided, filters to adapters connected to that virtual network. If virtual_ethernet_adapter_id is provided, filters to the adapter on that slot. virtual_network_name and virtual_ethernet_adapter_id are mutually exclusive for this state. Either vm_name or vios_name identifies the target partition.

Notes 

Note

This module uses the HMC REST API and requires a password for authentication. Passwordless authentication is not supported.
A Client Network Adapter (CNA) allows logical partitions and Virtual I/O Servers to communicate with each other without assigning physical hardware to the partitions.
When vios_name is used with state=updated, state=absent, or state=detach_virtual_network, the target VIOS must be in the not activated (shut-down) state. The module will fail if the VIOS is running, because the HMC does not allow CNA modifications on a running VIOS.

Examples 

- name: Create a Client Network Adapter on an LPAR
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_network_name: '{{ virtual_network_name }}'
    state: present

- name: Create a Client Network Adapter with a specific virtual slot number
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_network_name: '{{ virtual_network_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    state: present

- name: Get all Client Network Adapters on an LPAR
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    state: facts

- name: Get Client Network Adapters filtered by virtual network
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_network_name: '{{ virtual_network_name }}'
    state: facts

- name: Update CNA MAC address, MAC restrictions, QoS and 802.1Qbg settings on an LPAR
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    mac_address: '{{ mac_address }}'
    os_mac_address_restrictions: '{{ os_mac_address_restrictions }}'
    allowed_os_mac_addresses: '{{ allowed_os_mac_addresses }}'
    qos_priority_enabled: '{{ qos_priority_enabled }}'
    qos_priority: '{{ qos_priority }}'
    vsi_type_id: '{{ vsi_type_id }}'
    vsi_manager_id: '{{ vsi_manager_id }}'
    vsi_type_version: '{{ vsi_type_version }}'
    state: updated

- name: Delete a Client Network Adapter from an LPAR
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    state: absent

- name: Detach a virtual network from an LPAR's Client Network Adapter
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vm_name: '{{ vm_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    virtual_network_name: '{{ virtual_network_name }}'
    state: detach_virtual_network

- name: Update CNA MAC address, MAC restrictions, QoS and 802.1Qbg settings on a VIOS
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vios_name: '{{ vios_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    mac_address: '{{ mac_address }}'
    os_mac_address_restrictions: '{{ os_mac_address_restrictions }}'
    allowed_os_mac_addresses: '{{ allowed_os_mac_addresses }}'
    qos_priority_enabled: '{{ qos_priority_enabled }}'
    qos_priority: '{{ qos_priority }}'
    vsi_type_id: '{{ vsi_type_id }}'
    vsi_manager_id: '{{ vsi_manager_id }}'
    vsi_type_version: '{{ vsi_type_version }}'
    state: updated

- name: Detach a virtual network from a VIOS Client Network Adapter
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vios_name: '{{ vios_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    virtual_network_name: '{{ virtual_network_name }}'
    state: detach_virtual_network

- name: Get all Client Network Adapters on a VIOS
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vios_name: '{{ vios_name }}'
    state: facts

- name: Create a Client Network Adapter on a VIOS
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vios_name: '{{ vios_name }}'
    virtual_network_name: '{{ virtual_network_name }}'
    state: present

- name: Delete a Client Network Adapter from a VIOS
  ibm.power_hmc.powervm_client_network_adapter:
    hmc_host: "{{ inventory_hostname }}"
    hmc_auth:
      username: '{{ ansible_user }}'
      password: '{{ hmc_password }}'
    system_name: '{{ system_name }}'
    vios_name: '{{ vios_name }}'
    virtual_ethernet_adapter_id: '{{ virtual_ethernet_adapter_id }}'
    state: absent

Return Values 

client_network_adapter_info (on success of C(facts), C(present), C(updated), and C(detach_virtual_network) states, dict, )

Information about Client Network Adapters on the logical partition or VIOS.

client_network_adapters (, list, )

List of Client Network Adapters found on the logical partition or VIOS.

adapter_uuid (, str, ): Unique identifier of the Client Network Adapter.
mac_address (, str, ): MAC address of the adapter (no colons, uppercase hex).
virtual_ethernet_adapter_id (, str, ): Virtual slot number of the adapter.
port_vlan_id (, str, ): Port VLAN ID of the adapter.
virtual_switch_name (, str, ): Name of the virtual switch the adapter is attached to.
virtual_switch_id (, str, ): ID of the virtual switch the adapter is attached to.
virtual_network_uuid (, str, ): UUID of the virtual network the adapter is connected to.
virtual_network_uuids (, list, ): List of all virtual network UUIDs attached to the adapter.
virtual_network_name (, str, ): Name of the virtual network the adapter is connected to.
location_code (, str, ): Location code of the adapter.
drc_name (, str, ): Dynamic reconfiguration connector name of the adapter.
local_partition_id (, str, ): ID of the logical partition or VIOS that owns the adapter.
varied_on (, str, ): Whether the adapter is varied on.
required_adapter (, str, ): Whether the adapter is required.
tagged_vlan_supported (, str, ): Whether tagged VLAN is supported on the adapter.
tagged_vlan_ids (, str, ): Comma-separated list of tagged VLAN IDs configured on the adapter.
allowed_os_mac_addresses (, str, ): OS MAC address restriction setting (ALL, NONE, or a list of addresses).
qos_priority_enabled (, str, ): Whether QoS priority is enabled on the adapter.
qos_priority (, str, ): QoS priority value for the adapter (0-7). Null when QoS is disabled.
vsi_type_id (, str, ): VSI Type ID of the adapter. Null when not configured.
vsi_manager_id (, str, ): VSI Manager ID of the adapter. Null when not configured.
vsi_type_version (, str, ): VSI Type Version of the adapter. Null when not configured.
hcn_id (, str, ): Host Channel Name ID of the adapter.

Status 

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

Authors

Navinakumar Kandakur (@nkandak1)

powervm_client_network_adapter – Create, update, delete, and query Client Network Adapters (CNAs) on PowerVM logical partitions and Virtual I/O Servers

Synopsis

Requirements

Parameters

Notes

Examples

Return Values

Status