zhmc Ansible modules¶

Introduction¶

What this package provides¶

The zhmc-ansible-modules Python package contains Ansible modules that can manage platform resources on IBM Z and LinuxONE machines that are in the Dynamic Partition Manager (DPM) operational mode.

The goal of this package is to be able to utilize the power and ease of use of Ansible for the management of IBM Z platform resources.

The IBM Z resources that can be managed include Partitions, HBAs, NICs, and Virtual Functions.

The Ansible modules in the zhmc-ansible-modules package are fully idempotent, following an important principle for Ansible modules.

The idempotency of a module allows Ansible playbooks to specify the desired end state for a resource, regardless of what the current state is. For example, a IBM Z partition can be specified to have state=active which means that it must exist and be in the active operational status. Depending on the current state of the partition, actions will be taken by the module to reach this desired end state: If the partition does not exist, it will be created and started. If it exists but is not active, it will be started. If it is already active, nothing will be done. Other initial states including transitional states such as starting or stopping also will be taken care of.

The idempotency of modules makes Ansible playbooks restartable: If an error happens and some things have been changed already, the playbook can simply be re-run and will automatically do the right thing, because the initial state does not matter for reaching the desired end state.

The Ansible modules in the zhmc-ansible-modules package are written in Python and interact with the Web Services API of the Hardware Management Console (HMC) of the machines to be managed, by using the API of the zhmcclient Python package.

Supported environments¶

The Ansible modules in the zhmc-ansible-modules package are supported in these environments:

Ansible versions: 2.0 or higher
Operating systems running Ansible: Linux, OS-X
Machine generations: z13/z13s/Emperor/Rockhopper or higher

Installation¶

The system Ansible is installed on is called the “control system”. This is where Ansible commands (such as ansible-playbook) are invoked.

Ansible is written in Python and invokes Ansible modules always as executables, even when they are also written in Python. Therefore, Ansible modules implemented in Python are run as Python scripts and are not imported as Python modules.

The standard installation is that Ansible is installed as an operating system package and uses the existing system Python (version 2). The Ansible modules then also use the system Python.

As an alternative to the standard installation, it is possible to use a virtual Python environment for Ansible itself and for Ansible modules written in Python. Using a virtual Python environment has the main advantages that it minimizes the risk of incompatibilities between Python packages because the virtual environment contains only the packages that are needed for the specific use case, and that it does not pollute your system Python installation with other Python packages, keeping the risk of incompatibilities away from your system Python.

The following sections describe these two installation methods.

Standard installation with system Python¶

All commands shown are to be executed in a bash shell on the control system.

Install Ansible as an operating system package on the control system.

For details, see Installing the Control Machine.
Install the zhmc-ansible-modules package into the system Python:
```
$ sudo pip install zhmc-ansible-modules
```
This will also install its dependent Python packages.
Set up the Ansible module search path

Find out the install location of the zhmc-ansible-modules package:
```
$ pip show zhmc-ansible-modules | grep Location
Location: /usr/local/lib/python2.7/dist-packages
```
The Ansible module search path is the zhmc_ansible_modules directory in the location shown:
```
/usr/local/lib/python2.7/dist-packages/zhmc_ansible_modules
```
Note that the Python package name is zhmc-ansible-modules while the package directory is zhmc_ansible_modules.

Set the Ansible module search path using one of these options:
1. via the Ansible config file:
  
  Edit the Ansible config file /etc/ansible/ansible.cfg to contain the following line:
```
library = /usr/local/lib/python2.7/dist-packages/zhmc_ansible_modules
```
2. via an environment variable:
  
  Edit your ~/.bashrc file to contain the following line:
```
export ANSIBLE_LIBRARY=/usr/local/lib/python2.7/dist-packages/zhmc_ansible_modules
```
  and source the file to set it in your current shell:
```
$ . ~/.bashrc
```

Alternative installation with virtual Python environment¶

This section describes the installation of Ansible and the Ansible modules in the zhmc-ansible-modules package into a virtual Python environment that is set up using virtualenv.

This installation method utilizes the ability of Ansible to configure the Python environment it uses, and configures it to use the active Python (which can be a virtual Python environment or the system Python).

All commands shown are to be executed in a bash shell on the control system.

Install Ansible as an operating system package on the control system.

For details, see Installing the Control Machine.
Create a shell script that invokes the active Python.

Adjust the file name and path for the shell script in the python_script variable as needed, the only requirement is that the shell script must be found in the PATH:
```
$ python_script=$HOME/local/bin/env_python

$ cat >$python_script <<'EOT'
#!/bin/bash
py=$(which python)
$py "$@"
EOT

$ chmod 755 $python_script
```
Configure Ansible to invoke Python via the new shell script (using the python_script variable from the previous step):
```
$ sudo tee -a /etc/ansible/hosts >/dev/null <<EOT
[local:vars]
ansible_python_interpreter=$python_script
EOT
```
Create a shell script that sets the ANSIBLE_LIBRARY environment variable to the location of the zhmc-ansible-modules package found in the active Python environment.

Adjust the file name and path for the shell script in the library_script variable as needed, the only requirement is that the shell script must be found in the PATH:
```
$ library_script=$HOME/local/bin/setup_ansible_library

$ cat >$library_script <<'EOT'
#!/bin/bash
zhmc_dir=$(dirname $(python -c "import zhmc_ansible_modules as m; print(m.__file__)"))
export ANSIBLE_LIBRARY=$zhmc_dir
EOT

$ chmod 755 $library_script
```
Create a virtual Python environment for Python 2.7 and activate it.
```
$ mkvirtualenv myenv
```
Note: Using the command shown requires the virtualenvwrapper package.
Install the zhmc-ansible-modules Python package into the active virtual Python environment:
```
(myenv)$ pip install zhmc-ansible-modules
```
This will also install its dependent Python packages.

Set the ANSIBLE_LIBRARY environment variable by sourcing the script created in step 4:
```
$ . setup_ansible_library
```
This must be done after each switch (or deactivation) of the active Python environment and before any Ansible command (that uses these modules) is invoked.

Verification of the installation¶

You can verify that the zhmc-ansible-modules package and its dependent packages are installed correctly by running an example playbook in check mode:

$ ansible-playbook playbooks/create_partition.yml --check

PLAY [localhost] ***********************************************************

TASK [Gathering Facts] *****************************************************
ok: [127.0.0.1]

