hitachivantara.vspone_block.vsp.hv_gad module – Manages GAD 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_gad.

New in hitachivantara.vspone_block 3.1.0

Synopsis
Requirements
Parameters
Attributes
Notes
Examples
Return Values

Synopsis

This module allows for the creation, deletion, splitting, and resynchronization of GAD pairs on VSP block storage systems.
It supports various GAD 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/gad_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.
secondary_connection_info dictionary	Information required to establish a connection to the secondary storage system.
address string / required	IP address or hostname of the secondary storage.
api_token string	Value of the lock token to operate on locked resources.
password string	Password for authentication. This field is required for secondary storage connection if api_token is not provided.
username string	Username for authentication. This field is required for secondary storage connection if api_token is not provided.
spec dictionary / required	Specification for the GAD pairs task.
allocate_new_consistency_group boolean	Allocate and assign a new consistency group ID. Required for the Create GAD pair with server cluster configuration /Create GAD pair with cross path server configuration tasks. Choices: `false` `true`
begin_secondary_volume_id string	Specify beginning ldev id for LDEV range for svol. This is an optional field during create operation. If this field is specified, end_secondary_volume_id must also be specified. If this field is not specified, Ansible modules will try to create SVOL ID same as the PVOL ID if available, otherwise it will use the first available LDEV ID. Required for the Create a GAD pair using a range for secondary volume id task.
consistency_group_id integer	Consistency Group ID.
copy_group_name string	The name for the copy group. Required for the Create/Split/Resync/Delete/Swap-Split/Swap-Resync/Expand tasks.
copy_pace string	Copy pace to be used for the GAD pair, Supports “SMALL”, “MEDIUM”, “LARGE” values or 1 to 15. Default: `"3"`
copy_pair_name string	The name for the pair in the copy group. Required for the Create/Split/Resync/Swap-Split/Swap-Resync/Expand tasks.
do_initial_copy boolean	Whether to perform an initial copy. Choices: `false` `true` ← (default)
end_secondary_volume_id string	Specify end ldev id for LDEV range for svol. This is an optional field during create operation. If this field is specified, begin_secondary_volume_id must also be specified. If this field is not specified, Ansible modules will try to create SVOL ID same as PVOL ID iff available, otherwise it will use the first available LDEV ID. Required for the Create a GAD pair using a range for secondary volume id task.
fence_level string	Fence level. Choices: `"NEVER"` ← (default) `"DATA"` `"STATUS"` `"UNKNOWN"`
is_consistency_group boolean	Specify true for consistency group. Choices: `false` `true`
is_data_reduction_force_copy boolean	Whether to forcibly create a pair. Choices: `false` `true` ← (default)
is_new_group_creation boolean	Specify true for a new copy group name. Choices: `false` `true`
local_device_group_name string	The device group name in the local storage system. Optional for the Split/Resync/Swap-Split/Swap-Resync tasks.
mirror_unit_number aliases: mu_number integer	The mirror unit number.
new_volume_size string	Required for resize or expand operation. Value should be grater than the current volume size. Required for the Expand GAD pair task.
path_group_id integer	Path group ID.
primary_hostgroups list / elements=dictionary	The list of host groups on the primary storage device. Required for the Create GAD pair with server cluster configuration task.
enable_preferred_path boolean	Enables the preferred path for the specified host group. Required for the Create GAD pair with server cluster configuration /Create GAD pair with cross path server configuration tasks. Choices: `false` `true`
lun_id integer	LUN ID.
name string / required	Host group name. Required for the Create GAD pair with server cluster configuration /Create GAD pair with cross path server configuration tasks.
port_id aliases: port string / required	Port ID. Required for the Create GAD pair with server cluster configuration /Create GAD pair with cross path server configuration tasks. port field is deprecated, port_id should be used instead.
primary_resource_group_name string	The primary resource group name. Required for the Create GAD pair with cross path server configuration task.
primary_storage_serial_number string	The serial number of the primary storage device.
primary_volume_id string	Primary Volume ID. Required for the Create/Delete tasks.
provisioned_secondary_volume_id string	ID of the provisioned secondary volume that you want to use for the GAD pair creation. Required for the Create a GAD pair with provisioned secondary volume id task.
quorum_disk_id integer	The quorum disk ID. Required for the Create tasks.
remote_device_group_name string	The device group name in the remote storage system. Optional for the Split/Resync/Swap-Split/Swap-Resync tasks.
secondary_hostgroups list / elements=dictionary	The list of host groups on the secondary storage device. Required for the Create tasks.
enable_preferred_path boolean	Enables the preferred path for the specified host group. Required for the Create tasks. Choices: `false` `true`
lun_id integer	LUN ID. Required for the Create tasks.
name string / required	Host group name. Required for the Create tasks.
port_id aliases: port string / required	Port ID. Required for the Create tasks. port field is deprecated, port_id should be used instead.
secondary_iscsi_targets list / elements=dictionary	The list of iscsi targets on the secondary storage device. Required for the Create GAD-ISCSI Pair task.
enable_preferred_path boolean	Enables the preferred path for the specified ISCSI target. Required for the Create GAD-ISCSI Pair task. Choices: `false` `true`
lun_id integer	LUN ID. Required for the Create GAD-ISCSI Pair task.
name string / required	ISCSI target name. Required for the Create GAD-ISCSI Pair task.
port_id aliases: port string / required	Port ID. Required for the Create GAD-ISCSI Pair task. port field is deprecated, port_id should be used instead.
secondary_nvm_subsystem dictionary	NVM subsystem details of the secondary volume. Required for the Create GAD-NVMe Pair task.
name string / required	Name of the NVM subsystem on the secondary storage system. Required for the Create GAD-NVMe Pair task.
paths list / elements=string	Host NQN paths information on the secondary storage system. Required for the Create GAD-NVMe Pair task.
secondary_pool_id integer	Pool ID of the secondary storage system. Required for the Create tasks.
secondary_resource_group_name string	The secondary resource group name.
secondary_storage_serial_number string	The serial number of the secondary storage device.
set_alua_mode boolean	Set the ALUA mode to True. Required for the Create GAD pair with cross path server configuration task. Choices: `false` `true`
should_delete_svol boolean	Specify true to delete the SVOL. Choices: `false` ← (default) `true`
state string	The level of the GAD pairs task. Choices: `"present"` ← (default) `"absent"` `"split"` `"resync"` `"swap_split"` `"swap_resync"` `"resize"` `"expand"`
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

