hitachivantara.vspone_block.vsp.hv_truecopy module – Manages TrueCopy 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_truecopy.

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, re-syncing and resizing of TrueCopy pairs.
It also allows swap-splitting and swap-resyncing operations of TrueCopy pairs.
It supports various TrueCopy 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/truecopy.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 Hitachi storage system.
api_token string	This field is used to pass the value of the lock token of the secondary storage to operate on locked resources.
password string	Password for authentication.This is a required field if api_token is not provided.
username string	Username for authentication. This is a required field if api_token is not provided.
spec dictionary	Specification for the TrueCopy pairs task.
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.
consistency_group_id integer	Consistency Group ID, 0 to 255. This is an optional field.
copy_group_name string	Name of the copy group. This is a required field for create operation. For other operations, this field is optional, but when provided, the time to complete the operation is faster. Required for the Split TrueCopy pair by copy_group_name and primary volume ID /Resync TrueCopy pair by copy_group_name and copy_pair_name /Resync TrueCopy pair /Resync TrueCopy pair by copy_group_name and primary volume ID /Swap-Split TrueCopy pair by copy_group_name and copy_pair_name /Swap-Split TrueCopy pair /Swap-Split TrueCopy pair by copy_group_name and primary volume ID /Swap-Resync TrueCopy pair by copy_group_name and copy_pair_name /Swap-Resync TrueCopy pair /Swap-Resync TrueCopy pair by copy_group_name and primary volume ID /Delete TrueCopy pair by copy_group_name and copy_pair_name /Delete TrueCopy pair /Delete TrueCopy pair by copy_group_name and primary volume ID /Expand TrueCopy pair tasks.
copy_pace string	Copy speed. This is optional for the create operation. Default: `"3"`
copy_pair_name string	Name of the copy pair. This is a required field for create operation. For other operations, this field is optional, but when provided, the time to complete the operation is faster. Required for the Resync TrueCopy pair by copy_group_name and copy_pair_name /Resync TrueCopy pair /Swap-Split TrueCopy pair by copy_group_name and copy_pair_name /Swap-Split TrueCopy pair /Swap-Resync TrueCopy pair by copy_group_name and copy_pair_name /Swap-Resync TrueCopy pair /Delete TrueCopy pair by copy_group_name and copy_pair_name /Delete TrueCopy pair /Expand TrueCopy pair tasks.
do_initial_copy boolean	Perform initial copy. This is an optional field during create operation. 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.
fence_level string	Specifies the primary volume fence level setting and determines if the host is denied access or continues to access the primary volume when the pair is suspended because of an error. This is an optional field. Choices: `"NEVER"` ← (default) `"DATA"` `"STATUS"`
is_consistency_group boolean	This is an optional field during create operation. Depending on the value, this attribute specifies whether to register the new pair in a consistency group. If true, the new pair is registered in a consistency group. If false, the new pair is not registered in a consistency group. Choices: `false` ← (default) `true`
is_data_reduction_force_copy boolean	Force copy for data reduction. This is an optional field during create operation. Choices: `false` `true` ← (default)
is_new_group_creation boolean	Create a new copy group. This is an optional field during create operation. Choices: `false` `true`
is_svol_readwriteable boolean	It is applicable for split pair operation only. If true, the secondary volume will be read-writeable after split. Optional for the Split TrueCopy pair by specifying only the required fields /Split TrueCopy pair tasks. Choices: `false` ← (default) `true`
local_device_group_name string	Name of the local device group. This is an optional field.
new_volume_size string	Required only for resize or expand operation. Value should be greater than the current volume size.
path_group_id integer	This is an optional field during create operation. Specify the path group ID in the range from 0 to 255. If you are unsure don’t use this parameter. If you omit this value or specify 0, the lowest path group ID in the specified path group is used.
primary_volume_id string	Primary volume ID. This is a required field for create operation. Required for the Split TrueCopy pair by copy_group_name and primary volume ID /Resync TrueCopy pair by copy_group_name and primary volume ID /Swap-Split TrueCopy pair by copy_group_name and primary volume ID /Swap-Resync TrueCopy pair by copy_group_name and primary volume ID /Delete TrueCopy pair by copy_group_name and primary volume ID tasks.
provisioned_secondary_volume_id string	ID of the provisioned secondary volume that you want to use for the true copy creation. Required for the Create a TrueCopy pair with provisioned_secondary_volume_id /Create a TrueCopy pair with provisioned_secondary_volume_id and hostgroups tasks.
remote_device_group_name string	Name of the remote device group. This is an optional field.
secondary_hostgroup dictionary	Deprecated. Use secondary_hostgroups instead. Required for the Create a TrueCopy pair by specifying only the required fields /Create a TrueCopy pair with provisioned_secondary_volume_id and hostgroups /Create a TC pair using a range for secondary volume ID tasks.
lun_id integer	LUN ID of the host group on the secondary storage system. This is required for create operation.
name string / required	Name of the host group on the secondary storage system. This is required for create operation.
port_id aliases: port string / required	Port ID of the host group on the secondary storage system. This is required for create operation. port is deprecated, use port_id instead.
secondary_hostgroups list / elements=dictionary	List of hostgroup objects for the secondary volume.
lun_id integer	LUN ID of the host group on the secondary storage system. This is not required for create operation.
name string / required	Name of the host group on the secondary storage system. This is required for create operation.
port_id aliases: port string / required	Port ID of the host group on the secondary storage system. This is required for create operation. port is deprecated, use port_id instead.
secondary_iscsi_targets list / elements=dictionary	The list of iscsi targets on the secondary storage device. Required for the Create a TrueCopy-ISCSI pair by specifying only the required fields /Create a TrueCopy-ISCSI pair by specifying all the fields tasks.
lun_id integer	LUN ID. Required for the Create a TrueCopy-ISCSI pair by specifying only the required fields /Create a TrueCopy-ISCSI pair by specifying all the fields tasks.
name string / required	ISCSI target name. Required for the Create a TrueCopy-ISCSI pair by specifying only the required fields /Create a TrueCopy-ISCSI pair by specifying all the fields tasks.
port_id aliases: port string / required	Port ID. Required for the Create a TrueCopy-ISCSI pair by specifying only the required fields /Create a TrueCopy-ISCSI pair by specifying all the fields tasks. port is deprecated, use port_id instead.
secondary_nvm_subsystem dictionary	NVM subsystem details of the secondary volume. Required for the Create a TrueCopy-NVMe pair by specifying only the required fields /Create a TrueCopy-NVMe pair by specifying all the fields tasks.
name string / required	Name of the NVM subsystem on the secondary storage system. Required for the Create a TrueCopy-NVMe pair by specifying only the required fields /Create a TrueCopy-NVMe pair by specifying all the fields tasks.
paths list / elements=string	Host NQN paths information on the secondary storage system. Required for the Create a TrueCopy-NVMe pair by specifying only the required fields /Create a TrueCopy-NVMe pair by specifying all the fields tasks.
secondary_pool_id integer	ID of the dynamic pool where the secondary volume will be created. Required for the Create a TrueCopy pair by specifying only the required fields /Create a TC pair using a range for secondary volume ID /Create a TrueCopy-NVMe pair by specifying only the required fields /Create a TrueCopy-NVMe pair by specifying all the fields /Create a TrueCopy-ISCSI pair by specifying only the required fields /Create a TrueCopy-ISCSI pair by specifying all the fields tasks.
should_delete_svol boolean	Specify true to delete the SVOL. Optional for the Delete TrueCopy pair task. Choices: `false` ← (default) `true`
state string	The level of the TrueCopy pairs task. `present` is used to create or update a TrueCopy pair. `absent` is used to delete a TrueCopy pair. `expand` or `resize` is used to expand the size of the volumes of a TrueCopy pair. `resync` is used to re-sync a TrueCopy pair. `split` is used to split a TrueCopy pair. `swap-split` is used to swap-split a TrueCopy pair. `swap-resync` is used to swap-resync a TrueCopy pair. Choices: `"present"` ← (default) `"absent"` `"split"` `"resync"` `"resize"` `"expand"` `"swap_split"` `"swap_resync"`
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.
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.
Before managing a TrueCopy 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 TrueCopy pair through Ansible. For instructions, see Manage remote storage registration.
Before creating a TrueCopy pair, add the P-VOL to the host group, iSCSI target, or NVM subsystem on the primary storage system. Then, identify the host group to use on the secondary storage system.
For Create a TrueCopy pair by specifying only the required fields, by specifying all the fields, and using a range for secondary volume ID
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.)
For Expand TrueCopy pair
1. First, the S-VOL size is increased, followed by the P-VOL size. If the pair is in the PAIR state, it is split before resizing. Once the resize operation is complete, the pair is re-synchronized.
1. To use this API, enable System Option Mode (SOM) 1198 and disable SOM 1199 on both primary and secondary storage systems.