TASK [Ensure partition exists and is stopped] ******************************
changed: [127.0.0.1]

TASK [Ensure HBA exists in the partition] **********************************
changed: [127.0.0.1]

TASK [Ensure NIC exists in the partition] **********************************
changed: [127.0.0.1]

TASK [Ensure virtual function exists in the partition] *********************
changed: [127.0.0.1]

TASK [Configure partition for booting via HBA] *****************************
changed: [127.0.0.1]

PLAY RECAP *****************************************************************
127.0.0.1                  : ok=6    changed=5    unreachable=0    failed=0

Example playbooks¶

After having installed the zhmc-ansible-modules package, you can download and run the example playbooks in folder ``playbooks` of the Git repository <https://github.com/zhmcclient/zhmc-ansible-modules/tree/master/playbooks>`_:

create_partition.yml creates a partition with a NIC, HBA and virtual function to an accelerator adapter.
delete_partition.yml deletes a partition.
vars_example.yml is an example variable file defining variables such as CPC name, partition name, etc.
vault_example.yml is an example password vault file defining variables for authenticating with the HMC.

Before you run a playbook, copy vars_example.yml to vars.yml and vault_example.yml to vault.yml and change the variables in those files as needed.

Then, run the playbooks:

$ ansible-playbook create_partition.yml

PLAY [localhost] **********************************************************

TASK [Gathering Facts] ****************************************************
ok: [127.0.0.1]

TASK [Ensure partition exists and is stopped] *****************************
changed: [127.0.0.1]

TASK [Ensure HBA exists in the partition] *********************************
changed: [127.0.0.1]

TASK [Ensure NIC exists in the partition] *********************************
changed: [127.0.0.1]

TASK [Ensure virtual function exists in the partition] ********************
changed: [127.0.0.1]

TASK [Configure partition for booting via HBA] ****************************
changed: [127.0.0.1]

PLAY RECAP ****************************************************************
127.0.0.1                  : ok=6    changed=5    unreachable=0    failed=0

$ ansible-playbook delete_partition.yml

PLAY [localhost] **********************************************************

TASK [Gathering Facts] ****************************************************
ok: [127.0.0.1]

TASK [Ensure partition does not exist] ************************************
changed: [127.0.0.1]

PLAY RECAP ****************************************************************
127.0.0.1                  : ok=2    changed=1    unreachable=0    failed=0

Versioning¶

This documentation applies to version 0.6.1.dev3 of the zhmc-ansible-modules package. You can also see that version in the top left corner of this page.

The zhmc-ansible-modules package uses the rules of Semantic Versioning 2.0.0 for its version.

This documentation may have been built from a development level of the package. You can recognize a development version of this package by the presence of a “.devD” suffix in the version string.

Compatibility¶

For Ansible modules, compatibility is always seen from the perspective of an Ansible playbook using it. Thus, a backwards compatible new version of the zhmc-ansible-modules package means that the user can safely upgrade to that new version without encountering compatibility issues in any Ansible playbooks using these modules.

This package uses the rules of Semantic Versioning 2.0.0 for compatibility between package versions, and for deprecations.

The public interface of this package that is subject to the semantic versioning rules (and specificically to its compatibility rules) are the Ansible module interfaces described in this documentation.

Violations of these compatibility rules are described in section Change log.

Deprecations¶

Deprecated functionality is marked accordingly in this documentation and in the Change log.

Reporting issues¶

If you encounter any problem with this package, or if you have questions of any kind related to this package (even when they are not about a problem), please open an issue in the zhmc-ansible-modules issue tracker.

License¶

This package is licensed under the Apache 2.0 License.

All Modules¶

zhmc_adapter - Manages an adapter in a CPC.¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
- Status
- Support
- Shipment

Synopsis ¶

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

Requirements (on host that executes module)¶

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) 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.

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.

zhmc_cpc - Manages a CPC.¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about the CPC including its child resources.
Updates the properties of a CPC.

Requirements (on host that executes module)¶

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) 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.

name

yes

The name of the target CPC.

properties

no

No property changes.

Only for state=set: New values for the properties of the CPC. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for state=facts.

The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for CPC 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 CPC resources.

state

yes

set
facts

The desired state for the attachment:

* set: Ensures that the CPC has the specified properties.

* facts: Does not change anything on the CPC and returns the CPC properties including its child resources.

Examples ¶

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

- name: Gather facts about the CPC
  zhmc_cpc:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    name: "{{ my_cpc_name }}"
    state: facts
  register: cpc1