Connection type gateway was removed starting from version 3.4.0. Please use an earlier version if you require this connection type.
Ansible modules use a technology called copy group to manage all remote replication pair types (GAD, TC, HUR). Therefore, replication pairs created by tools that do not use copy group technology are not compatible with the Ansible modules. As a result, replication pairs created without copy group technology cannot be managed by the Ansible modules.
This module supports Fibre Channel, iSCSI, NVMe Fibre Channel, and NVMe TCP-based GAD pairs.
For GAD single server, cluster, and crosspath configurations
1. Before managing a GAD pair through Ansible Direct Connect, you must register (or pair) the source and target storage systems in the source storage’s API server. This step is required because Ansible uses REST API calls on the backend. If you skip this step—especially if you are unfamiliar with Hitachi’s REST API—you will encounter errors when managing a GAD pair through Ansible. For instructions, see Manage remote storage registration.
1. After creating the secondary host group, you must manually add it to the VSM resource group.
1. A valid WWN should be added to the host groups (primary and secondary).
1. Before executing the GAD playbook, make sure that remote paths and the quorum disk are configured correctly as mentioned in the User Guide for GAD.
1. For VSM to VSM GAD, a common VSM must be created on the primary and secondary storage systems.
1. Add the P-VOL and host group to the VSM. Map the P-VOL to the host group.
1. After adding a P-VOL to the VSM, the virtual ID of the P-VOL becomes the ‘GAD Reserve’ or 65534. Hence, update the virtual ID of the P-VOL using the Update volume with virtual ldev task from the LDEV playbook. The P-VOL’s physical and virtual ID must match.
1. Add the secondary host group to the VSM.
1. If the P-VOL is unnamed, the S-VOL will be assigned a name in the format smrha-[ldev_id]. If the P-VOL has a name, the S-VOL should use the same name. (Here, smrha stands for Storage Module Red Hat Ansible.)

Examples

- name: Swap-Split a GAD pair
  hitachivantara.vspone_block.vsp.hv_gad:
    state: "swap_split"
    connection_info:
      address: storage1.company.com
      username: "username"
      password: "password"
    secondary_connection_info:
      address: storage2.company.com
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "gad_copy_group_name_8"
      copy_pair_name: "gad_copy_pair_name_8"
      local_device_group_name: "gad_local_device_group_name_8"
      remote_device_group_name: "gad_remote_device_group_name_8"

- name: Swap-Resync a GAD pair
  hitachivantara.vspone_block.vsp.hv_gad:
    state: "swap_resync"
    connection_info:
      address: storage2.company.com
      username: "username"
      password: "password"
    secondary_connection_info:
      address: storage1.company.com
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "gad_copy_group_name_8"
      copy_pair_name: "gad_copy_pair_name_8"
      local_device_group_name: "gad_local_device_group_name_8"
      remote_device_group_name: "gad_remote_device_group_name_8"

