Provision NAS File Systems Programmatically with CreateFileSystem API - File Storage NAS - Alibaba Cloud - File Storage NAS

Creates a file system.

Operation description

Make sure that you understand the billing methods and pricing of File Storage NAS before you invoke this operation. For more information, see Billing and Pricing.
You must complete real-name verification before you can create a file system instance. For more information, see Real-name verification.
When you invoke this operation, the service-linked role required for the operation is automatically created. For more information, see Manage the service-linked roles of NAS.

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 supports 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

nas:CreateFileSystem

create

*FileSystem

acs:nas:{#regionId}:{#accountId}:filesystem/*

nas:EncryptedType
nas:FileSystemType

None

Request parameters

Parameter	Type	Required	Description	Example
FileSystemType	string	No	The file system type. Valid values: standard (default): General-purpose NAS. extreme: Extreme NAS. cpfs: Cloud Parallel File Storage (locally redundant). cpfsse: Cloud Parallel File Storage SE (zone-redundant). Valid values: standard : General-purpose NAS. cpfs : Cloud Paralleled File System (locally redundant) cpfsse : Cloud Paralleled File System SE (zone-redundant) extreme : Extreme NAS.	standard
ChargeType	string	No	The billing method. Valid values: PayAsYouGo (default): pay-as-you-go. Subscription: subscription. Valid values: PayAsYouGo : Pay-as-you-go. Subscription : Subscription.	PayAsYouGo
Duration	integer	No	The subscription duration. Unit: months. This parameter is required and valid only when ChargeType is set to Subscription. If a subscription instance is not renewed upon instance expiration, the instance expires and is automatically released.	1
Capacity	integer	No	The capacity of the file system. Unit: GiB. This parameter is required and valid only when FileSystemType is set to extreme, cpfs, or cpfsse. For available values, refer to the actual specifications on the purchase page: Extreme NAS pay-as-you-go purchase page Parallel file system CPFS pay-as-you-go purchase page	100
Bandwidth	integer	No	The maximum throughput of the file system. Unit: MB/s. For available specification values, refer to the actual specifications on the purchase page. Parallel file system CPFS pay-as-you-go purchase page	150
StorageType	string	Yes	The storage type. If FileSystemType is set to standard, valid values: Performance, Capacity, Premium, and Agentic (AgenticFS). If FileSystemType is set to extreme, valid values: standard and advance. If FileSystemType is set to cpfs, valid values: advance_100 (100 MB/s/TiB baseline), advance_200 (200 MB/s/TiB baseline), and economic. If FileSystemType is set to cpfsse, valid values: advance_100 (100 MB/s/TiB baseline). Valid values: standard : Standard Extreme NAS. Agentic : AgenticFS Capacity : Capacity NAS. advance_200 : Cloud Paralleled File System 200 MB/s/TiB baseline. advance_100 : Cloud Paralleled File System 100 MB/s/TiB baseline. Premium : Premium NAS. Performance : Performance NAS. economic : Cloud Paralleled File System economy. advance : Advanced Extreme NAS.	Performance
ZoneId	string	No	The zone ID. A zone is an independent physical area within a region that has its own power supply and network. If FileSystemType is set to standard, this parameter is optional. By default, an active zone that meets the conditional requirements is randomly selected based on ProtocolType and StorageType. If FileSystemType is set to extreme or cpfs, this parameter is required. Note File systems and Elastic Compute Service (ECS) instances in different zones within the same region can communicate with each other. The file system and the ECS instance should reside in the same zone to avoid cross-zone latency.	cn-hangzhou-b
ProtocolType	string	Yes	The file transfer protocol type. If FileSystemType is set to standard, valid values: NFS and SMB. If FileSystemType is set to extreme, valid values: NFS. If FileSystemType is set to cpfs, valid values: cpfs. If FileSystemType is set to cpfsse, valid values: cpfs. Valid values: cpfs : cpfs protocol. SMB : SMB protocol. NFS : NFS protocol.	NFS
EncryptType	integer	No	Specifies whether to encrypt the file system. Uses keys managed by Key Management Service (KMS) to encrypt data stored on the file system. Decryption is not required when reading or writing encrypted data. Valid values: 0 (default): Not encrypted. 1: NAS-managed key. Supported when FileSystemType is set to standard or extreme. 2: Custom key encryption. Supported when FileSystemType is set to standard or extreme. Note Extreme NAS: Custom Key (KMS) is supported in all regions except China (Hangzhou) Finance Cloud. General-purpose NAS: Custom Key (KMS) is supported in all regions. Valid values: 0 : Not encrypted. 1 : NAS-managed key. 2 : Custom key encryption.	1
SnapshotId	string	No	The snapshot ID. This parameter is supported only for Extreme NAS file systems with the advanced storage type. Note A file system created from a snapshot has the same version as the source file system of the snapshot. For example, if the source file system version is 1 and you want to create a version 2 file system, first create file system A from the snapshot, then create file system B that meets version 2 configurations, copy data from file system A to file system B, and migrate your workloads to file system B after the copy is complete.	s-extreme-snapsho****
VpcId	string	No	The VPC ID. If FileSystemType is set to cpfs or cpfsse, this parameter is required. If FileSystemType is set to standard or extreme, this parameter is reserved for future use and does not take effect. You do not need to configure it.	vpc-bp18cx9a7zoh0h9b4****
VSwitchId	string	No	The vSwitch ID. If FileSystemType is set to cpfs, this parameter is required. If FileSystemType is not set to cpfs, this parameter is reserved for future use and does not take effect. You do not need to configure it.	vsw-bp131dkqilvw5pnlt****
Description	string	No	The description of the file system. Limits: The description must be 2 to 128 characters in length. The description must start with a letter and cannot start with `http://` or `https://`. The description can contain digits, colons (:), underscores (_), and hyphens (-).	Description of this file system
ClientToken	string	No	Ensures the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests. The value of ClientToken can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence. Note If you do not specify this parameter, the system uses the RequestId of the API request as the ClientToken. The RequestId may vary for each API request.	123e4567-e89b-12d3-a456-42665544****
KmsKeyId	string	No	The KMS key ID. This parameter is required only when EncryptType is set to 2.	fcbd**-62-4a-b605-c58cc1d5**
DryRun	boolean	No	Specifies whether to perform a dry run for this request. A dry run checks parameter validity, verifies inventory, and performs other validations without actually creating the instance or incurring charges. Valid values: true: Sends a dry run request without creating the instance. The check items include required parameters, request format, service limits, and NAS inventory. If the check fails, the corresponding error is returned. If the check passes, HTTP status code 200 is returned, but FileSystemId is empty. false (default): Sends a normal request. After the check passes, the instance is directly created.	true
ResourceGroupId	string	No	The resource group ID. You can view resource group IDs in the Resource Management console.	rg-acfmwavnfdf****
Tag	array<object>	No	The tags. Array length: 1 to 20. If the array contains multiple tag objects, the tag key (Key) must be unique.
	object	No	The tag object.
Key	string	No	The tag key. Limits: The tag key cannot be empty. The tag key can be up to 128 characters in length. The tag key cannot start with `aliyun` or `acs:`. The tag key cannot contain `http://` or `https://`.	nastest
Value	string	No	The tag value. Limits: The tag value cannot be empty. The tag value can be up to 128 characters in length. The tag value cannot contain `http://` or `https://`.	testValue
RedundancyType	string	No	The storage redundancy type. This parameter takes effect only for CPFS SE. Valid values: ZRS. Valid values: ZRS : Zone-redundant.	ZRS
RedundancyVSwitchIds	array	No	The list of zone-redundant vSwitch IDs. When RedundancyType is set to ZRS, this parameter is required. You must specify three vSwitch IDs from three different zones.
	string	No	The zone-redundant vSwitch ID list.	vsw-123xxx

Notes on API idempotence:
Because the CreateFileSystem operation involves cloud resource creation and billing, if a request times out or an internal server error occurs, the client may retry the request. We recommend that you specify the ClientToken parameter to prevent duplicate orders caused by multiple retries.

Note

Currently, this operation supports idempotence only when FileSystemType is set to extreme or cpfs. When FileSystemType is set to standard, this operation does not support idempotence.

Details about the ClientToken parameter:

ClientToken is a unique, case-sensitive string generated by the client that contains no more than 64 ASCII characters. Example: ClientToken=123e4567-e89b-12d3-a456-42665544****
If you provide a ClientToken that has been used before but with different request parameters, NAS returns the IdempotentParameterMismatch error code.

Note

The SignatureNonce, Timestamp, and Signature parameters must change upon retry. This is because NAS uses SignatureNonce to prevent replay attacks and Timestamp to mark the time of each request. Therefore, a new request must provide different SignatureNonce and Timestamp values, which also causes the Signature value to change.

After you add the ClientToken parameter:
- If the response is HTTP 200, the retry returns the same result as the previous request without affecting your server state.
- If the response is HTTP 4xx and the error message does not indicate a "try it later" type of message, the retry will never succeed. Troubleshoot the issue based on the error message and modify the request parameters before retrying.
- If the response is HTTP 5xx, the request may have timed out or an internal server error may have occurred. You can resend the same request (which must contain the same ClientToken and business request parameters) to confirm the result.
The ClientToken is valid for 30 days.

Response elements

Element	Type	Description	Example
	object	The response structure.
RequestId	string	The request ID.	98696EF0-1607-4E9D-B01D-F20930B6****
FileSystemId	string	The ID of the created file system.	1ca404****

Examples

Success response

JSON format

{
  "RequestId": "98696EF0-1607-4E9D-B01D-F20930B6****",
  "FileSystemId": "1ca404****"
}

Error codes

HTTP status code	Error code	Error message	Description
202	RequestAccepted	The request has been accepted by the server.	The request has been accepted by the server.
400	IdempotentParameterMismatch	The same client token was passed in to different parameters.	The same client token was passed in to different parameters.
400	InvalidParameter.KmsServiceNotEnabled	Key Management Service is not enabled.	Key Management Service is not enabled.
400	DryRunOperation	The request is validated with DryRun flag set.	The request is validated with DryRun flag set.
400	SubAccount.NoExtremeSLRPermission	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasExtreme. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasExtreme. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.
400	SubAccount.NoStandardSLRPermission	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasStandard. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasStandard. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.
400	SubAccount.NoEncryptionSLRPermission	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasEncryption. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.	The RAM user does not have the permission to create service linked role AliyunServiceRoleForNasEncryption. Please authorize the RAM user the permission ram:CreateServiceLinkedRole.
400	InvalidParam.NotSupportBYOK	The specified file system type does not support the BYOK encryption function.	The specified file system type does not support the BYOK encryption function.
400	MissingParameter.KmsKeyId	When parameter EncryptType equals 2, the parameter KmsKeyId is mandatory for your request.	When parameter EncryptType equals 2, the parameter KmsKeyId is mandatory for your request.
400	InvalidParameter.InvalidKmsKeyId	The specified KMS key ID is invalid.	The specified KMS key ID is invalid.
400	InvalidParameter.KmsKeyIdNotFound	The specified KMS key ID does not exist.	The specified KMS key ID does not exist.
403	OperationDenied.InvalidState	The operation is not permitted when the status is processing.	The operation is not permitted when the status is processing.
403	InvalidFileSystem.AlreadyExisted	The specified file system already exists.	The specified file system already exists.
403	Resource.OutOfStock	The inventory of the specified zone is insufficient.	The inventory of the specified zone is insufficient.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.