- name: Ensure the CPC has the desired property values
  zhmc_cpc:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    name: "{{ my_cpc_name }}"
    state: set
    properties:
      acceptable_status:
       - active
      description: "This is CPC {{ my_cpc_name }}"

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=set\|facts`, a dictionary with the properties of the CPC. The properties contain these additional artificial properties for listing its child resources: - 'partitions': The defined partitions of the CPC, as a dict of key: partition name, value: dict of a subset of the partition properties (name, status, object_uri). - 'adapters': The adapters of the CPC, as a dict of key: adapter name, value: dict of a subset of the adapter properties (name, status, object_uri).	success	dict	`{ "name": "CPCA", "description": "CPC A", "status": "active", "acceptable_status": [ "active" ], ... "partitions": [ { "name": "part-1", ... }, ... ], "adapters": [ { "name": "adapter-1", ... }, ... ], }`

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.

zhmc_crypto_attachment - Manages the attachment of crypto adapters and domains to partitions.¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about the attachment of crypto adapters and domains to a partition.
Attaches a range of crypto domains and a number of crypto adapters to a partition.
Detaches all crypto domains and all crypto adapters from a partition.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

access_mode

no

usage

usage
control

Only for state=attach: The access mode in which the crypto domains specified in domain_range need to be attached.

adapter_count

no

-1

Only for state=attach: The number of crypto adapters the partition needs to have attached. The special value -1 means all adapters of the desired crypto type in the CPC.

cpc_name

yes

The name of the CPC that has the partition and the crypto adapters.

crypto_type

no

ep11

ep11
cca
acc

Only for state=attach: The crypto type of the crypto adapters that will be considered for attaching.

domain_range

no

(0, -1)

Only for state=attach: The domain range the partition needs to have attached, as a tuple of integers (min, max) that specify the inclusive range of domain index numbers. Other domains attached to the partition remain unchanged. The special value -1 for the max item means the maximum supported domain index number.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) 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.

partition_name

yes

The name of the partition to which the crypto domains and crypto adapters are attached.

state

yes

attached
detached
facts

The desired state for the attachment:

* attached: Ensures that the specified number of crypto adapters of the specified crypto type, and the specified range of domain index numbers in the specified access mode are attached to the partition.

* detached: Ensures that no crypto adapter and no crypto domains are attached to the partition.

* facts: Does not change anything on the attachment and returns the crypto configuration of the partition.

Examples ¶

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

- name: Gather facts about the crypto configuration of a partition
  zhmc_crypto_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    state: facts
  register: crypto1

- name: Ensure domain 0 on all ep11 adapters is attached in usage mode
  zhmc_crypto_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_first_partition_name }}"
    state: attached
    crypto_type: ep11
    adapter_count: -1
    domain_range: 0,0
    access_mode: usage

- name: Ensure domains 1-max on all ep11 adapters are attached in control mode
  zhmc_crypto_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_first_partition_name }}"
    state: attached
    crypto_type: ep11
    adapter_count: -1
    domain_range: 1,-1
    access_mode: control

- name: Ensure domains 0-max on 1 ep11 adapter are attached to in usage mode
  zhmc_crypto_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_second_partition_name }}"
    state: attached
    crypto_type: ep11
    adapter_count: 1
    domain_range: 0,-1
    access_mode: usage

Return Values ¶

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

name	description	returned	type	sample
crypto_configuration	For `state=detached\|attached\|facts`, a dictionary with the crypto configuration of the partition after the changes applied by the module. Key is the partition name, and value is a dictionary with keys: - 'adapters': attached adapters, as a dict of key: adapter name, value: dict of adapter properties; - 'domain_config': attached domains, as a dict of key: domain index, value: access mode ('control' or 'usage'); - 'usage_domains': domains attached in usage mode, as a list of domain index numbers; - 'control_domains': domains attached in control mode, as a list of domain index numbers.	success	dict	`{ "part-1": { "adapters": { "adapter 1": { "type": "crypto", ... } }, "domain_config": { "0": "usage", "1": "control", "2": "control" } "usage_domains": [0], "control_domains": [1, 2] } }`
changes	For `state=detached\|attached\|facts`, a dictionary with the changes performed.	success	dict	`{ "added-adapters": ["adapter 1", "adapter 2"], "added-domains": ["0", "1"] }`

Notes ¶

Note

The CPC of the target partition must be in the Dynamic Partition Manager (DPM) operational mode.

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.

zhmc_hba - Manages HBAs in existing partitions (without “dpm-storage-management” feature)¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Creates, updates, and deletes HBAs in existing partitions of a CPC.
The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC with the partition containing the HBA.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target HBA that is managed. If the HBA needs to be created, this value becomes its name.

partition_name

yes

The name of the partition containing the HBA.

properties

no

No input properties

Dictionary with input properties for the HBA, for state=present. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for state=absent.

The possible input properties in this dictionary are the properties defined as writeable in the data model for HBA resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

* adapter_port_uri: Cannot be specified because this information is specified using the artificial properties adapter_name and adapter_port.

* adapter_name: The name of the adapter that has the port backing the target HBA. Cannot be changed after the HBA exists.

* adapter_port: The port index of the adapter port backing the target HBA. Cannot be changed after the HBA exists.

Properties omitted in this dictionary will remain unchanged when the HBA already exists, and will get the default value defined in the data model for HBAs when the HBA is being created.

state

yes

absent
present

The desired state for the target HBA:

absent: Ensures that the HBA does not exist in the specified partition.

present: Ensures that the HBA exists in the specified partition and has the specified properties.

Examples ¶

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

- name: Ensure HBA exists in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_hba_name }}"
    state: present
    properties:
      adapter_name: FCP-1
      adapter_port: 0
      description: "The port to our V7K #1"
      device_number: "123F"
  register: hba1

- name: Ensure HBA does not exist in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_hba_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
hba	For `state=absent`, an empty dictionary. For `state=present`, a dictionary with the resource properties of the HBA (after changes, if any). The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package.	success	dict	`{ "name": "hba-1", "description": "HBA #1", "adapter-port-uri": "/api/adapters/.../ports/...", ... }`

Notes ¶

Note

See also Ansible module zhmc_partition.

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.

zhmc_nic - Manages NICs in existing partitions¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Creates, updates, and deletes NICs in existing partitions of a CPC.
The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC with the partition containing the NIC.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target NIC that is managed. If the NIC needs to be created, this value becomes its name.

partition_name

yes

The name of the partition containing the NIC.

properties

no

No input properties

Dictionary with input properties for the NIC, for state=present. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for state=absent.

The possible input properties in this dictionary are the properties defined as writeable in the data model for NIC resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

* network_adapter_port_uri and virtual_switch_uri: Cannot be specified because this information is specified using the artificial properties adapter_name and adapter_port.

* adapter_name: The name of the adapter that has the port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets).

* adapter_port: The port index of the adapter port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets).

Properties omitted in this dictionary will remain unchanged when the NIC already exists, and will get the default value defined in the data model for NICs when the NIC is being created.

state

yes

absent
present

The desired state for the target NIC:

absent: Ensures that the NIC does not exist in the specified partition.

present: Ensures that the NIC exists in the specified partition and has the specified properties.

Examples ¶

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

- name: Ensure NIC exists in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_nic_name }}"
    state: present
    properties:
      adapter_name: "OSD 0128 A13B-13"
      adapter_port: 0
      description: "The port to our data network"
      device_number: "023F"
  register: nic1

- name: Ensure NIC does not exist in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_nic_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
nic	For `state=absent`, an empty dictionary. For `state=present`, a dictionary with the resource properties of the NIC (after changes, if any). The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package.	success	dict	`{ "name": "nic-1", "description": "NIC #1", "virtual-switch-uri': "/api/vswitches/...", ... }`

Notes ¶

Note

See also Ansible module zhmc_partition.

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.

zhmc_partition - Manages partitions¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about a partition, including its child resources (HBAs, NICs and virtual functions).
Creates, updates, deletes, starts, and stops partitions in a CPC. The child resources of the partition are are managed by separate Ansible modules.
The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC with the target partition.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target partition.

properties

no

No input properties

Dictionary with input properties for the partition, for state=stopped and state=active. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for state=absent.

The possible input properties in this dictionary are the properties defined as writeable in the data model for Partition resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

* type: Cannot be changed once the partition exists, because updating it is not supported.

* boot_storage_device: Cannot be specified because this information is specified using the artificial property boot_storage_hba_name.

* boot_network_device: Cannot be specified because this information is specified using the artificial property boot_network_nic_name.

* boot_storage_hba_name: The name of the HBA whose URI is used to construct boot_storage_device. Specifying it requires that the partition exists.

* boot_network_nic_name: The name of the NIC whose URI is used to construct boot_network_device. Specifying it requires that the partition exists.

* crypto_configuration: The crypto configuration for the partition, in the format of the crypto-configuration property of the partition (see HMC API book for details), with the exception that adapters are specified with their names in field crypto_adapter_names instead of their URIs in field crypto_adapter_uris. If the crypto_adapter_names field is null, all crypto adapters of the CPC will be used.

Properties omitted in this dictionary will remain unchanged when the partition already exists, and will get the default value defined in the data model for partitions in the HMC API book when the partition is being created.

state

yes

absent
stopped
active
facts

The desired state for the target partition:

absent: Ensures that the partition does not exist in the specified CPC.

stopped: Ensures that the partition exists in the specified CPC, has the specified properties, and is in the 'stopped' status.

active: Ensures that the partition exists in the specified CPC, has the specified properties, and is in the 'active' or 'degraded' status.

facts: Does not change anything on the partition and returns the partition properties and the properties of its child resources (HBAs, NICs, and virtual functions).

Examples ¶

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

# Because configuring LUN masking in the SAN requires the host WWPN, and the
# host WWPN is automatically assigned and will be known only after an HBA has
# been added to the partition, the partition needs to be created in stopped
# state. Also, because the HBA has not yet been created, the boot
# configuration cannot be done yet:
- name: Ensure the partition exists and is stopped
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_partition_name }}"
    state: stopped
    properties:
      description: "zhmc Ansible modules: Example partition 1"
      ifl_processors: 2
      initial_memory: 1024
      maximum_memory: 1024
  register: part1