- name: Increase size of volumes of a GAD pair
  hitachivantara.vspone_block.vsp.hv_gad:
    state: "resize"
    connection_info:
      address: storage1.company.com
      username: "username"
      password: "password"
    secondary_connection_info:
      address: storage2.company.com
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "gad_copy_group_name_9"
      copy_pair_name: "gad_copy_pair_name_9"
      new_volume_size: "4GB"

- name: Create a GAD-NVMe pair
  hitachivantara.vspone_block.vsp.hv_gad:
    state: "present"
    connection_info:
      address: storage1.company.com
      username: "username"
      password: "password"
    secondary_connection_info:
      address: storage2.company.com
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

      primary_volume_id: 12
      secondary_pool_id: 1
      secondary_nvm_subsystem:
        name: gk-nvm-sub-75
        paths:
          - "nqn.2014-08.com.ucpa-sc-hv:nvme:gk-test-12346"
      quorum_disk_id: 1

- name: Create a GAD-ISCSI pair
  hitachivantara.vspone_block.vsp.hv_gad:
    state: "present"
    connection_info:
      address: storage1.company.com
      username: "username"
      password: "password"
    secondary_connection_info:
      address: storage2.company.com
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

      primary_volume_id: 12
      secondary_pool_id: 1
      secondary_iscsi_targets:
        - name: "test"
          port_id: "CL1-A"
          enable_preferred_path: false
          lun_id: 1
      quorum_disk_id: 1

Return Values

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

Key	Description
data dictionary	Newly created GAD 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: `"cp_group_840"`
copy_pace_track_size integer	Deprecated. Copy pace track size. Returned: success Sample: `""`
copy_pair_name string	Pair name. Returned: success Sample: `"gad_pair_840"`
copy_rate string	Deprecated. Copy rate. Returned: success Sample: `""`
fence_level string	Fence level. Returned: success Sample: `"NEVER"`
is_alua_enabled boolean	Whether ALUA is enabled or not. Returned: success Sample: `false`
local_device_group_name string	Local device group name. Returned: success Sample: `"cp_group_840S_"`
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_virtual_serial_number integer	Primary virtual serial number. Returned: success Sample: `-1`
primary_virtual_volume_id integer	Primary virtual volume id. Returned: success Sample: `-1`
primary_volume_id integer	Primary volume ID. Returned: success Sample: `840`
primary_volume_id_hex string	Primary volume ID in hexadecimal format. Returned: success Sample: `"00:03:48"`
primary_volume_size string	Size of the primary volume. Returned: success Sample: `"4.00GB"`
primary_volume_status string	Status of the GAD pair. Returned: success Sample: `"PSUE"`
primary_volume_storage_id string	Deprecated. Use primary_volume_storage_serial_number instead. Returned: success Sample: `"810050"`
primary_volume_storage_serial_number string	Primary volume storage serial number. Returned: success Sample: `"810050"`
primary_vsm_resource_group_name string	Primary VSM resource group name. Returned: success Sample: `""`
quorum_disk_id integer	Quorum disk ID. Returned: success Sample: `21`
remote_device_group_name string	Remote device group name. Returned: success Sample: `"cp_group_840P_"`
remote_mirror_copy_pair_id string	Deprecated. Remote mirror copy pair ID. Returned: success Sample: `"A34000810050,cp_group_840,cp_group_840S_,cp_group_840P_,gad_pair_840"`
secondary_virtual_serial_number integer	Secondary virtual storage serial number. Returned: success Sample: `-1`
secondary_virtual_volume_id integer	Secondary virtual volume ID. Returned: success Sample: `-1`
secondary_volume_id integer	Secondary volume ID. Returned: success Sample: `831`
secondary_volume_id_hex string	Secondary volume ID in hexadecimal format. Returned: success Sample: `"00:03:3F"`
secondary_volume_size string	Size of the secondary volume. Returned: success Sample: `"4.00GB"`
secondary_volume_status string	Status of the GAD pair. Returned: success Sample: `"PSUE"`
secondary_volume_storage_id string	Deprecated. Use secondary_volume_storage_serial_number instead. Returned: success Sample: `"810045"`
secondary_volume_storage_serial_number string	Secondary volume storage serial number. Returned: success Sample: `"810045"`
secondary_vsm_resource_group_name string	Secondary VSM resource group name. 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_gad_module.html