CreateGatewayBlockVolume - Cloud Storage Gateway - Alibaba Cloud Documentation Center

Creates a block volume (iSCSI) for an iSCSI gateway.

Operation description

Before you call this operation, make sure that the following requirements are met:

You have created and deployed an iSCSI gateway. If the cache mode is used, the gateway must have an unused cache disk. If the write-through mode is used, no cache disk is required.
You have an Object Storage Service (OSS) bucket.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that support authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

hcs-sgw:CreateGatewayBlockVolume

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
GatewayId	string	Yes	The ID of the gateway.	gw-000dt67z4ijngqvh1***
Name	string	Yes	The name of the block volume. The name must be 1 to 32 characters in length, start with a lowercase letter, and can contain lowercase letters and digits.	name
Recovery	boolean	No	Specifies whether to enable recovery for the block volume. If you enable recovery and the specified OSS bucket was previously used as the cloud storage of a block volume, the gateway attempts to recover the block volume using the metadata dataset in the bucket. The default value is false. This value indicates that a new block volume is created using the OSS bucket.	false
VolumeProtocol	string	Yes	The protocol of the block volume. The only valid value is iSCSI.	iSCSI
Size	integer	No	The size of the block volume. Unit: GB. Valid values: 1 to 262144. Default value: 100. Note This parameter is invalid when recovery is enabled.	100
ChunkSize	integer	No	The storage allocation unit of the block volume. This parameter specifies the minimum allocation unit of the block volume. To achieve optimal storage efficiency, we recommend that you set this parameter to the same value as the storage allocation unit of the application. Unit: bytes. Valid values: 8192. 16384. 32768. 65536. 131072. Default value: 32768. Note This parameter is invalid when recovery is enabled.	32768
CacheMode	string	No	The cache mode of the block volume. Default value: Cache. Valid values: Cache: cache mode. WriteThrough: write-through mode. Note You must specify this parameter. In cache mode, read and write operations preferentially access the local cache of the gateway. In write-through mode, read and write operations directly access the OSS bucket in the cloud. In most cases, the cache mode provides better read and write performance.	Cache
ChapEnabled	boolean	No	Specifies whether to enable Challenge-Handshake Authentication Protocol (CHAP) for iSCSI access. Inbound CHAP is supported. Default value: false.	false
ChapInUser	string	No	The username for inbound CHAP when CHAP is enabled for the block volume. The username must be 1 to 32 characters in length and can contain letters and digits. Note This parameter is invalid when CHAP is disabled.	chapInUser
ChapInPassword	string	No	The password for inbound CHAP when CHAP is enabled for the block volume. The password must be 12 to 16 characters in length and can contain letters, digits, or the following special characters: !, @, #, $, %, ^, &, and . Note* This parameter is invalid when CHAP is disabled.	chapInPassword
OssBucketName	string	Yes	The name of the Object Storage Service (OSS) bucket that corresponds to the block volume. Note Block volumes do not support OSS buckets for which the back-to-origin feature is enabled.	bucketName
OssEndpoint	string	Yes	The endpoint of the region where the OSS bucket that corresponds to the block volume is located. Note Differentiate between internal and public endpoints. If the OSS bucket and the gateway are in the same region, we recommend that you use an internal endpoint, such as oss-cn-shanghai-internal.aliyuncs.com.	oss-cn-shanghai-internal.aliyuncs.com
OssBucketSsl	boolean	No	Specifies whether to enable SSL to access the OSS bucket. Default value: true.	true
LocalFilePath	string	No	The internal device name of the cache disk used by the block volume. You can call the DescribeGatewayCaches operation to obtain the name. Note If CacheMode is set to Cache, you must specify LocalFilePath. If CacheMode is set to WriteThrough, this parameter is invalid.	/dev/vdb
OssBucketRegionId	string	No	The region where the OSS bucket that corresponds to the block volume is located.

Response parameters

Parameter	Type	Description	Example
	object
TaskId	string	The ID of the task.	t-000c6hshwukkbtxrb***
Message	string	The returned message.	successful
RequestId	string	The ID of the request.	9083F167-95B1-4B40-B2CD-70DE068EC3**
Code	string	The status code. A status code of 200 indicates that the request is successful.	200
Success	boolean	Indicates whether the request is successful.	true

Examples

Success response

JSON format

{
  "TaskId": "t-000c6hshwukkbtxrb***",
  "Message": "successful",
  "RequestId": "9083F167-95B1-4B40-B2CD-70DE068EC3**",
  "Code": "200",
  "Success": true
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter.BlockVolume.%s	The specified field %s for block volume is invalid. Please check it again.	The specified block volume parameter is invalid. You must specify a valid parameter.
400	VersionNotSupported.BlockVolume.%s	The specified field %s for block volume is not supported by current gateway version. Please check it again.	The specified block volume parameter for the gateway is not compatible with the gateway version. You must specify a valid parameter.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.