# After an HBA has been added (see Ansible module zhmc_hba), and LUN masking
# has been configured in the SAN, and a bootable image is available at the
# configured LUN and target WWPN, the partition can be configured for boot
# from the FCP LUN and can be started:
- name: Configure boot device and start the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_partition_name }}"
    state: active
    properties:
      boot_device: storage-adapter
      boot_storage_device_hba_name: hba1
      boot_logical_unit_number: 00000000001
      boot_world_wide_port_name: abcdefabcdef
  register: part1

- name: Ensure the partition does not exist
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_partition_name }}"
    state: absent

- name: Define crypto configuration
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_partition_name }}"
    state: active
    properties:
      crypto_configuration:
        crypto_adapter_names:
          - adapter1
          - adapter2
        crypto_domain_configurations:
          - domain_index: 0
            access_mode: control-usage
          - domain_index: 1
            access_mode: control
  register: part1

- name: Gather facts about a partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_partition_name }}"
    state: facts
  register: part1

Return Values ¶

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

name	description	returned	type	sample
partition	For `state=absent`, an empty dictionary. For `state=stopped` and `state=active`, a dictionary with the resource properties of the partition (after changes, if any). The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package. For `state=facts`, a dictionary with the resource properties of the partition, including its child resources (HBAs, NICs, and virtual functions). The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package. The properties of the child resources are represented in partition properties named 'hbas', 'nics', and 'virtual-functions', respectively.	success	dict	`{ "name": "part-1", "description": "partition #1", "status": "active", "boot-device": "storage-adapter", ... }`

Notes ¶

Note

See also Ansible modules zhmc_hba, zhmc_nic, zhmc_virtual_function.

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.

zhmc_storage_group - Manages DPM storage groups (with “dpm-storage-management” feature)¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about a storage group associated with a CPC, including its storage volumes and virtual storage resources.
Creates, deletes and updates a storage group associated with a CPC.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC associated with the target storage group.

expand

no

yes
no

Boolean that controls whether the returned storage group contains additional artificial properties that expand certain URI or name properties to the full set of resource properties (see description of return values of this module).

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target storage group.

properties

no

No properties.

Dictionary with desired properties for the storage group. Used for state=present; ignored for state=absent|facts. Dictionary key is the property name with underscores instead of hyphens, and dictionary value is the property value in YAML syntax. Integer properties may also be provided as decimal strings.

The possible input properties in this dictionary are the properties defined as writeable in the data model for Storage Group resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

* type: Cannot be changed once the storage group exists.

Properties omitted in this dictionary will remain unchanged when the storage group already exists, and will get the default value defined in the data model for storage groups in the HMC API book when the storage group is being created.

state

yes

absent
present
facts

The desired state for the target storage group:

* absent: Ensures that the storage group does not exist. If the storage group is currently attached to any partitions, the module will fail.

* present: Ensures that the storage group exists and is associated with the specified CPC, and has the specified properties. The attachment state of the storage group to a partition is not changed.

* facts: Does not change anything on the storage group and returns the storage group properties.

Examples ¶

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

- name: Gather facts about a storage group
  zhmc_storage_group:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_storage_group_name }}"
    state: facts
    expand: true
  register: sg1

- name: Ensure the storage group does not exist
  zhmc_storage_group:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_storage_group_name }}"
    state: absent

- name: Ensure the storage group exists
  zhmc_storage_group:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_storage_group_name }}"
    state: present
    expand: true
    properties:
      description: "Example storage group 1"
      type: fcp
      shared: false
      connectivity: 4
      max-partitions: 1
  register: sg1

Return Values ¶

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

name	description	returned	type	sample
storage_group	For `state=absent`, an empty dictionary. For `state=present\|facts`, a dictionary with the resource properties of the target storage group, plus additional artificial properties as described in the following list items. The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package. The additional artificial properties are: * `attached-partition-names`: List of partition names to which the storage group is attached. * `cpc-name`: Name of the CPC that is associated to this storage group. * `candidate-adapter-ports` (only if expand was requested): List of candidate adapter ports of the storage group. Each port is represented as a dictionary of its properties; in addition each port has an artificial property `parent-adapter` which represents the adapter of the port. Each adapter is represented as a dictionary of its properties. * `storage-volumes` (only if expand was requested): List of storage volumes of the storage group. Each storage volume is represented as a dictionary of its properties. * `virtual-storage-resources` (only if expand was requested): List of virtual storage resources of the storage group. Each virtual storage resource is represented as a dictionary of its properties. * `attached-partitions` (only if expand was requested): List of partitions to which the storage group is attached. Each partition is represented as a dictionary of its properties. * `cpc` (only if expand was requested): The CPC that is associated to this storage group. The CPC is represented as a dictionary of its properties.	success	dict	`{ "name": "sg-1", "description": "storage group #1", ... }`

