Call the CreateVSwitch API to create a vSwitch - Virtual Private Cloud - Alibaba Cloud - Virtual Private Cloud

Creates a vSwitch.

Operation description

When you call this operation to create a vSwitch, take note of the following items:

The number of vSwitches in each VPC cannot exceed 150.
The first IP address and the last three IP addresses of each vSwitch CIDR block are reserved by the system. For example, the system reserved IP addresses of 192.168.1.0/24 are 192.168.1.0, 192.168.1.253, 192.168.1.254, and 192.168.1.255.
The number of cloud service instances in a vSwitch cannot exceed the remaining available cloud service instances in the VPC (15,000 minus the current number of cloud service instances).
A cloud service instance can belong to only one vSwitch.
vSwitches do not support multicast or broadcast.
After a vSwitch is created, you cannot modify its CIDR block.
The CreateVSwitch operation is asynchronous. After you send a request, the system returns an instance ID but the vSwitch is not yet created. The background task is still in progress. You can call DescribeVSwitchAttributes to query the creation status of the vSwitch:
- When the vSwitch is in the Pending state, the vSwitch is being configured.
- When the vSwitch is in the Available state, the vSwitch is available.
The CreateVSwitch operation does not support concurrent creation of vSwitches in the same VPC.
When you call the CreateVSwitch operation, the CIDR block of the vSwitch cannot be within the following reserved address ranges: 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, or 224.0.0.0/4.

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

vpc:CreateVSwitch

create

*VPC

