O adapter updates, including optional partition migration

Synopsis 

This module performs update and upgrade for various system components as part of system maintenance or automation workflows.

Supports System Firmware update and upgrade.

Supports VIOS and I/O Adapters update.

Supports SR-IOV Adapters update based on supported system firmware levels.

Supports Logical Partition migration.

All updates and upgrades can be performed independently or combined in a single consolidated update operation.

Supports state=facts to retrieve information about available adapters without making any changes.

Requirements 

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

Python >= 3.9

Parameters 

hmc_host (True, str, None)
IP address or hostname of the target Hardware Management Console (HMC).

hmc_auth (True, dict, None)
Authentication credentials to connect to the HMC.

username (True, str, None)
Username for logging into the HMC.

password (optional, str, None)
Password for the HMC user.

system_name (True, str, None)
The name or MTMS (machine type model serial) of the managed system on which the operations are to be performed.

platform_config (optional, dict, None)
Defines the configuration for the operation to be performed, such as system firmware update/upgrade (including SR-IOV adapter updates) or VIOS updates (including I/O adapter updates).

Also supports performing partition migrations.

system_firmware_update (optional, dict, None)
System firmware update/upgrade configuration.

update_type (optional, str, None)
Type of firmware update/upgrade operation.

NoUpdate: System firmware update/upgrade is skipped, but SR-IOV adapter updates are still allowed.

Update: Applies an update.

Upgrade: Applies an upgrade.

When set to Update or Upgrade, the sriov_adapter_update will be implicit.

When set to NoUpdate, the fields repository and level are not required.

update_order (optional, int, None)
Priority order in which the update/upgrade should be applied.

repository (optional, str, IBMWebsite)
Specifies the source repository for the update image.

IBMWebsite uses IBM Fix Central as the source.

sftp uses an SFTP server as the source; requires the sftp block.

If not specified, it defaults to IBMWebsite.

level (optional, str, latest)
Specifies the firmware version level to apply.

If not provided, the latest available version will be used by default.

Not applicable when repository=sftp.

sftp (optional, dict, None)
SFTP connection and authentication details.

Required when repository=sftp.

hostname (optional, str, None)
Hostname or IP address of the SFTP server.

Required when repository=sftp.

directory (optional, str, None)
Directory on the SFTP server containing the firmware image.

Required when repository=sftp.

username (optional, str, None)
Username for SFTP authentication.

Required when repository=sftp.

password (optional, str, None)
Password for SFTP authentication.

Required unless keyfile is provided.

keyfile (optional, str, None)
Path to an SSH private key file.

Mutually exclusive with password.

sriov_adapter_update (optional, list, None)
List of SR-IOV adapter update configurations.

This option must not be provided if update_type is set to Update or Upgrade in system_firmware_update.

all (optional, bool, None)
Indicates whether the update should be applied to all adapters.

If set to True, the adapter_id field is not required.

adapter_id (optional, int, None)
ID of the specific adapter to be updated.

Required only when all is not specified.

subtype (optional, str, None)
Specifies the level of update to apply.

DriverOnly performs only the driver update.

Adapter performs both the adapter firmware and driver updates.

partition_migration (optional, dict, None)
Configuration for migrating logical partitions.

This option cannot be used alone.

Must be specified along with either vios_update or system_firmware_update.

is_quick_evac (optional, bool, None)
Indicates whether to perform a quick evacuation during partition migration.

Must always be set to True when performing partition migration.

destination_managed_system (optional, str, None)
Name of the target managed system to migrate partitions to.

leave_partition_in_target (optional, bool, False)
Whether to keep the partition in the target after platform update.

If not specified, the default is False.

vios_update (optional, list, None)
Configuration for updating Virtual I/O Servers.

update_type (optional, str, None)
Specifies the type of VIOS update to be performed.

NoUpdate: No update will be applied to VIOS, but I/O adapter updates are still allowed.

Update: Applies a VIOS update using the provided configuration. The I/O adapter update is performed implicitly.

