hitachivantara.vspone_block.vsp.hv_shadow_image_pair module – Manages shadow image pairs on VSP block storage systems.

Note

This module is part of the hitachivantara.vspone_block collection (version 4.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install hitachivantara.vspone_block. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: hitachivantara.vspone_block.vsp.hv_shadow_image_pair.

New in hitachivantara.vspone_block 3.0.0

Synopsis
Requirements
Parameters
Attributes
Notes
Examples
Return Values

Synopsis

This module allows for the creation, deletion, splitting, syncing, restoring and migrating of shadow image pairs on VSP block storage systems.
It supports various shadow image pairs operations based on the specified task level.
For examples, go to URL https://github.com/hitachi-vantara/vspone-block-ansible/blob/main/playbooks/vsp_direct/shadow_image_pair.yml

Requirements

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

python >= 3.9

Parameters

Parameter	Comments
connection_info dictionary / required	Information required to establish a connection to the storage system.
address string / required	IP address or hostname of the storage system.
api_token string	Token used to operate on locked resources.
connection_type string	Type of connection to the storage system. Choices: `"direct"` ← (default)
password string	Password for authentication. This is a required field.
username string	Username for authentication. This is a required field.
spec dictionary / required	Specification for the shadow image pairs task.
allocate_new_consistency_group boolean	New consistency group. Optional for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Create and auto-split a ShadowImage pair tasks. Choices: `false` `true`
auto_split boolean	Auto split. Optional for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume tasks. Choices: `false` `true`
consistency_group_id integer	Consistency group id. Optional for the Create and auto-split a ShadowImage pair task.
copy_group_name string	Copy group name. Required for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volum /Split a ShadowImage pair /Resync ShadowImage pair /Create and auto-split a ShadowImage pair /Restore a ShadowImage pair /Migrate ShadowImage pair /Cancel Migration of ShadowImage Pair /Delete ShadowImage pair /Delete ShadowImage pair with force delete /Create ShadowImage pair for an existing secondary volume for migration /Create ShadowImage pair for non-existing secondary volume for migration tasks.
copy_pace aliases: copy_pace_track_size string	Copy pace track size. Optional for the Create a ShadowImage pair for an existing secondary volume / Supports “SMALL”, “MEDIUM”, “LARGE” values or 1 to 15. /Create ShadowImage pair for non-existing secondary volume /Resync ShadowImage pair /Create and auto-split a ShadowImage pair /Restore a ShadowImage pair tasks.
copy_pair_name string	Copy pair name. Required for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Split a ShadowImage pair /Resync ShadowImage pair /Create and auto-split a ShadowImage pair /Restore a ShadowImage pair /Migrate ShadowImage pair /Cancel Migration of ShadowImage Pair /Delete ShadowImage pair /Delete ShadowImage pair with force delete /Create ShadowImage pair for an existing secondary volume for migration /Create ShadowImage pair for non-existing secondary volume for migration tasks.
create_for_migration boolean	Specify to create shadow image pair for migration. Required for the Create ShadowImage pair for an existing secondary volume for migration /Create ShadowImage pair for non-existing secondary volume for migration tasks. Choices: `false` `true`
enable_quick_mode boolean	Enable quick mode. Optional for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Split a ShadowImage pair /Resync ShadowImage pair /Restore a ShadowImage pair tasks. Choices: `false` `true`
enable_read_write boolean	Enable read write. Optional for the Split a ShadowImage pair task. Choices: `false` `true`
is_data_reduction_force_copy boolean	Enable data reduction force copy. Choices: `false` `true`
mirror_unit_number aliases: pvol_mu_number integer	Primary volume mirror unit number. Optional for the Create a ShadowImage pair.
pair_id string	Pair Id.
primary_volume_device_group_name string	Primary volume device name. Optional for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Create ShadowImage pair for an existing secondary volume for migration /Create ShadowImage pair for non-existing secondary volume for migration tasks.
primary_volume_id string	Primary volume id. Required for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Create and auto-split a ShadowImage pair /Create ShadowImage pair for an existing secondary volume for migration tasks. Optional for the Split a ShadowImage pair /Resync ShadowImage pair /Restore a ShadowImage pair /Delete ShadowImage pair /Delete ShadowImage pair with force delete /Create ShadowImage pair for non-existing secondary volume for migration tasks.
secondary_pool_id integer	Secondary storage pool id. Optional for the Create ShadowImage pair for non-existing secondary volume for migration task.
secondary_volume_device_group_name string	Secondary volume device name. Optional for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Create ShadowImage pair for an existing secondary volume for migration /Create ShadowImage pair for non-existing secondary volume for migration tasks.
secondary_volume_id string	Secondary volume id. Required for the Create a ShadowImage pair for an existing secondary volume /Create ShadowImage pair for non-existing secondary volume /Create and auto-split a ShadowImage pair /Create ShadowImage pair for an existing secondary volume for migration tasks. Optional for the Split a ShadowImage pair /Resync ShadowImage pair /Restore a ShadowImage pair /Delete ShadowImage pair /Delete ShadowImage pair with force delete tasks.
should_delete_svol boolean	Specify to delete SVOL from host group, iSCSI Target, and NVM Subsystem. Required for the Delete ShadowImage pair with force delete task. Choices: `false` `true`
should_force_split boolean	Specify to force split. Optional for the Cancel Migration of ShadowImage Pair task. Choices: `false` `true`
state string	The level of the shadow image pairs task. Choices are `present`, `absent`, `split`, `restore`, `sync`, `migrate`. Choices: `"present"` ← (default) `"absent"` `"split"` `"restore"` `"sync"` `"migrate"`
storage_system_info dictionary	Information about the storage system. This field is an optional field.
serial string	The serial number of the storage system.

Attributes

Attribute	Support	Description
check_mode	Support: none	Determines if the module should run in check mode.

Notes

Note

The output parameters entitlement_status, subscriber_id and partner_id were removed in version 3.4.0. They were also deprecated due to internal API simplification and are no longer supported.
Connection type gateway was removed starting from version 3.4.0. Please use an earlier version if you require this connection type.
During automatic SVOL creation in a pair setup, the system provisions a single secondary host group/iSCSI target.
The ShadowImage pair supports Fibre Channel, NVMe over FC, NVMe over TCP, and iSCSI protocols.
In Direct mode, you can create a ShadowImage pair without specifying a secondary volume ID. Instead, provide the secondary pool ID in the specification. Ansible then automatically creates the S-VOL and assigns it to the same NVMe subsystem, host group, and iSCSI target as the P-VOL.
For Create a ShadowImage pair for an existing secondary volume
1. When creating a ShadowImage pair, if the primary volume (P-VOL) is the same, use a different copy group name. If the P-VOL is different, you may reuse the same copy group name. The copy pair name must always be unique.
For Migrate ShadowImage pair
1. Once the data copy and synchronization between the source and target volumes are complete, the LDEV ID and host I/O of the source volume are swapped with those of the target volume. From the host perspective, the volume and path settings remain unchanged. However, the actual data now resides on the volume prepared for migration.
For Cancel Migration of ShadowImage Pair
1. If a pair migration is canceled, its status changes to SMPL, allowing you to restart the migration process.
For Create ShadowImage pair for an existing secondary volume for migration
1. When a volume migration pair is created, its status is set to SMPL. Data remains unchanged until the migration process begins.
For Create ShadowImage pair for non-existing secondary volume for migration
1. The S-VOL will be automatically created and mapped to same NVMe subsystem, host group, and iSCSI as the P-VOL. When a volume migration pair is created, the pair status is SMPL. Data is not copied until migration is performed.

Examples

- name: Create shadow image pair for non-existing secondary volume
  hitachivantara.vspone_block.vsp.hv_shadow_image_pair:
    connection_info:
      address: storage1.company.com
      username: "admin"
      password: "secret"
    state: "present"
    spec:
      primary_volume_id: 274
      secondary_pool_id: 1
      allocate_new_consistency_group: true
      copy_pace: "MEDIUM"
      enable_quick_mode: false
      auto_split: true
      copy_group_name: "CGTest"
      copy_pair_name: "CPTest"
      primary_volume_device_group_name: "CPTestP"
      secondary_volume_device_group_name: "CPTestS"

Return Values

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

Key	Description
data dictionary	Newly created shadow image pair object. Returned: success
consistency_group_id integer	Consistency group id. Returned: success Sample: `-1`
copy_group_name string	Copy group name. Returned: success Sample: `"SI172"`
copy_pace_track_size string	Copy pace track size. Returned: success Sample: `""`
copy_pair_name string	Copy pair name. Returned: success Sample: `"CPTest"`
copy_rate integer	Copy rate. Returned: success Sample: `100`
mirror_unit_id integer	Deprecated. Use mirror_unit_number instead. Returned: success Sample: `0`
mirror_unit_number integer	Mirror unit number. Returned: success Sample: `0`
primary_volume_host_groups list / elements=dictionary	Primary volume host groups. Returned: success Sample: `[{"host_group_name": "hostserver1153", "host_group_number": 189, "lun": 0, "port_id": "CL2-B"}]`
primary_volume_id integer	Primary volume id. Returned: success Sample: `172`
primary_volume_id_hex string	Primary hex volume id. Returned: success Sample: `"00:00:AC"`
primary_volume_iscsi_targets list / elements=dictionary	Primary volume iSCSI targets. Returned: success Sample: `[]`
primary_volume_nvm_subsystem_name string	Primary volume’s nvm subsystem name. Returned: success Sample: `""`
pvol_host_groups list / elements=dictionary	Deprecated. Use primary_volume_host_groups instead. Returned: success Sample: `[{"host_group_name": "hostserver1153", "host_group_number": 189, "lun": 0, "port_id": "CL2-B"}]`
pvol_iscsi_targets list / elements=dictionary	Deprecated. Use primary_volume_iscsi_targets instead. Returned: success Sample: `[]`
pvol_nvm_subsystem_name string	Deprecated. Use primary_volume_nvm_subsystem_name instead. Returned: success Sample: `""`
secondary_volume_host_groups list / elements=dictionary	Secondary volume host groups. Returned: success Sample: `[{"host_group_name": "hostserver1153", "host_group_number": 189, "lun": 1, "port_id": "CL2-B"}]`
secondary_volume_id integer	Secondary volume id. Returned: success Sample: `173`
secondary_volume_id_hex string	Secondary hex volume id. Returned: success Sample: `"00:00:AD"`
secondary_volume_iscsi_targets list / elements=dictionary	Secondary volume iSCSI targets. Returned: success Sample: `[]`
secondary_volume_nvm_subsystem_name string	Secondary volume’s nvm subsystem name. Returned: success Sample: `""`
status string	Status. Returned: success Sample: `"PAIR"`
storage_serial_number string	Storage serial number. Returned: success Sample: `"810050"`
svol_host_groups list / elements=dictionary	Deprecated. Use secondary_volume_host_groups instead. Returned: success Sample: `[{"host_group_name": "hostserver1153", "host_group_number": 189, "lun": 1, "port_id": "CL2-B"}]`
svol_iscsi_targets list / elements=dictionary	Deprecated. Use secondary_volume_iscsi_targets instead. Returned: success Sample: `[]`
svol_nvm_subsystem_name string	Deprecated. Use secondary_volume_nvm_subsystem_name instead. Returned: success Sample: `""`

Authors

Hitachi Vantara LTD (@hitachi-vantara)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/hitachivantara/vspone_block/vsp.hv_shadow_image_pair_module.html