Notes ¶

Note

The CPC that is associated with the target storage group must be in the Dynamic Partition Manager (DPM) operational mode and must have the “dpm-storage-management” firmware feature enabled. That feature has been introduced with the z14-ZR1 / Rockhopper II machine generation.
This module performs actions only against the Z HMC regarding the definition of storage group objects and their attachment to partitions. This module does not perform any actions against storage subsystems or SAN switches.
Attachment of a storage group to and from partitions is managed by the Ansible module zhmc_storage_group_attachment.
The Ansible module zhmc_hba is no longer used on CPCs that have the “dpm-storage-management” feature enabled.

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.

zhmc_storage_group_attachment - Manages the attachment of DPM storage groups to partitions (with “dpm-storage-management” feature)¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about the attachment of a storage group to a partition.
Attaches and detaches a storage group to and from a partition.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC that has the partition and is associated with the storage group.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

partition_name

yes

The name of the partition for the attachment.

state

yes

detached
attached
facts

The desired state for the attachment:

* detached: Ensures that the storage group is not attached to the partition. If the storage group is currently attached to the partition and the partition is currently active, the module will fail.

* attached: Ensures that the storage group is attached to the partition.

* facts: Does not change anything on the attachment and returns the attachment status.

storage_group_name

yes

The name of the storage group for the attachment.

Examples ¶

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

- name: Gather facts about the attachment
  zhmc_storage_group_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    partition_name: "{{ my_partition_name }}"
    state: facts
  register: sga1

- name: Ensure the storage group is attached to the partition
  zhmc_storage_group_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    partition_name: "{{ my_partition_name }}"
    state: attached

- name: "Ensure the storage group is not attached to the partition."
  zhmc_storage_group_attachment:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    partition_name: "{{ my_partition_name }}"
    state: detached

Return Values ¶

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

name	description	returned	type	sample
storage_group_attachment	A dictionary with a single key 'attached' whose boolean value indicates whether the storage group is now actually attached to the partition. If check mode was requested, the actual (i.e. not the desired) attachment state is returned.	success	dict	`{"attached": true}`

Notes ¶

Note

The CPC that is associated with the target storage group must be in the Dynamic Partition Manager (DPM) operational mode and must have the “dpm-storage-management” firmware feature enabled. That feature has been introduced with the z14-ZR1 / Rockhopper II machine generation.
This module performs actions only against the Z HMC regarding the attachment of storage group objects to partitions. This module does not perform any actions against storage subsystems or SAN switches.
The Ansible module zhmc_hba is no longer used on CPCs that have the “dpm-storage-management” feature enabled.

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.

zhmc_storage_volume - Manages DPM storage volumes in existing storage groups (with “dpm-storage-management” feature)¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Gathers facts about a storage volume in a storage group associated with a CPC.
Creates, deletes and updates a storage volume in a storage group associated with a CPC.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC associated with the storage group containing the target storage volume.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target storage volume.

properties

no

No properties.

Dictionary with desired properties for the storage volume. Used for state=present; ignored for state=absent|facts. Dictionary key is the property name with underscores instead of hyphens, and dictionary value is the property value in YAML syntax. Integer properties may also be provided as decimal strings.

The possible input properties in this dictionary are the properties defined as writeable in the data model for Storage Volume resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

Properties omitted in this dictionary will remain unchanged when the storage volume already exists, and will get the default value defined in the data model for storage volumes in the HMC API book when the storage volume is being created.

state

yes

absent
present
facts

The desired state for the target storage volume:

* absent: Ensures that the storage volume does not exist in the specified storage group.

* present: Ensures that the storage volume exists in the specified storage group, and has the specified properties.

* facts: Does not change anything on the storage volume and returns the storage volume properties.

storage_group_name

yes

The name of the storage group containing the target storage volume.

Examples ¶

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

- name: Gather facts about a storage volume
  zhmc_storage_volume:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    name: "{{ my_storage_volume_name }}"
    state: facts
  register: sv1

- name: Ensure the storage volume does not exist
  zhmc_storage_volume:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    name: "{{ my_storage_volume_name }}"
    state: absent

- name: Ensure the storage volume exists
  zhmc_storage_volume:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    storage_group_name: "{{ my_storage_group_name }}"
    name: "{{ my_storage_volume_name }}"
    state: present
    properties:
      description: "Example storage volume 1"
      size: 1
  register: sv1

Return Values ¶

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

name	description	returned	type	sample
storage_volume	For `state=absent`, an empty dictionary. For `state=present\|facts`, a dictionary with the resource properties of the storage volume, indicating the state after changes from this module (if any) have been applied. The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package. The additional artificial properties are: * `type`: Type of the storage volume ('fc' or 'fcp'), as defined in its storage group.	success	dict	`{ "name": "sv-1", "description": "storage volume #1", ... }`

Notes ¶

Note

The CPC that is associated with the storage group must be in the Dynamic Partition Manager (DPM) operational mode and must have the “dpm-storage-management” firmware feature enabled. That feature has been introduced with the z14-ZR1 / Rockhopper II machine generation.
This module performs actions only against the Z HMC regarding the definition of storage volume objects within storage group objects. This module does not perform any actions against storage subsystems or SAN switches.
The Ansible module zhmc_hba is no longer used on CPCs that have the “dpm-storage-management” feature enabled.

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.

zhmc_virtual_function - Manages virtual functions in existing partitions¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status
- Support
- Shipment

Synopsis ¶

Creates, updates, and deletes virtual functions in existing partitions of a CPC.
The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.

Requirements (on host that executes module)¶

Options ¶

parameter required default choices comments

cpc_name

yes

The name of the CPC with the partition containing the virtual function.

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
password	yes			The password for authenticating with the HMC.
userid	yes			The userid (username) for authenticating with the HMC.

hmc_host

yes

The hostname or IP address of the HMC.

name

yes

The name of the target virtual function that is managed. If the virtual function needs to be created, this value becomes its name.

partition_name

yes

The name of the partition containing the virtual function.

properties

no

No input properties

Dictionary with input properties for the virtual function, for state=present. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for state=absent.

