zhmc_adapter - Manages an adapter in a CPC.

Synopsis

  • Gathers facts about the adapter including its ports.
  • Updates the properties of an adapter.

Requirements (on host that executes module)

  • Network access to HMC
  • zhmcclient >=0.20.0
  • ansible >=2.2.0.0

Options

parameter required default choices comments
faked_session
no Real HMC will be used.
A zhmcclient_mock.FakedSession object that has a mocked HMC set up. If provided, it will be used instead of connecting to a real HMC. This is used for testing purposes only.
hmc_auth
yes
The authentication credentials for the HMC.
Dictionary object hmc_auth
parameter required default choices comments
userid
yes
The userid (username) for authenticating with the HMC.
password
yes
The password for authenticating with the HMC.
hmc_host
yes
The hostname or IP address of the HMC.
log_file
no
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.
match
no No match properties
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.
name
yes
The name of the target adapter. In case of renaming an adapter, this is the new name of the adapter.
properties
no No property changes (other than possibly C(name)).
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.
state
yes
  • set
  • present
  • absent
  • facts
The desired state for the attachment:
* 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: Does not change anything on the adapter and returns the adapter properties including its ports.

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

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
cpc
For state=absent, an empty dictionary.
For state=set|present|facts, a dictionary with the properties of the adapter. The properties contain these additional artificial properties for listing its child resources: - 'ports': The ports of the adapter, as a dict of key: port name, value: dict of a subset of the port properties (name, status, element_uri).
success dict { "name": "adapter-1", "description": "Adapter 1", "status": "active", "acceptable_status": [ "active" ], ... "ports": [ { "name": "Port 0", ... }, ... ] }


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support.

For help in developing on modules, should you be so inclined, please read the contribution guidelines in the module’s source repository, Testing Ansible and Developing Modules.

Shipment

This module is a third-party module and is not shipped with Ansible. See the module’s source repository for details.