acs:vpc:{#regionId}:{#accountId}:vpc/{#VpcId}

*VSwitch

acs:vpc:{#regionId}:{#accountId}:vswitch/*

vpc:tag

None

Request parameters

Parameter	Type	Required	Description	Example
Tag	array<object>	No	The tags of the resource.
	object	No	The tag.
Key	string	No	The tag key of the resource. You can specify up to 20 tag keys. The tag key cannot be an empty string. A tag key can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceJoshua
Value	string	No	The tag value of the resource. You can specify up to 20 tag values. The tag value can be an empty string. The tag value can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceDept
ZoneId	string	Yes	The ID of the zone in which to create the vSwitch. You can call the DescribeZones operation to query the zone ID.	cn-hangzhou-b
RegionId	string	No	The region ID of the vSwitch that you want to create. You can call the DescribeRegions operation to query the region ID.	cn-hangzhou
CidrBlock	string	Yes	The CIDR block of the vSwitch. The following requirements apply: The mask length of the vSwitch CIDR block must be 16 to 29 bits. The CIDR block of the vSwitch must be a subset of the CIDR block of the VPC to which the vSwitch belongs. The CIDR block of the vSwitch cannot be the same as the destination CIDR block of a route in the VPC, but can be a subset of the destination CIDR block. The CIDR block of the vSwitch cannot be within the following reserved address ranges: 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, or 224.0.0.0/4. Note After a vSwitch is created, you cannot modify its CIDR block.	172.16.0.0/24
Ipv6CidrBlock	integer	No	The last 8 bits of the IPv6 CIDR block of the vSwitch. Valid values: 0 to 255. You can specify this parameter only when the VPC to which the vSwitch belongs has IPv6 enabled. This allows you to assign an IPv6 CIDR block to the vSwitch. After the IPv6 CIDR block is allocated, it cannot be changed. Make sure that the CIDR block does not overlap with those of other vSwitches in the VPC.	12
VpcId	string	Yes	The ID of the VPC to which the vSwitch belongs.	vpc-257gqcdfvx6n****
VSwitchName	string	No	The name of the vSwitch. The name must be 1 to 128 characters in length and cannot start with `http://` or `https://`.	vSwitch-1
Description	string	No	The description of the vSwitch. The description must be 1 to 256 characters in length and cannot start with `http://` or `https://`.	vSwitch
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters. Note If you do not specify this parameter, the system uses the RequestId of the API request as the ClientToken. The RequestId may differ for each API request.	0c593ea1-3bea-11e9-b96b-88e9fe63****
VpcIpv6CidrBlock	string	No	The IPv6 CIDR block of the VPC. If the VPC to which the vSwitch belongs has multiple IPv6 CIDR blocks, you can specify this parameter to determine the IPv6 CIDR block range for the vSwitch. If you do not specify this parameter, the IPv6 CIDR block assigned when IPv6 was enabled for the VPC is used.	2408:XXXX:0:6a::/56

Response elements

Element	Type	Description	Example
	object	The response parameters.
VSwitchId	string	The ID of the created vSwitch.	vsw-25navfgbue4g****
RequestId	string	The request ID.	0ED8D006-F706-4D23-88ED-E11ED28DCAC0

Examples

Success response

JSON format

{
  "VSwitchId": "vsw-25navfgbue4g****",
  "RequestId": "0ED8D006-F706-4D23-88ED-E11ED28DCAC0"
}

Error codes

HTTP status code	Error code	Error message	Description
400	OperationFailed.ResourceConflict	vpc only support one cloud box.
400	OperationFailed.IdempotentTokenProcessing	Action is processing.
400	InvalidDescription.Malformed	Invalid description.
400	InvalidVSwitchName.Malformed	Specified virtual switch name is not valid.	The format of the specified vSwitch name is invalid. Specify the name in the valid format.
400	InvalidVSwitchDiscription.Malformed	Specified virtual switch description is not valid.
400	Abs.Vpc.InvalidDescription.Malformed	Specified virtual switch name is not valid.
400	MissingParam.vpcId	The parameter vpcId is mandatory.	The vpcId parameter is required.
400	ResourceNotAvailable	Resource you requested is not available in this region or zone.
400	InvalidParameter	Specified CIDR block is not valid in VPC.
400	InvalidCidrBlock.Overlapped	Specified CIDR block overlapped with other subnets.
400	QuotaExceeded.VSwitch	Virtual switch quota exceeded.	The number of vSwitches has reached the upper limit. Reduce the number of vSwitches and try again later.
400	IncorrectRouteEntryStatus	Some route entry status blocked this operation.
400	IncorrectVSwitchStatus	Some virtual switch is modifying within the same VPC.	Multiple vSwitches are in the Modifying state in the same VPC. Try again later.
400	InvalidCirdrBlock.MaskLength	Specified CIDR block is not valid .	Invalid CIDR block.
400	IncorrectVpcStatus	Current VPC status does not support this operation.
400	CreateVSwitch.IncorrectStatus.cbnStatus	Current CBN status does not support this operation.	You cannot create a vSwitch when the CEN instance is in the current state.
400	InvalidCidrBlock.Malformed	Specified CIDR block is not valid.
400	MissingParameter	Miss mandatory parameter.
400	TaskConflict	The operation is too frequent, TaskConflict.	The system is unavailable. Try again later.
400	VPC.SWITCH.RULE.QUOTA.NOT.EXISTS	vSwitch quota rule not exists.
400	Forbidden.VpcNotFound	Specified VPC can not found.	The specified VPC does not exist.
400	RouteConflict.AlreadyExist	Route conflict exists in routing table.	Route conflicts exist in the route table.
400	OperationFailed.CidrAcross	Classic link instance cidr must not across.
400	Duplicated.ClientToken	%s
400	OperationFailed.Ipv6CidrBlockExisted	%s
400	IllegalParam.Ipv6CidrBlock	%s
400	OperationFailed.VpcIpv6Disabled	%s
400	IncorrectStatus.cbnStatus	Current CBN status does not support this operation.	The status of the CEN instance is invalid.
400	OperationFailed.NotifyCenCreate	Failed to notify cen when create vswitch.
400	OperationFailed.DistibuteLock	Distibute lock fail.	The operation is locked by another request;
400	UnsupportedFeature.CloudBoxIpv6	The IPv6 feature is not supported by cloud box.	You cannot create an IPv6 address for a CloudBox instance.
400	OperationDenied.VpcPeerExist	The operation is not allowed because the VPC peer exists.	The operation failed because VPC peering connections exist.
400	OperationDenied.CenAttached	The operation is not allowed because the VPC is attached to CEN.	The operation is not allowed because the VPC is attached to a CEN instance.
400	OperationDenied.NatgwExist	The operation is not allowed because the NAT gateway exists in VPC.	The operation is not allowed because NAT gateways exist in the VPC.
400	MissingParam.Ipv6CidrBlock	The parameter Ipv6CidrBlock is mandatory.	The Ipv6CidrBlock parameter is required.
400	IllegalParam.VpcIpv6CidrBlock	%s
400	OperationDenied.OtherSubnetCreating	The operation is not allowed because the other VSwitch is creating.
400	OperationDenied.VpcPeerExists	The operation is not allowed because the VpcPeer exists.	The VPC has a VPC peering connection.
400	IllegalParam.CidrBlock	The param of CidrBlock [%s] is illegal.	The CidrBlock parameter is set to an invalid value.
400	InvalidStatus.RouteEntry	RouteEntry status error.
400	InvalidZoneId.NotFound	Specified zone does not exist.
400	OperationDenied.ZoneIsDisabled	The specified zone is disabled. You cannot create a vSwitch in a disabled zone.	The specified zone is disabled. You cannot create a vSwitch in a disabled zone.
404	Invalid.NotExist	witch mask rule not exists.
404	InvalidVpcId.NotFound	Specified VPC does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.