The possible input properties in this dictionary are the properties defined as writeable in the data model for Virtual Function resources (where the property names contain underscores instead of hyphens), with the following exceptions:

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

* adapter_uri: Cannot be specified because this information is specified using the artificial property adapter_name.

* adapter_name: The name of the adapter that backs the target virtual function.

Properties omitted in this dictionary will remain unchanged when the virtual function already exists, and will get the default value defined in the data model for virtual functions when the virtual function is being created.

state

yes

absent
present

The desired state for the target virtual function:

absent: Ensures that the virtual function does not exist in the specified partition.

present: Ensures that the virtual function exists in the specified partition and has the specified properties.

Examples ¶

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

- name: Ensure virtual function exists in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_vfunction_name }}"
    state: present
    properties:
      adapter_name: "ABC-123"
      description: "The accelerator adapter"
      device_number: "033F"
  register: vfunction1

- name: Ensure virtual function does not exist in the partition
  zhmc_partition:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    partition_name: "{{ my_partition_name }}"
    name: "{{ my_vfunction_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
virtual_function	For `state=absent`, an empty dictionary. For `state=present`, a dictionary with the resource properties of the virtual function (after changes, if any). The dictionary keys are the exact property names as described in the data model for the resource, i.e. they contain hyphens (-), not underscores (_). The dictionary values are the property values using the Python representations described in the documentation of the zhmcclient Python package.	success	dict	`{ "name": "vfunction-1", "description": "virtual function #1", "adapter-uri': "/api/adapters/...", ... }`

Notes ¶

Note

See also Ansible module zhmc_partition.

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.

Note

(D): This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged. The module documentation details page may explain more about this rationale.

Return Values ¶

Topics

Return Values
- Common
  - backup_file
  - changed
  - failed
  - invocation
  - msg
  - rc
  - results
  - skipped
  - stderr
  - stderr_lines
  - stdout
  - stdout_lines
- Internal use

Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by the ansible program. Each module can optionally document its own unique return values (visible through ansible-doc and https://docs.ansible.com).

This document covers return values common to all modules.

Note

Some of these keys might be set by Ansible itself once it processes the module’s return information.

Common ¶

backup_file ¶

For those modules that implement backup=no|yes when manipulating files, a path to the backup file created.

changed ¶

A boolean indicating if the task had to make changes.

failed ¶

A boolean that indicates if the task was failed or not.

invocation ¶

Information on how the module was invoked.

msg ¶

A string with a generic message relayed to the user.

rc ¶

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains ‘return code’ of these utilities.

results ¶

If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module ‘result’ per item.

skipped ¶

A boolean that indicates if the task was skipped or not

stderr ¶

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities.

stderr_lines ¶

When c(stderr) is returned we also always provide this field which is a list of strings, one item per line from the original.

stdout ¶

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities.

stdout_lines ¶

When c(stdout) is returned, Ansible always provides a list of strings, each containing one item per line from the original output.

Internal use ¶

These keys can be added by modules but will be removed from registered variables; they are ‘consumed’ by Ansible itself.

ansible_facts ¶

This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don’t require using a registered variable.

exception ¶

This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).

warnings ¶

This key contains a list of strings that will be presented to the user.

deprecations ¶

This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are msg and version, values are string, value for the version key can be an empty string.

Development¶

This section only needs to be read by developers of the zhmc-ansible-modules project. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.

Repository¶

The repository for the zhmc-ansible-modules project is on GitHub:

https://github.com/zhmcclient/zhmc-ansible-modules

Setting up the development environment¶

The development environment is pretty easy to set up.

Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.

Then, with a virtual Python environment active, clone the Git repo of this project and prepare the development environment with make setup:

$ git clone git@github.com:zhmcclient/zhmc-ansible-modules.git
$ cd zhmc-ansible-modules
$ make setup

This will install all prerequisites the project needs for its development.

Generally, this project uses Make to do things in the currently active Python environment. The command make help (or just make) displays a list of valid Make targets and a short description of what each target does.

Building the documentation¶

The ReadTheDocs (RTD) site is used to publish the documentation for the zhmc-ansible-modules project at http://zhmc-ansible-modules.readthedocs.io/

This page automatically gets updated whenever the master branch of the Git repo for this package changes.

In order to build the documentation locally from the Git work directory, issue:

$ make docs

The top-level document to open with a web browser will be build/docs/html/index.html.

Testing¶

To run unit tests in the currently active Python environment, issue one of these example variants of make test:

$ make test                                  # Run all unit tests
$ TESTCASES=test_resource.py make test       # Run only this test source file
$ TESTCASES=TestInit make test               # Run only this test class
$ TESTCASES="TestInit or TestSet" make test  # py.test -k expressions are possible

To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:

$ tox                              # Run all tests on all supported Python versions
$ tox -e py27                      # Run all tests on Python 2.7
$ tox -e py27 test_resource.py     # Run only this test source file on Python 2.7
$ tox -e py27 TestInit             # Run only this test class on Python 2.7
$ tox -e py27 TestInit or TestSet  # py.test -k expressions are possible

The positional arguments of the tox command are passed to py.test using its -k option. Invoke py.test --help for details on the expression syntax of its -k option.

Contributing¶

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

Test is required.
Each commit should only contain one “logical” change.
A “logical” change should be put into one commit, and not split over multiple commits.
Large new features should be split into stages.
The commit message should not only summarize what you have done, but explain why the change is useful.
The commit message must follow the format explained below.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

Format of commit messages¶

A commit message must start with a short summary line, followed by a blank line.

Optionally, the summary line may start with an identifier that helps identifying the type of change or the component that is affected, followed by a colon.

It can include a more detailed description after the summary line. This is where you explain why the change was done, and summarize what was done.

It must end with the DCO (Developer Certificate of Origin) sign-off line in the format shown in the example below, using your name and a valid email address of yours. The DCO sign-off line certifies that you followed the rules stated in DCO 1.1. In short, you certify that you wrote the patch or otherwise have the right to pass it on as an open-source patch.

We use GitCop during creation of a pull request to check whether the commit messages in the pull request comply to this format. If the commit messages do not comply, GitCop will add a comment to the pull request with a description of what was wrong.

Example commit message:

cookies: Add support for delivering cookies

Cookies are important for many people. This change adds a pluggable API for
delivering cookies to the user, and provides a default implementation.

Signed-off-by: Random J Developer <random@developer.org>