When set to NoUpdate, the fields resource_type and vios_image_name are not required.

vios_name (optional, str, None)
Name of the VIOS partition to be updated.

update_order (optional, int, None)
Priority order in which the update should be applied relative to other components.

resource_type (optional, str, IBMWebsite)
Specifies the source repository for the update image.

IBMWebsite uses IBM Fix Central as the source.

sftp uses an SFTP server as the source; requires the sftp block.

If not specified, it defaults to IBMWebsite.

vios_image_name (optional, str, None)
Specifies the VIOS image name to apply.

Required when update_type=Update for both IBMWebsite and sftp.

sftp (optional, dict, None)
SFTP connection and authentication details.

Required when resource_type=sftp.

hostname (optional, str, None)
Hostname or IP address of the SFTP server.

Required when resource_type=sftp.

username (optional, str, None)
Username for SFTP authentication.

Required when resource_type=sftp.

password (optional, str, None)
Password for SFTP authentication.

Required unless ssh_key is provided.

ssh_key (optional, str, None)
Path to an SSH private key file used for SFTP authentication.

Mutually exclusive with password.

remote_directory (optional, str, None)
Directory on the SFTP server containing the VIOS image.

file_names (optional, list, None)
Specific files to download from the SFTP server.

Specified as a list; internally converted to a comma-separated string.

io_adapter_update (optional, list, None)
List of I/O adapters to update during VIOS update.

all (optional, bool, None)
Indicates whether all I/O adapters should be updated.

If set to True, the device field is not required.

device (optional, list, None)
List of I/O adapter device names to be updated.

Specify one or more device names as a list (e.g., ['ent0', 'ent1']).

Required only when all is not specified.

repository (optional, str, IBMWebsite)
Specifies the source repository for the update image.

IBMWebsite uses IBM Fix Central as the source.

sftp uses an SFTP server as the source; requires the sftp block.

If not specified, it defaults to IBMWebsite.

sftp (optional, dict, None)
SFTP connection and authentication details.

Required when repository=sftp.

hostname (optional, str, None)
Hostname or IP address of the SFTP server.

Required when repository=sftp.

directory (optional, str, None)
Directory on the SFTP server containing the adapter firmware.

Required when repository=sftp.

username (optional, str, None)
Username for SFTP authentication.

Required when repository=sftp.

password (optional, str, None)
Password for SFTP authentication.

Required unless keyfile is provided.

keyfile (optional, str, None)
Path to an SSH private key file.

Mutually exclusive with password.

state (optional, str, None)
facts gathers and returns information about available SR-IOV adapters, Virtual I/O Servers (VIOS), and I/O adapters without making any changes.

Notes 

Note

Supports IBM Fix Central website (IBMWebsite) and SFTP server (sftp) as update/upgrade sources.
For SFTP-based updates, the firmware or VIOS image must already be present on the SFTP server. The HMC connects to the SFTP server directly; no pre-staging to the HMC is required.
Supports defining the order in which updates and upgrades are applied across components.
To perform configuration operations, you do not need to specify a separate state or action. Supplying values under platform_config is sufficient to apply the changes directly to the HMC.
When performing an update or upgrade operation via IBMWebsite with level='latest', if the Ansible response status is ok and changed is False, and the result is COMPLETED_WITH_ERROR with the reason "update not available", it indicates that no newer update images are available or the target is already up-to-date.
This module will not satisfy the idempotency requirement of Ansible, even though it partially confirms it. For instance, if the module is tasked to update/upgrade the HMC to the same level, it will still go ahead with the operation and finally the changed state will be reported as false.
Upgrade the Power server after successfully evacuating the partition to the destination system, and ensure the partition is not returned to the original server.

Examples 

- name: Update a SR-IOV adapters (DriverOnly) using IBM Fix Central
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: NoUpdate
        update_order: 1
        sriov_adapter_update:
          - adapter_id: 1
            subtype: DriverOnly

