zhmc_adapter – Update adapters and create Hipersocket adapters

Synopsis 

Gather facts about an adapter of a CPC (Z system), including its ports.
Update the properties of an adapter and its ports.
Create or delete a Hipersocket adapter.

Requirements 

The targeted Z system must be in the Dynamic Partition Manager (DPM) operational mode.
The HMC userid must have these task permissions: ‘Adapter Details’, ‘Create HiperSockets Adapter’, ‘Delete HiperSockets Adapter’, ‘Configure Storage - System Programmer’.
The HMC userid must have object-access permissions to these objects: Target adapters, CPCs of target adapters.

Parameters 

hmc_host

The hostname or IP address of the HMC.

required: True

type: str

hmc_auth

The authentication credentials for the HMC.

required: True

type: dict

userid: The userid (username) for authenticating with the HMC. This is mutually exclusive with providing session_id.

required: False

type: str
password: The password for authenticating with the HMC. This is mutually exclusive with providing session_id.

required: False

type: str
session_id: HMC session ID to be used. This is mutually exclusive with providing userid and password and can be created as described in :ref:`zhmc_session_module`.

required: False

type: str
ca_certs: Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the ‘REQUESTS_CA_BUNDLE’ environment variable or the path name in the ‘CURL_CA_BUNDLE’ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

required: False

type: str
verify: If True (default), verify the HMC certificate as specified in the ca_certs parameter. If False, ignore what is specified in the ca_certs parameter and do not verify the HMC certificate.

required: False

type: bool

default: True

cpc_name

The name of the CPC with the target adapter.

required: True

type: str

name

The name of the target adapter. In case of renaming an adapter, this is the new name of the adapter.

required: True

type: str

match

Only for state=set: Match properties for identifying the target adapter in the set of adapters in the CPC, if an adapter with the name specified in the name module parameter does not exist in that set. This parameter will be ignored otherwise.

Use of this parameter allows renaming an adapter: The name module parameter specifies the new name of the target adapter, and the match module parameter identifies the adapter to be renamed. This can be combined with other property updates by using the properties module parameter.

The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for adapter resources, with underscores instead of hyphens. The value of each dictionary item is the match value for the property (in YAML syntax). Integer properties may also be provided as decimal strings.

The specified match properties follow the rules of filtering for the zhmcclient library as described in https://python-zhmcclient.readthedocs.io/en/stable/concepts.html#filtering

The possible match properties are all properties in the data model for adapter resources, including name.

required: False

type: dict

state

The desired state for the adapter. All states are fully idempotent within the limits of the properties that can be changed:

* set: Ensures that an existing adapter has the specified properties.

* present: Ensures that a Hipersockets adapter exists and has the specified properties.

* absent: Ensures that a Hipersockets adapter does not exist.

* facts: Returns the adapter properties including its ports.

required: True
type: str
choices: set, present, absent, facts

properties

Only for state=set|present: New values for the properties of the adapter. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other states.

The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for adapter resources, with underscores instead of hyphens. The value of each dictionary item is the property value (in YAML syntax). Integer properties may also be provided as decimal strings.

The possible properties in this dictionary are the properties defined as writeable in the data model for adapter resources, with the following exceptions:

* name: Cannot be specified as a property because the name has already been specified in the name module parameter.

* type: The desired adapter type can be specified in order to support adapters that can change their type (e.g. the FICON Express adapter can change its type between ‘not-configured’, ‘fcp’ and ‘fc’).

* crypto_type: The crypto type can be specified in order to support the ability of the Crypto Express adapters to change their crypto type. Valid values are ‘ep11’, ‘cca’ and ‘acc’. Changing to ‘acc’ will zeroize the crypto adapter.

required: False

type: dict

log_file

File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger.

required: False

type: str

Examples 

---
# Note: The following examples assume that some variables named 'my_*' are set.

- name: Gather facts about an existing adapter
  zhmc_adapter:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_adapter_name }}"
    state: facts
  register: adapter1

- name: Ensure an existing adapter has the desired property values
  zhmc_adapter:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_adapter_name }}"
    state: set
    properties:
      description: "This is adapter {{ my_adapter_name }}"
  register: adapter1

- name: "Ensure the existing adapter identified by its name or adapter ID has
         the desired name and property values"
  zhmc_adapter:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_adapter_name }}"
    match:
      adapter_id: "12C"
    state: set
    properties:
      description: "This is adapter {{ my_adapter_name }}"
  register: adapter1

- name: "Ensure a Hipersockets adapter exists and has the desired property
         values"
  zhmc_adapter:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_adapter_name }}"
    state: present
    properties:
      type: hipersockets
      description: "This is Hipersockets adapter {{ my_adapter_name }}"
  register: adapter1

- name: "Ensure a Hipersockets adapter does not exist"
  zhmc_adapter:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_adapter_name }}"
    state: absent

Return Values 

changed

Indicates if any change has been made by the module. For state=facts, always will be false.

returned: always

type: bool

msg

An error message that describes the failure.

returned: failure

type: str

adapter

For state=absent, an empty dictionary.

For state=set|present|facts, the adapter and its ports.

returned: success
type: dict
sample:

{
    "adapter-family": "ficon",
    "adapter-id": "120",
    "allowed-capacity": 64,
    "card-location": "A14B-D112-J.01",
    "channel-path-id": "09",
    "class": "adapter",
    "configured-capacity": 14,
    "description": "",
    "detected-card-type": "ficon-express-16s-plus",
    "maximum-total-capacity": 254,
    "name": "FCP_120_SAN1_02",
    "object-id": "dfb2147a-e578-11e8-a87c-00106f239c31",
    "object-uri": "/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31",
    "parent": "/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7",
    "physical-channel-status": "operating",
    "port-count": 1,
    "ports": [
        {
            "class": "storage-port",
            "description": "",
            "element-id": "0",
            "element-uri": "/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0",
            "fabric-id": "100088947155A1E9",
            "index": 0,
            "name": "Port 0",
            "parent": "/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31"
        }
    ],
    "state": "online",
    "status": "active",
    "storage-port-uris": [
        "/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0"
    ],
    "type": "fcp",
    "used-capacity": 20
}

name

Adapter name

type: str

{property}

Additional properties of the adapter, as described in the data model of the ‘Adapter’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

ports

Artificial property for the ports of the adapter.

type: list

elements: dict

name: Port name

type: str
{property}: Additional properties of the port, as described in the data model of the ‘Network Port’ or ‘Storage Port’ element object of the ‘Adapter’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book. In case of unconfigured FICON adapters, the property list is short.

zhmc_adapter – Update adapters and create Hipersocket adapters

Synopsis

Requirements

Parameters

Examples

See Also

Return Values

Synopsis 

Requirements 

Parameters 

Examples 

See Also 

Return Values 