Use git commit --amend to edit the commit message, if you need to.

Use the --signoff (-s) option of git commit to append a sign-off line to the commit message with your name and email as known by Git.

If you like filling out the commit message in an editor instead of using the -m option of git commit, you can automate the presence of the sign-off line by using a commit template file:

Create a file outside of the repo (say, ~/.git-signoff.template) that contains, for example:

<one-line subject>

<detailed description>

Signed-off-by: Random J Developer <random@developer.org>

Configure Git to use that file as a commit template for your repo:
```
git config commit.template ~/.git-signoff.template
```

Releasing a version¶

This section shows the steps for releasing a version to PyPI.

It covers all variants of versions that can be released:

Releasing the master branch as a new major or minor version (M+1.0.0 or M.N+1.0)
Releasing a stable branch as a new update version (M.N.U+1)

This description assumes that you are authorized to push to the upstream repo at https://github.com/zhmcclient/zhmc-ansible-modules and that the upstream repo has the remote name origin in your local clone.

Switch to your work directory of your local clone of the zhmc-ansible-modules Git repo and perform the following steps in that directory.
Set shell variables for the version and branch to be released:
- MNU - Full version number M.N.U this release should have
- MN - Major and minor version numbers M.N of that full version
- BRANCH - Name of the branch to be released
When releasing the master branch (e.g. as version 0.6.0):
```
MNU=0.6.0
MN=0.6
BRANCH=master
```
When releasing a stable branch (e.g. as version 0.5.1):
```
MNU=0.5.1
MN=0.5
BRANCH=stable_$MN
```
Check out the branch to be released, make sure it is up to date with upstream, and create a topic branch for the version to be released:
```
git status  # Double check the work directory is clean
git checkout $BRANCH
git pull
git checkout -b release_$MNU
```
Edit the change log:
```
vi docs/changes.rst
```
and make the following changes in the section of the version to be released:
- Finalize the version to the version to be released.
- Remove the statement that the version is in development.
- Change the release date to today´s date.
- Make sure that all changes are described.
- Make sure the items shown in the change log are relevant for and understandable by users.
- In the “Known issues” list item, remove the link to the issue tracker and add text for any known issues you want users to know about.
- Remove all empty list items in that section.

Commit your changes and push them upstream:

git add docs/changes.rst
git commit -sm "Release $MNU"
git push --set-upstream origin release_$MNU

On GitHub, create a Pull Request for branch release_$MNU. This will trigger the CI runs in Travis and Appveyor.

Important: When creating Pull Requests, GitHub by default targets the master branch. If you are releasing a stable branch, you need to change the target branch of the Pull Request to stable_M.N.
On GitHub, close milestone M.N.U.
Perform a complete test:
```
tox
```
This should not fail because the same tests have already been run in the Travis CI. However, run it for additional safety before the release.
- If this test fails, fix any issues until the test succeeds. Commit the changes and push them upstream:
```
git add <changed-files>
git commit -sm "<change description with details>"
git push
```
  Wait for the automatic tests to show success for this change.
On GitHub, once the checks for this Pull Request succeed:
- Merge the Pull Request (no review is needed).
  
  Because this updates the stable_M.N branch, it triggers an RTD docs build of its stable version. However, because the git tag for this version is not assigned yet, this RTD build will show an incorrect version (a dev version based on the previous version tag). This will be fixed in a subsequent step.
- Delete the branch of the Pull Request (release_M.N.U)
Checkout the branch you are releasing, update it from upstream, and delete the local topic branch you created:
```
git checkout $BRANCH
git pull
git branch -d release_$MNU
```
Tag the version:

Important: This is the basis on which ‘pbr’ determines the package version. The tag string must be exactly the version string M.N.U.

Create a tag for the new version and push the tag addition upstream:
```
git status    # Double check the branch to be released is checked out
git tag $MNU
git push --tags
```
The pushing of the tag triggers another RTD docs build of its stable version, this time with the correct version as defined in the tag.

If the previous commands fail because this tag already exists for some reason, delete the tag locally and remotely:
```
git tag --delete $MNU
git push --delete origin $MNU
```
and try again.
On RTD, verify that it shows the correct version for its stable version:

RTD stable version: https://zhmc-ansible-modules.readthedocs.io/en/stable.

If it does not, trigger a build of RTD version “stable” on the RTD project page:

RTD build page: https://readthedocs.org/projects/zhmc-ansible-modules/builds/

Once that build is complete, verify again.
On GitHub, edit the new tag M.N.U, and create a release description on it. This will cause it to appear in the Release tab.

You can see the tags in GitHub via Code -> Releases -> Tags.
Do a fresh install of this version in your active Python environment. This ensures that ‘pbr’ determines the correct version. Otherwise, it may determine some development version.
```
make clobber install
make help    # Double check that it shows version ``M.N.U``
```
Upload the package to PyPI:
```
make upload
```
This will show the package version and will ask for confirmation.

Important: Double check that the correct package version (M.N.U, without any development suffix) is shown.

Attention!! This only works once for each version. You cannot re-release the same version to PyPI, or otherwise update it.

Verify that the released version arrived on PyPI: https://pypi.python.org/pypi/zhmc-ansible-modules/
If you released the master branch, it needs a new fix stream.

Create a branch for its fix stream and push it upstream:
```
git status    # Double check the branch to be released is checked out
git checkout -b stable_$MN
git push --set-upstream origin stable_$MN
```
Log on to the RTD project zhmc-ansible-modules and activate the new version (=branch) stable_M.N as a version to be built.

Starting a new version¶

This section shows the steps for starting development of a new version.

These steps may be performed right after the steps for Releasing a version, or independently.

This section covers all variants of new versions:

A new major or minor version for new development based upon the master branch.
A new update (=fix) version based on a stable branch.

This description assumes that you are authorized to push to the upstream repo at https://github.com/zhmcclient/zhmc-ansible-modules and that the upstream repo has the remote name origin in your local clone.

Switch to your work directory of your local clone of the zhmc-ansible-modules Git repo and perform the following steps in that directory.
Set shell variables for the version to be started and its base branch:
- MNU - Full version number M.N.U of the new version to be started
- MN - Major and minor version numbers M.N of that full version
- BRANCH - Name of the branch the new version is based upon
When starting a (major or minor) version (e.g. 0.6.0) based on the master branch:
```
MNU=0.6.0
MN=0.6
BRANCH=master
```
When starting an update (=fix) version (e.g. 0.5.1) based on a stable branch:
```
MNU=0.5.1
MN=0.5
BRANCH=stable_$MN
```
Check out the branch the new version is based on, make sure it is up to date with upstream, and create a topic branch for the new version:
```
git status  # Double check the work directory is clean
git checkout $BRANCH
git pull
git checkout -b start_$MNU
```

