Call the CreateFileSystem API to create a file system - Cloud Parallel File Storage - Alibaba Cloud - Cloud Parallel File Storage

Creates a file system.

Operation description

Before you call this operation, make sure that you fully understand the billing rules and pricing of File Storage NAS. For more information, see Billing overview and Pricing.
To create a file system, you must pass real-name verification. For more information, see Real-name verification for accounts.
When you invoke this operation, the system performs automatic creation of the service-linked role to associate with NAS. For more information, see Manage the service-linked role for 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 type of the file system. Valid values: standard: General-purpose NAS. This is the default value. extreme: Extreme NAS. cpfs: Cloud Parallel File Storage (locally redundant edition). cpfsse: Cloud Parallel File Storage SE (zone-redundant edition). Valid values: standard : General-purpose NAS. cpfs : Cloud Paralleled File System (locally redundant edition) cpfsse : Cloud Paralleled File System SE (zone-redundant edition) extreme : Extreme NAS.	standard
ChargeType	string	No	The billing method. Valid values: PayAsYouGo: pay-as-you-go. This is the default value. 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 takes effect only when ChargeType is set to Subscription. If no renewal is performed when the subscription instance expires, the instance expires and is subject to automatic release.	1
Capacity	integer	No	The capacity of the file system. Unit: GiB. This parameter is required and takes effect only when FileSystemType is set to extreme, cpfs, or cpfsse. For valid values, refer to the actual specifications on the buy page: Buy page for Extreme NAS (pay-as-you-go) Buy page for parallel file system CPFS (pay-as-you-go)	100
Bandwidth	integer	No	The maximum throughput of the file system. Unit: MB/s. For valid values, refer to the actual specifications on the buy page. Buy page for parallel file system CPFS (pay-as-you-go)	150
StorageType	string	Yes	The storage type. When FileSystemType is set to standard, valid values are Performance, Capacity, Premium, and Agentic (AgenticFS). When FileSystemType is set to extreme, valid values are standard (Standard) and advance (Advanced). When FileSystemType is set to cpfs, valid values are advance_100 (100 MB/s/TiB baseline), advance_200 (200 MB/s/TiB baseline), and economic (Economy). When FileSystemType is set to cpfsse, the valid value is advance_100 (100 MB/s/TiB baseline). Valid values: Agentic : Agentic. Capacity : Capacity. Premium : Premium. Performance : Performance. economic : Economy. advance : Advanced.	Performance
ZoneId	string	No	The zone ID. A zone is a physical area with independent power grids and networks in a region. When FileSystemType is set to standard, this parameter is optional. By default, a conditional active zone is randomly selected based on the ProtocolType and StorageType settings. When FileSystemType is set to extreme or cpfs, this parameter is required. Note File systems and Elastic Computing Service servers in different active zones of the same region can communicate with each other. Deploy the file system and the Elastic Computing Service in the same active zone to avoid cross-zone latency.	cn-hangzhou-b
ProtocolType	string	Yes	The File Transfer Protocol type. When FileSystemType is set to standard, valid values are NFS and SMB. When FileSystemType is set to extreme, the valid value is NFS. When FileSystemType is set to cpfs, the valid value is cpfs. When FileSystemType is set to cpfsse, the valid value is cpfs. Valid values: dual : NFS and SMB. SMB : SMB. NFS : NFS.	NFS
EncryptType	integer	No	Specifies whether to encrypt the file system. Uses KMS-managed keys to encrypt data at rest on the file system. When reading and writing encrypted data, no decryption is required. Valid values: 0: not encrypted. This is the default value. 1: NAS-managed key. This value is supported when FileSystemType is set to standard or extreme. 2: custom key. This value is supported when FileSystemType is set to standard or extreme. Note Extreme NAS: The Custom Key (KMS) feature is supported in all regions except China East 1 Finance Cloud. General-purpose NAS: The Custom Key (KMS) feature is supported in all regions. Valid values: 0 : Not encrypted. 1 : NAS-managed key encryption. 2 : Custom key encryption.	1
SnapshotId	string	No	The snapshot ID. This parameter is supported only for Extreme NAS file systems of the Advanced storage type. Note If you create a file system from a snapshot, the created file system has the same version as the source file system of the snapshot. For example, if the source file system of the snapshot is of version 1 and you want to create a file system of version 2, you can first create File System A from the snapshot, then create File System B that meets the version 2 configurations, copy the data from File System A to File System B, and then migrate your business to File System B.	s-extreme-snapsho****
VpcId	string	No	The VPC ID. This parameter is required when FileSystemType is set to cpfs or cpfsse. This parameter is reserved and does not take effect when FileSystemType is set to standard or extreme. You do not need to configure this parameter.	vpc-bp18cx9a7zoh0h9b4****
VSwitchId	string	No	The vSwitch ID. This parameter is required when FileSystemType is set to cpfs. This parameter is reserved and does not take effect when FileSystemType is not set to cpfs. You do not need to configure this parameter.	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 (-).	The description of the file system
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that the value is unique among different requests. The client token 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 automatically uses the RequestId of the API request as the ClientToken. The RequestId of each API request may be different.	123e4567-e89b-12d3-a456-42665544****
KmsKeyId	string	No	The ID of the KMS key. 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 on the creation request. A dry run helps you check parameter validity and inventory, without actually creating the instance or incurring fees. Valid values: true: performs a dry run without creating the instance. The system checks whether required parameters are specified, the request format, business limits, and NAS inventory. If the request fails the dry run, an error is returned. If the request passes the dry run, the HTTP status code 200 is returned, but FileSystemId is empty. false: performs a normal request. If the request passes the dry run, the instance is created. This is the default value.	true
ResourceGroupId	string	No	The resource group ID. You can view the resource group ID 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 keys must be unique.
	object	No	The tag object.
Key	string	No	The tag key. Limits: The tag key cannot be empty or an empty string. 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 or an empty string. 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 Cloud Parallel File Storage SE. Valid value: ZRS. Valid values: ZRS : Zone-redundant. LRS : Locally redundant storage.	ZRS
RedundancyVSwitchIds	array	No	The zone-redundant vSwitch IDs. This parameter is required when RedundancyType is set to ZRS. You must specify three vSwitch IDs, and the vSwitches must reside in three different zones.
	string	No	The zone-redundant vSwitch ID.	vsw-123xxx

Note the following items about API idempotence:
Because the CreateFileSystem operation involves the creation of cloud resources and incurs fees, the client may retry the request if a request timeout or internal server error occurs. Specify the ClientToken parameter in the request to prevent duplicate orders caused by multiple retries.

Note

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

Details of the ClientToken parameter are as follows:

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

Note

The SignatureNonce, Timestamp, and Signature parameters must be changed during a retry. This is because NAS uses SignatureNonce to prevent replay attacks and Timestamp to record the time of each request. Therefore, you must provide different values for the SignatureNonce and Timestamp parameters in a retry, which also results in a change to the Signature value.

After the ClientToken parameter is added:
- If HTTP status code 200 is returned, the client can obtain the same result as the previous request after a retry, and the server status is not affected.
- If an HTTP status code 4xx is returned and the error message does not contain information similar to "try it later", the retry will never succeed. You must troubleshoot the issue based on the error message, modify the request parameters, and then retry the request.
- If an HTTP status code 5xx is returned, it indicates that a network timeout 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 request result.
A ClientToken is valid for 30 days.

Response elements

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

Examples

Success response

JSON format

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

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.