2019/01/14 - AWS Storage Gateway - 2 new 4 updated api methods
Changes JoinDomain API supports two more parameters: organizational unit(OU) and domain controllers. Two new APIs are introduced: DetachVolume and AttachVolume.
Connects a volume to an iSCSI connection and then attaches the volume to the specified gateway. Detaching and attaching a volume enables you to recover your data from one gateway to a different gateway without creating a snapshot. It also makes it easier to move your volumes from an on-premises gateway to a gateway hosted on an Amazon EC2 instance.
See also: AWS API Documentation
Request Syntax
client.attach_volume(
GatewayARN='string',
TargetName='string',
VolumeARN='string',
NetworkInterfaceId='string',
DiskId='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway that you want to attach the volume to.
string
The name of the iSCSI target used by an initiator to connect to a volume and used as a suffix for the target ARN. For example, specifying TargetName as myvolume results in the target ARN of arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/target/iqn.1997-05.com.amazon:myvolume . The target name must be unique across all volumes on a gateway.
If you don't specify a value, Storage Gateway uses the value that was previously used for this volume as the new target name.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the volume to attach to the specified gateway.
string
[REQUIRED]
The network interface of the gateway on which to expose the iSCSI target. Only IPv4 addresses are accepted. Use DescribeGatewayInformation to get a list of the network interfaces available on a gateway.
Valid Values: A valid IP address.
string
The unique device ID or other distinguishing data that identifies the local disk used to create the volume. This value is only required when you are attaching a stored volume.
dict
Response Syntax
{
'VolumeARN': 'string',
'TargetARN': 'string'
}
Response Structure
(dict) --
AttachVolumeOutput
VolumeARN (string) --
The Amazon Resource Name (ARN) of the volume that was attached to the gateway.
TargetARN (string) --
The Amazon Resource Name (ARN) of the volume target, which includes the iSCSI name for the initiator that was used to connect to the target.
Disconnects a volume from an iSCSI connection and then detaches the volume from the specified gateway. Detaching and attaching a volume enables you to recover your data from one gateway to a different gateway without creating a snapshot. It also makes it easier to move your volumes from an on-premises gateway to a gateway hosted on an Amazon EC2 instance.
See also: AWS API Documentation
Request Syntax
client.detach_volume(
VolumeARN='string',
ForceDetach=True|False
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the volume to detach from the gateway.
boolean
Set to true to forcibly remove the iSCSI connection of the target volume and detach the volume. The default is false . If this value is set to false , you must manually disconnect the iSCSI connection from the target volume.
dict
Response Syntax
{
'VolumeARN': 'string'
}
Response Structure
(dict) --
AttachVolumeOutput
VolumeARN (string) --
The Amazon Resource Name (ARN) of the volume that was detached.
{'CachediSCSIVolumes': {'TargetName': 'string',
'VolumeAttachmentStatus': 'string'}}
Returns a description of the gateway volumes specified in the request. This operation is only supported in the cached volume gateway types.
The list of gateway volumes in the request must be from one gateway. In the response Amazon Storage Gateway returns volume information sorted by volume Amazon Resource Name (ARN).
See also: AWS API Documentation
Request Syntax
client.describe_cached_iscsi_volumes(
VolumeARNs=[
'string',
]
)
list
[REQUIRED]
(string) --
dict
Response Syntax
{
'CachediSCSIVolumes': [
{
'VolumeARN': 'string',
'VolumeId': 'string',
'VolumeType': 'string',
'VolumeStatus': 'string',
'VolumeAttachmentStatus': 'string',
'VolumeSizeInBytes': 123,
'VolumeProgress': 123.0,
'SourceSnapshotId': 'string',
'VolumeiSCSIAttributes': {
'TargetARN': 'string',
'NetworkInterfaceId': 'string',
'NetworkInterfacePort': 123,
'LunNumber': 123,
'ChapEnabled': True|False
},
'CreatedDate': datetime(2015, 1, 1),
'VolumeUsedInBytes': 123,
'KMSKey': 'string',
'TargetName': 'string'
},
]
}
Response Structure
(dict) --
A JSON object containing the following fields:
CachediSCSIVolumes (list) --
An array of objects where each object contains metadata about one cached volume.
(dict) --
Describes an iSCSI cached volume.
VolumeARN (string) --
The Amazon Resource Name (ARN) of the storage volume.
VolumeId (string) --
The unique identifier of the volume, e.g. vol-AE4B946D.
VolumeType (string) --
One of the VolumeType enumeration values that describes the type of the volume.
VolumeStatus (string) --
One of the VolumeStatus values that indicates the state of the storage volume.
VolumeAttachmentStatus (string) --
A value that indicates whether a storage volume is attached to or detached from a gateway.
VolumeSizeInBytes (integer) --
The size, in bytes, of the volume capacity.
VolumeProgress (float) --
Represents the percentage complete if the volume is restoring or bootstrapping that represents the percent of data transferred. This field does not appear in the response if the cached volume is not restoring or bootstrapping.
SourceSnapshotId (string) --
If the cached volume was created from a snapshot, this field contains the snapshot ID used, e.g. snap-78e22663. Otherwise, this field is not included.
VolumeiSCSIAttributes (dict) --
An VolumeiSCSIAttributes object that represents a collection of iSCSI attributes for one stored volume.
TargetARN (string) --
The Amazon Resource Name (ARN) of the volume target.
NetworkInterfaceId (string) --
The network interface identifier.
NetworkInterfacePort (integer) --
The port used to communicate with iSCSI targets.
LunNumber (integer) --
The logical disk number.
ChapEnabled (boolean) --
Indicates whether mutual CHAP is enabled for the iSCSI target.
CreatedDate (datetime) --
The date the volume was created. Volumes created prior to March 28, 2017 don’t have this time stamp.
VolumeUsedInBytes (integer) --
The size of the data stored on the volume in bytes.
Note
This value is not available for volumes created prior to May 13, 2015, until you store data on the volume.
KMSKey (string) --
The Amazon Resource Name (ARN) of the AWS KMS key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
TargetName (string) --
The name of the iSCSI target that is used by an initiator to connect to a volume and used as a suffix for the target ARN. For example, specifying TargetName as myvolume results in the target ARN of arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/target/iqn.1997-05.com.amazon:myvolume .
{'StorediSCSIVolumes': {'TargetName': 'string',
'VolumeAttachmentStatus': 'string'}}
Returns the description of the gateway volumes specified in the request. The list of gateway volumes in the request must be from one gateway. In the response Amazon Storage Gateway returns volume information sorted by volume ARNs. This operation is only supported in stored volume gateway type.
See also: AWS API Documentation
Request Syntax
client.describe_stored_iscsi_volumes(
VolumeARNs=[
'string',
]
)
list
[REQUIRED]
An array of strings where each string represents the Amazon Resource Name (ARN) of a stored volume. All of the specified stored volumes must from the same gateway. Use ListVolumes to get volume ARNs for a gateway.
(string) --
dict
Response Syntax
{
'StorediSCSIVolumes': [
{
'VolumeARN': 'string',
'VolumeId': 'string',
'VolumeType': 'string',
'VolumeStatus': 'string',
'VolumeAttachmentStatus': 'string',
'VolumeSizeInBytes': 123,
'VolumeProgress': 123.0,
'VolumeDiskId': 'string',
'SourceSnapshotId': 'string',
'PreservedExistingData': True|False,
'VolumeiSCSIAttributes': {
'TargetARN': 'string',
'NetworkInterfaceId': 'string',
'NetworkInterfacePort': 123,
'LunNumber': 123,
'ChapEnabled': True|False
},
'CreatedDate': datetime(2015, 1, 1),
'VolumeUsedInBytes': 123,
'KMSKey': 'string',
'TargetName': 'string'
},
]
}
Response Structure
(dict) --
StorediSCSIVolumes (list) --
(dict) --
Describes an iSCSI stored volume.
VolumeARN (string) --
The Amazon Resource Name (ARN) of the storage volume.
VolumeId (string) --
The unique identifier of the volume, e.g. vol-AE4B946D.
VolumeType (string) --
One of the VolumeType enumeration values describing the type of the volume.
VolumeStatus (string) --
One of the VolumeStatus values that indicates the state of the storage volume.
VolumeAttachmentStatus (string) --
A value that indicates whether a storage volume is attached to, detached from, or is in the process of detaching from a gateway.
VolumeSizeInBytes (integer) --
The size of the volume in bytes.
VolumeProgress (float) --
Represents the percentage complete if the volume is restoring or bootstrapping that represents the percent of data transferred. This field does not appear in the response if the stored volume is not restoring or bootstrapping.
VolumeDiskId (string) --
The ID of the local disk that was specified in the CreateStorediSCSIVolume operation.
SourceSnapshotId (string) --
If the stored volume was created from a snapshot, this field contains the snapshot ID used, e.g. snap-78e22663. Otherwise, this field is not included.
PreservedExistingData (boolean) --
Indicates if when the stored volume was created, existing data on the underlying local disk was preserved.
Valid Values: true, false
VolumeiSCSIAttributes (dict) --
An VolumeiSCSIAttributes object that represents a collection of iSCSI attributes for one stored volume.
TargetARN (string) --
The Amazon Resource Name (ARN) of the volume target.
NetworkInterfaceId (string) --
The network interface identifier.
NetworkInterfacePort (integer) --
The port used to communicate with iSCSI targets.
LunNumber (integer) --
The logical disk number.
ChapEnabled (boolean) --
Indicates whether mutual CHAP is enabled for the iSCSI target.
CreatedDate (datetime) --
The date the volume was created. Volumes created prior to March 28, 2017 don’t have this time stamp.
VolumeUsedInBytes (integer) --
The size of the data stored on the volume in bytes.
Note
This value is not available for volumes created prior to May 13, 2015, until you store data on the volume.
KMSKey (string) --
The Amazon Resource Name (ARN) of the AWS KMS key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
TargetName (string) --
The name of the iSCSI target that is used by an initiator to connect to a volume and used as a suffix for the target ARN. For example, specifying TargetName as myvolume results in the target ARN of arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/target/iqn.1997-05.com.amazon:myvolume .
{'DomainControllers': ['string'], 'OrganizationalUnit': 'string'}
Adds a file gateway to an Active Directory domain. This operation is only supported for file gateways that support the SMB file protocol.
See also: AWS API Documentation
Request Syntax
client.join_domain(
GatewayARN='string',
DomainName='string',
OrganizationalUnit='string',
DomainControllers=[
'string',
],
UserName='string',
Password='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
string
[REQUIRED]
The name of the domain that you want the gateway to join.
string
The organizational unit (OU) is a container with an Active Directory that can hold users, groups, computers, and other OUs and this parameter specifies the OU that the gateway will join within the AD domain.
list
List of IPv4 addresses, NetBIOS names, or host names of your domain server. If you need to specify the port number include it after the colon (“:”). For example, mydc.mydomain.com:389 .
(string) --
string
[REQUIRED]
Sets the user name of user who has permission to add the gateway to the Active Directory domain.
string
[REQUIRED]
Sets the password of the user who has permission to add the gateway to the Active Directory domain.
dict
Response Syntax
{
'GatewayARN': 'string'
}
Response Structure
(dict) --
JoinDomainOutput
GatewayARN (string) --
The unique Amazon Resource Name (ARN) of the gateway that joined the domain.
{'VolumeInfos': {'VolumeAttachmentStatus': 'string'}}
Lists the iSCSI stored volumes of a gateway. Results are sorted by volume ARN. The response includes only the volume ARNs. If you want additional volume information, use the DescribeStorediSCSIVolumes or the DescribeCachediSCSIVolumes API.
The operation supports pagination. By default, the operation returns a maximum of up to 100 volumes. You can optionally specify the Limit field in the body to limit the number of volumes in the response. If the number of volumes returned in the response is truncated, the response includes a Marker field. You can use this Marker value in your subsequent request to retrieve the next set of volumes. This operation is only supported in the cached volume and stored volume gateway types.
See also: AWS API Documentation
Request Syntax
client.list_volumes(
GatewayARN='string',
Marker='string',
Limit=123
)
string
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
string
A string that indicates the position at which to begin the returned list of volumes. Obtain the marker from the response of a previous List iSCSI Volumes request.
integer
Specifies that the list of volumes returned be limited to the specified number of items.
dict
Response Syntax
{
'GatewayARN': 'string',
'Marker': 'string',
'VolumeInfos': [
{
'VolumeARN': 'string',
'VolumeId': 'string',
'GatewayARN': 'string',
'GatewayId': 'string',
'VolumeType': 'string',
'VolumeSizeInBytes': 123,
'VolumeAttachmentStatus': 'string'
},
]
}
Response Structure
(dict) --
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
Marker (string) --
VolumeInfos (list) --
(dict) --
Describes a storage volume object.
VolumeARN (string) --
The Amazon Resource Name (ARN) for the storage volume. For example, the following is a valid ARN:
arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/volume/vol-1122AABB
Valid Values: 50 to 500 lowercase letters, numbers, periods (.), and hyphens (-).
VolumeId (string) --
The unique identifier assigned to the volume. This ID becomes part of the volume Amazon Resource Name (ARN), which you use as input for other operations.
Valid Values: 50 to 500 lowercase letters, numbers, periods (.), and hyphens (-).
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
GatewayId (string) --
The unique identifier assigned to your gateway during activation. This ID becomes part of the gateway Amazon Resource Name (ARN), which you use as input for other operations.
Valid Values: 50 to 500 lowercase letters, numbers, periods (.), and hyphens (-).
VolumeType (string) --
VolumeSizeInBytes (integer) --
The size of the volume in bytes.
Valid Values: 50 to 500 lowercase letters, numbers, periods (.), and hyphens (-).
VolumeAttachmentStatus (string) --