Edit the change log:

vi docs/changes.rst

and insert the following section before the top-most section:

Version 0.6.0
^^^^^^^^^^^^^

Released: not yet

**Incompatible changes:**

**Deprecations:**

**Bug fixes:**

**Enhancements:**

**Known issues:**

* See `list of open issues`_.

.. _`list of open issues`: https://github.com/zhmcclient/zhmc-ansible-modules/issues

Commit your changes and push them upstream:

git add docs/changes.rst
git commit -sm "Start $MNU"
git push --set-upstream origin start_$MNU

On GitHub, create a Pull Request for branch start_M.N.U.

Important: When creating Pull Requests, GitHub by default targets the master branch. If you are starting based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.
On GitHub, create a milestone for the new version M.N.U.

You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.
On GitHub, go through all open issues and pull requests that still have milestones for previous releases set, and either set them to the new milestone, or to have no milestone.
On GitHub, once the checks for this Pull Request succeed:
- Merge the Pull Request (no review is needed)
- Delete the branch of the Pull Request (start_M.N.U)
Checkout the branch the new version is based on, update it from upstream, and delete the local topic branch you created:
```
git checkout $BRANCH
git pull
git branch -d start_$MNU
```

Change log¶

Version 0.6.1¶

Released: 2019-01-08

Bug fixes:

Docs: Fixed change log of 0.6.0 (see the 0.6.0 section below).

Version 0.6.0¶

Released: 2019-01-07

Fixed this change log in 0.6.1

Bug fixes:

Fixed dependency to zhmcclient package to be >=0.20.0, instead of using its master branch from the github repo.
Updated the ‘requests’ package to 2.20.0 to fix the following vulnerability: https://nvd.nist.gov/vuln/detail/CVE-2018-18074
Added support for Python 3.7. This required increasing the minimum version of Ansible from 2.2.0.0 to 2.4.0.0. This also removes the dependency on the ‘pycrypto’ package, which has vulnerabilities and is no longer maintained since 2013. Ansible uses the ‘cryptography’ package, instead. See issue #66.
The crypto_number property of Adapter is an integer property, and thus the Ansible module zhmc_adapter needs to change the string passed by Ansible back to an integer. It did that correctly but only for the properties input parameter, and not for the match input parameter. The type conversions are now applied for all properties of Adapter also for the match parameter.
The dictionary to check input properties for the zhmc_cpc module had the acceptable_status property written with a hyphen instead of underscore. This had the effect that it was rejected as non-writeable when specifying it as input.

Enhancements:

Added support for managing CPCs by adding a zhmc_cpc Ansible module. The module allows setting writeable properties of a CPC in an idempotent way, and to gather facts for a CPC (i.e. all of its properties including a few artificial ones). See issue #82.
Added support for managing adapters by adding a zhmc_adapter Ansible module. The module allows setting writeable properties of an adapter, changing the adapter type for FICON Express adapters, and changing the crypto type for Crypto Express adapters, all in an idempotent way. It also allows gathering facts for an adapter (i.e. all of its properties# including a few artificial ones). See issue #83.
Added a zhmc_crypto_attachment Ansible module, which manages the attachment of crypto adapters and of crypto domains to partitions in an idempotent way. This was already supported in a less flexible and non-idempotent way by the zhmc_partition Ansible module.
Added support for adjusting the value of the ssc_ipv4_gateway input property for the zhmc_partition module to None if specified as the empty string. This allows defaulting the value more easily in playbooks.
Docs: Improved and fixed the documentation how to release a version and how to start a new version.

Version 0.5.0¶

Released: 2018-10-24

Incompatible changes:

Changed ‘make setup’ back to ‘make develop’ for consistency with the other zhmcclient projects.

Bug fixes:

Several fixes in the make process and package dependencies.
Synced package dependencies with zhmcclient project.

Enhancements:

Added support for DPM storage groups, attachments and volumes, by adding new modules ‘zhmc_storage_group’, ‘zhmc_storage_group_attachment’, and ‘zhmc_storage_volume’. Added several playbooks as examples.

Version 0.4.0¶

Released: 2018-03-15

Bug fixes:

Fixed the bug that a TypeError was raised when setting the ‘ssc_dns_servers’ property for a Partition. The property value is a list of strings, and lists of values were not supported previously. Extended the function test cases for partitions accordingly. (Issue #34).
Fixed that the “type” property for Partitions could not be specified. It is valid for Partition creation, and the only restriction is that its value cannot be changed once the Partition exists. Along with fixing the logic for such create-only properties, the same issue was also fixed for the adapter port related properties of HBAs. (Issue #31).
Improved the logic for handling create+update properties in case the resource does not exist, such that they are no longer updated in addition to being set during creation. The logic still supports updating as an alternative if the resource does not exist, for update-only properties (e.g. several properties in Partitions). (Fixed as part of issue #31).
Fixed the issue that a partition in “terminated” or “paused” status could not be made absent (i.e. deleted). Now, the partition is stopped which should bring it into “stopped” status, and then deleted. (Issue #29).

Enhancements:

Added get_facts.py script to examine usage of the Ansible 2.0 API.
Added support for gathering partition and child facts. The fact support is invoked by specifying state=facts. The fact support is implemented by returning the partition properties in the result. The returned partition properties are enriched by adding properties ‘hbas’, ‘nics’, ‘virtual-functions’ that are a list of the properties of the respective child elements of that partition. (Issue #32).

Version 0.3.0¶

Released: 2017-08-16

Incompatible changes:

Deprecations:

Bug fixes:

Enhancements:

Added support for specifying integer-typed and float-typed properties of Partitions, NICs, HBAs, and VFs also as decimal strings in the module input.
Specifying string typed properties of Partitions, NICs, HBAs, and VFs with Unicode characters no longer performs an unnecessary property update.

Dependencies:

Increased minimum Ansible release from 2.0.0.1 to 2.2.0.0.
Upgraded zhmcclient requirement to 0.15.0

Version 0.2.0¶

Released: 2017-07-20

This is the initial release.