- name: Update all SR-IOV adapters (Adapter) using IBM Fix Central (No Firmware Update)
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: NoUpdate
        update_order: 1
        sriov_adapter_update:
          - all: true
            subtype: Adapter

- name: Perform a System Firmware update using default level
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: Update
        update_order: 1

- name: Perform a System Firmware update using specified level (level 12)
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: Update
        update_order: 1
        level: 12

- name: Migrate a partition to a different managed system and perform a System Firmware update
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: Update
        update_order: 1
        repository: IBMWebsite
      partition_migration:
        is_quick_evac: true
        destination_managed_system: "p920_system"
        leave_partition_in_target: true

- name: Update VIOS to latest available level from IBM Fix Central
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: Update
          vios_name: "vios1"
          vios_image_name: "name"
          update_order: 1
          resource_type: IBMWebsite

- name: Update selected I/O adapters only (no VIOS update)
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: NoUpdate
          vios_name: <vios1>
          update_order: 1
          io_adapter_update:
            - device:
                - "ent0"
                - "ent1"
              repository: IBMWebsite

- name: Update VIOS to specific image and all I/O adapters from IBM Fix Central
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: NoUpdate
          vios_name: <vios1>
          update_order: 1
          resource_type: IBMWebsite
          io_adapter_update:
            - all: true
              repository: IBMWebsite

- name: Update multiple VIOS instances from IBM Fix Central with ordered execution
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: Update
          vios_name: <vios1>
          update_order: 1
          vios_image_name: "name"
          resource_type: IBMWebsite
        - update_type: Update
          vios_name: <vios2>
          update_order: 2
          vios_image_name: <name>
          resource_type: IBMWebsite

- name: Update System Firmware and VIOS with all I/O adapters from IBM Fix Central
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: Update
        update_order: 1
        repository: IBMWebsite
      vios_update:
        - update_type: Update
          vios_name: <vios1>
          update_order: 1
          vios_image_name: "name"
          resource_type: IBMWebsite
          io_adapter_update:
            - all: true
              repository: IBMWebsite

- name: Perform a System Firmware update from an SFTP server using password authentication
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      system_firmware_update:
        update_type: Update
        update_order: 1
        repository: sftp
        sftp:
          hostname: sftp.example.com
          directory: /firmware/images
          username: sftpuser
          password: sftppass

- name: Update VIOS from an SFTP server using SSH key authentication with specific files
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: Update
          vios_name: vios1
          update_order: 1
          resource_type: sftp
          vios_image_name: vios_package_name
          sftp:
            hostname: sftp.example.com
            username: sftpuser
            ssh_key: /home/hscroot/.ssh/id_rsa
            remote_directory: /vios/images
            file_names:
              - vios_image.tar.gz

- name: Update I/O adapters from an SFTP server using SSH key authentication
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    platform_config:
      vios_update:
        - update_type: NoUpdate
          vios_name: vios1
          update_order: 1
          io_adapter_update:
            - all: true
              repository: sftp
              sftp:
                hostname: sftp.example.com
                directory: /io/firmware
                username: sftpuser
                keyfile: /home/hscroot/.ssh/id_rsa

- name: Gather SR-IOV, VIOS, and I/O adapter facts
  platform_update:
    hmc_host: <host>
    hmc_auth:
      username: <hscroot>
      password: <hmcpass>
    system_name: <system_name>
    state: facts

Return Values 

result (always, dict, {‘changed’: True, ‘command_output’: {‘Key1’: ‘Value1’, ‘Key2’: ‘Value2’, ‘…’: ‘…’}}): Dictionary containing the outcome of the operation. Always includes changed indicating if the operation made any changes. The command_output key contains a dictionary with operation-specific details. The keys and values in command_output depend on the type of operation performed.

Status 

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

Authors

Chiranthan M V (@chiranthanmv)

platform_update – Applies consolidated system firmware (update/upgrade), VIOS, SR-IOV, and I/O adapter updates, including optional partition migration

Synopsis

Requirements

Parameters

Notes

Examples

Return Values

Status