nim_viosupgrade – Use NIM to upgrade VIOS(es) with the viosupgrade tool from a NIM master.
Synopsis
Uses the Network Installation Management (NIM) to performs the operations of backing up the virtual and logical configuration data, installing the specified image, and restoring the virtual and logical configuration data of the Virtual I/O Server (VIOS) from the NIM master.
The installation is a new and complete installation using the provided VIOS image, any customized configurations that might exist on the currently running system before the installation starts (including the timezone) are not included in the new installation image.
Requirements
The below requirements are needed on the host that executes this module.
AIX >= 7.2 TL3
Python >= 3.6
ios_mksysb VIOS level >= 3.1.0.0
Privileged user with authorizations: aix.system.install,aix.system.nim.config.server
Parameters
- action (True, str, None)
Specifies the operation to perform.
get_statusto get the status of an ongoing upgrade operation.
bosinstto perform a new and fresh installation on the current rootvg disk.
altdiskto perform a new installation on the alternative disk. The current rootvg disk on the VIOS partition is not impacted by this installation. The VIOS partition that has the current rootvg disk, remains in the running state during the installation of the alternative disk.- targets (optional, list, None)
Specifies the list of VIOSes NIM targets to update.
Either targets or target_file must be specified.
For an SSP cluster, the viosupgrade command must be run on individual nodes. Out of the n number of nodes in the SSP cluster, maximum n-1 nodes can be upgraded at the same time. Hence, you must ensure that at least one node is always active in the cluster and is not part of the upgrade process.
- target_file (optional, str, None)
Specifies the file name that contains the list of VIOS nodes.
Either targets or target_file must be specified.
The values and fields in the file must be specified in a particular sequence and format. The details of the format are specified in the /usr/samples/nim/viosupgrade.inst file and they are comma-separated. The maximum number of nodes that can be installed through the -f option is 30.
The VIOS images are installed on the nodes simultaneously.
For an SSP cluster, the viosupgrade command must be run on individual nodes. Out of the n number of nodes in the SSP cluster, maximum n-1 nodes can be upgraded at the same time. Hence, you must ensure that at least one node is always active in the cluster and is not part of the upgrade process.
Only the action and preview parameters will be considered while others should be provided in file.
- viosupgrade_params (False, dict, None)
Specifies the parameters for the viosupgrade command in a dictionary of disctionaries.
The keys of this dictionary can be the target name or the specific key ‘all’. Then associated parameters will apply to the target or all of them. When target_file is specified, then you must use the key ‘all’.
When building the viosugrade command, it will look first if the parameter is present for the target then into the ‘all’ section.
Valid keys are the follwoing.
ios_mksysb, specifies the ios_mksysb resource name on the NIM Master server for the specified VIOS installation.
spotname, when
action=bosinstit specifies the resource object name of the Shared Product Object Tree (SPOT) for NIM installation.rootvg_clone_disk, mandatory if
action=altdiskthis colon-separated list specifies alternative disks to install the selected VIOS image, current rootvg disk on the VIOS partition is not impacted by this installation. Whenaction=bosinst, the provided disks are used to clone the current rootvg. After the completion of the migration process, the current rootvg disk is installed with the provided image. The provided disks are at the VIOS level before the migration process.skip_rootvg_cloning, when
action=bosinstboolean (default=no) to skip the cloning of current rootvg disks to alternative disks and continues with the VIOS installation on the current rootvg disk.rootvg_install_disk, when
action=bosinstthis colon-separated list specifies new rootvg disks where the specified image must be installed instead of the existing rootvg disks, one and only one of rootvg_clone_disk or rootvg_install_disk or skip_rootvg_cloning must be specified.backup_file_resource, specifies the resource name of the VIOS configuration backup file.
resources, specifies the configuration resources to be applied after the installation, valid values are resolv_conf, script, fb_script, file_res, image_data, and log.
manage_cluster, boolean (default=yes) that specifies that cluster-level backup and restore operations are performed, mandatory for the VIOS that is part of an SSP cluster.
preview, boolean (default=false) that specifies only validation of VIOS hosts readyness for installation is performed, can be used for preview of the installation image only.
- vios_status (optional, dict, None)
Specifies the result of a previous operation.
If set then the vios_status of a target tuple must contain
SUCCESSto attempt update.If no vios_status value is found for a tuple, then returned status for this tuple is set to
SKIPPED-NO-PREV-STATUS.- nim_node (optional, dict, None)
Allows to pass along NIM node info from a task to another so that it discovers NIM info only one time for all tasks.
Notes
Note
See IBM documentation about requirements for the viosupgrade command at https://www.ibm.com/support/knowledgecenter/en/ssw_aix_72/v_commands/viosupgrade.html.
You can refer to the IBM documentation for additional information on the NIM concept at https://www.ibm.com/support/knowledgecenter/ssw_aix_72/install/nim_concepts.html,
The viosupgrade command on NIM server is supported from IBM AIX 7.2 with Technology Level 3, or later.
For NIM bosinst method of installation, supported current VIOS levels are 2.2.6.30, or later.
If the altinst_rootvg or old_rootvg disks are already available in the VIOS, you must rename them.
The disks that are specified for the VIOS installation must not be in use.
In an SSP cluster, you must ensure that at least one node is always active in the cluster and is not part of the upgrade process.
If the viosupgrade command fails to restore all of the mappings, you must manually re-initiate the restore operation on the VIOS.
If you have installed any additional software on the VIOS apart from what is supplied as part of the base VIOS image, the viosupgrade command might fail to restore configurations that are related to that software. To manage this scenario, you must create a customized VIOS image with the software applications that you might want to include and provide this customized VIOS image as an input to the viosupgrade command for installation.
Examples
- name: Validate an altdisk viosupgrade, no change on the vios
nim_viosupgrade:
action: altdisk
targets: nimvios01
viosupgrade_params:
all:
resources: master_net_conf:logdir
manage_cluster: false
preview: true
nimvios01:
ios_mksysb: vios-3-1-1-0_sysb
rootvg_clone_disk: hdisk1
backup_file_resource: nimvios01_iosb
- name: Perform an altdisk viosupgrade
nim_viosupgrade:
action: altdisk
targets: nimvios01
viosupgrade_params:
all:
resources: master_net_conf:logdir
manage_cluster: false
preview: false
nimvios01:
ios_mksysb: vios-3-1-1-0_sysb
rootvg_clone_disk: hdisk1
backup_file_resource: nimvios01_iosb
- name: Wait for up to an hour for the viosupgrade status to complete
nim_viosupgrade:
action: get_status
targets: nimvios01
register: result
until: result.status['nimvios01'] != 'ONGOING'
retries: 30
delay: 120
- name: Validate an bosinst viosupgrade, no change on the vios
nim_viosupgrade:
action: bosinst
targets: nimvios02
viosupgrade_params:
all:
resources: master_net_conf:logdir:my_filebackup_res
manage_cluster: false
preview: true
nimvios02:
ios_mksysb: vios-3-1-1-0_sysb
spotname: vios-3-1-1-0_spot
rootvg_install_disk: "hdisk1:hdisk2"
skip_rootvg_cloning: false
backup_file_resource: nimvios02_iosb
Return Values
- msg (always, str, )
Status information.
- targets (always, list, [‘vios1’, ‘vios2’, ‘…’])
List of NIM client actually targeted for the operation.
- status (always, dict, { vios1: ‘SUCCESS’, vios2: ‘FAILURE’ })
Status of the operation for each VIOS
target. It can be empty, SUCCESS or FAILURE.When
target_fileis set, then the key is ‘all’.- cmd (If the command was run when C(target_file) is set., str, )
Command executed.
- stdout (If the command was run when C(target_file) is set., str, )
Standard output of the command.
- stderr (If the command was run when C(target_file) is set., str, )
Standard error of the command.
- nim_node (always, dict, {‘nim_node’: {‘vios’: {‘vios1’: {‘Cstate’: ‘ready for a NIM operation’, ‘Cstate_result’: ‘success’, ‘Mstate’: ‘currently running’, ‘cable_type1’: ‘N/A’, ‘class’: ‘management’, ‘connect’: ‘nimsh’, ‘cpuid’: ‘00F600004C00’, ‘if1’: ‘master_net vios1.aus.stglabs.ibm.com 0’, ‘mgmt_profile1’: ‘p8-hmc 1 vios-cec’, ‘netboot_kernel’: ‘64’, ‘platform’: ‘chrp’, ‘prev_state’: ‘alt_disk_install operation is being performed’}}}})
NIM node info. It can contains more information if passed as option nim_node.
- vios (always, dict, )
List of VIOS NIM resources.
- meta (always, dict, )
Detailed information on the module execution.
- messages (always, list, )
Details on errors/warnings not related to a specific target vios.
- <vios> (when target is actually a NIM client, dict, )
Detailed information on the execution on the target vios. Can be ‘all’.
- messages (always, list, )
Details on errors/warnings.
- cmd (If the command was run., str, )
Command executed.
- stdout (If the command was run., str, )
Standard output of the command.
- stderr (If the command was run., str, )
Standard error of the command.
Status
This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by community.