Examples

- name: Create a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "present"
    connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"
      primary_volume_id: 11
      is_consistency_group: true
      fence_level: 'NEVER'
      secondary_pool_id: 1
      secondary_hostgroup:
        name: ansible_test_group
        port_id: CL1-A
        lun_id: 1

- name: Split a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "split"
    connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

- name: Resync a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "resync"
    connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

- name: Swap-split a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "swap_split"
    connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

- name: Swap-resync a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "swap_resync"
    connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

- name: Delete a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "swap_resync"
    connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"

- name: Increase the size of the volumes of a TrueCopy pair
  hitachivantara.vspone_block.vsp.hv_truecopy:
    state: "expand"
    connection_info:
      address: 172.1.1.126
      username: "admin"
      password: "secret"
    secondary_connection_info:
      address: 172.1.1.127
      username: "admin"
      password: "secret"
    spec:
      copy_group_name: "copy_group_name_1"
      copy_pair_name: "copy_pair_name_1"
      new_volume_size: 4GB

Return Values

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

Key	Description
truecopy_info list / elements=dictionary	List of TrueCopy pair objects returned by the module. Returned: success
consistency_group_id integer	Consistency Group ID. Returned: success Sample: `-1`
copy_group_name string	Name of the copy group. Returned: success Sample: `"ESD_TC_CG"`
copy_pair_name string	Name of the copy pair. Returned: success Sample: `"ESD_TC_CP"`
copy_progress_rate integer	Deprecated.Copy progress rate. Returned: success Sample: `-1`
fence_level string	Fence level. Returned: success Sample: `"NEVER"`
local_device_group_name string	Name of the local device group to retrieve TrueCopy pair information for. Returned: success Sample: `"tc_bulk_cg_1P_"`
primary_volume_id integer	Primary volume ID. Returned: success Sample: `11`
primary_volume_id_hex string	Primary volume ID in hex format. Returned: success Sample: `"00:00:0B"`
primary_volume_size string	Size of the primary volume. Returned: success Sample: `"4.00GB"`
primary_volume_status string	Primary volume status. Returned: success Sample: `"PAIR"`
primary_volume_storage_serial_number string	Storage serial number of the primary volume. Returned: success Sample: `"810050"`
pvol_status string	Deprecated. Use primary_volume_status instead. Returned: success Sample: `"PAIR"`
pvol_storage_device_id string	Deprecated. PVOL storage device ID. Returned: success Sample: `"A00000970041"`
remote_device_group_name string	Name of the remote device group to retrieve TrueCopy pair information for. Returned: success Sample: `"tc_bulk_cg_1S_"`
remote_mirror_copy_pair_id string	Remote mirror copy pair ID. Returned: success Sample: `"A00000970045,ESD_TC_CG,ESD_TC_CGP_,ESD_TC_CGS_,ESD_TC_CP"`
secondary_volume_id integer	Secondary volume ID. Returned: success Sample: `11`
secondary_volume_id_hex string	Secondary volume ID in hex format. Returned: success Sample: `"00:00:0B"`
secondary_volume_size string	Size of the secondary volume. Returned: success Sample: `"4.00GB"`
secondary_volume_status string	Secondary volume status. Returned: success Sample: `"PAIR"`
secondary_volume_storage_serial_number string	Storage serial number of the secondary volume. Returned: success Sample: `"810045"`
storage_serial_number string	Deprecated. Use primary_volume_storage_serial_number instead. Returned: success Sample: `"810050"`
svol_status string	Deprecated. Use secondary_volume_status instead. Returned: success Sample: `"PAIR"`
svol_storage_device_id string	Deprecated. SVOL storage device ID. Returned: success Sample: `"A34000810045"`

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_truecopy_module.html