All Products
Search
Document Center

VPN Gateway:CreateVpnAttachment

Last Updated:Aug 07, 2026

Creates an IPsec-VPN connection to be associated with a transit router instance by calling the CreateVpnAttachment operation.

Operation description

Important

Before you begin.

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:CreateVpnAttachment

create

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

RegionId

string

Yes

The region ID of the IPsec-VPN connection.

You can call the DescribeRegions operation to query region IDs.

cn-hangzhou

Name

string

No

The name of the IPsec-VPN connection.

nametest

CustomerGatewayId

string

No

The customer gateway ID.

cgw-p0w2jemrcj5u61un8****

NetworkType

string

No

The network type of the IPsec-VPN connection. Valid values:

  • public (default): public network. The IPsec-VPN connection establishes an encrypted communication channel over the Internet.

  • private: private network. The IPsec-VPN connection establishes an encrypted communication channel over a private network.

public

LocalSubnet

string

Yes

The CIDR block on the VPC side that needs to communicate with the on-premises data center. This is used for Phase 2 negotiation.

Separate multiple CIDR blocks with commas (,). Example: 192.168.1.0/24,192.168.2.0/24.

Description of IPsec-VPN connection routing modes:

  • If both LocalSubnet and RemoteSubnet are set to 0.0.0.0/0, the destination routing mode is used.

  • If both LocalSubnet and RemoteSubnet are set to specific CIDR blocks, the protected data flow mode is used.

10.1.1.0/24,10.1.2.0/24

RemoteSubnet

string

Yes

The CIDR block of the on-premises data center that needs to communicate with the VPC. This is used for Phase 2 negotiation.

Separate multiple CIDR blocks with commas (,). Example: 192.168.3.0/24,192.168.4.0/24.

Description of the routing mode for the IPsec-VPN connection:

  • If both LocalSubnet and RemoteSubnet are set to 0.0.0.0/0, the destination routing mode is used.

  • If both LocalSubnet and RemoteSubnet are set to specific CIDR blocks, the protected data flow mode is used.

10.1.3.0/24,10.1.4.0/24

EffectImmediately

boolean

No

Specifies whether the IPsec-VPN connection configuration takes effect immediately. Valid values:

  • true: The system immediately initiates IPsec protocol negotiation after the configuration is complete.

  • false (default): The system initiates IPsec protocol negotiation only when inbound traffic is detected.

false

IkeConfig

string

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

Phase 1 negotiation configuration:

  • IkeConfig.Psk: The pre-shared key, which is used for identity authentication between the VPN gateway and the on-premises data center.

    • The key must be 1 to 100 characters in length and can contain digits, uppercase letters, lowercase letters, and the following characters. It cannot contain spaces. ~!`@#$%^&*()_-+={}[]|;:',.<>/?

    • If you do not specify a pre-shared key, the system randomly generates a string as the pre-shared key. You can call the DescribeVpnConnection operation to query the pre-shared key automatically generated by the system.

    Note

    The pre-shared key on the IPsec-VPN connection side must be the same as the authentication key on the on-premises data center side. Otherwise, a connection cannot be established between the on-premises data center and the VPN gateway.

  • IkeConfig.IkeVersion: The version of the IKE protocol. Valid values: ikev1 or ikev2. Default value: ikev1.

  • IkeConfig.IkeMode: The negotiation mode. Valid values: main or aggressive. Default value: main.

  • IkeConfig.IkeEncAlg: The encryption algorithm used in Phase 1 negotiation. Valid values: aes, aes192, aes256, des, or 3des. Default value: aes.

  • IkeConfig.IkeAuthAlg: The authentication algorithm used in Phase 1 negotiation. Valid values: md5, sha1, sha256, sha384, or sha512. Default value: md5.

  • IkeConfig.IkePfs: The Diffie-Hellman key exchange algorithm used in Phase 1 negotiation. Valid values: group1, group2, group5, or group14. Default value: group2.

  • IkeConfig.IkeLifetime: The lifetime of the SA generated in Phase 1 negotiation. Unit: seconds. Valid values: 0 to 86400. Default value: 86400.

  • IkeConfig.LocalId: The identifier on the Alibaba Cloud side of the IPsec-VPN connection. The identifier can be up to 100 characters in length and cannot contain spaces. Default value: empty.

  • IkeConfig.RemoteId: The identifier on the on-premises data center side of the IPsec-VPN connection. The identifier can be up to 100 characters in length and cannot contain spaces. Default value: the IP address of the customer gateway.

{"Psk":"1234****","IkeVersion":"ikev1","IkeMode":"main","IkeEncAlg":"aes","IkeAuthAlg":"sha1","IkePfs":"group2","IkeLifetime":86400,"LocalId":"47.XX.XX.1","RemoteId":"47.XX.XX.2"}

IpsecConfig

string

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

The configuration of Phase 2 negotiation:

  • IpsecConfig.IpsecEncAlg: The encryption algorithm for Phase 2 negotiation. Valid values: aes, aes192, aes256, des, or 3des. Default value: aes.

  • IpsecConfig.IpsecAuthAlg: The authentication algorithm for Phase 2 negotiation. Valid values: md5, sha1, sha256, sha384, sha512. Default value: md5.

  • IpsecConfig.IpsecPfs: The Diffie-Hellman key exchange algorithm used in Phase 2 negotiation. Valid values: disabled, group1, group2, group5, or group14. Default value: group2.

  • IpsecConfig.IpsecLifetime: The lifetime of the SA negotiated in Phase 2. Unit: seconds. Valid values: 0 to 86400. Default value: 86400.

{"IpsecEncAlg":"aes","IpsecAuthAlg":"sha1","IpsecPfs":"group2","IpsecLifetime":86400}

BgpConfig

string

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

BGP configuration:

  • BgpConfig.EnableBgp: specifies whether to enable BGP. Valid values: true or false (default).

  • BgpConfig.LocalAsn: the autonomous system number (ASN) on the Alibaba Cloud side. Valid values: 1 to 4294967295. Default value: 45104.

    You can enter the ASN in the two-segment format: the first 16 bits.the last 16 bits. Each segment is entered in decimal notation.

    For example, if you enter 123.456, the ASN is 123×65536+456=8061384.

  • BgpConfig.TunnelCidr: the CIDR block of the IPsec tunnel. The CIDR block must be a /30 subnet within 169.254.0.0/16 and cannot be 169.254.0.0/30, 169.254.1.0/30, 169.254.2.0/30, 169.254.3.0/30, 169.254.4.0/30, 169.254.5.0/30, 169.254.6.0/30, or 169.254.169.252/30.

  • LocalBgpIp: the BGP IP address on the Alibaba Cloud side. This address must be an IP address within the IPsec tunnel CIDR block.

Note
  • Before you configure BGP, we recommend that you familiarize yourself with how BGP dynamic routing works and its limits. For more information, see Configure BGP dynamic routing.

  • Use a private ASN to establish a BGP connection with Alibaba Cloud. Refer to the relevant documentation for the private ASN range.

{"EnableBgp":"true","LocalAsn":"45104","TunnelCidr":"169.254.11.0/30","LocalBgpIp":"169.254.11.1"}

HealthCheckConfig

string

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

{"enable":"true","dip":"192.168.1.1","sip":"10.1.1.1","interval":"3","retry":"3","Policy": "revoke_route"}

AutoConfigRoute

boolean

No

Specifies whether to automatically configure routes. Valid values:

  • true (default): Automatically configures routes.

  • false: Does not automatically configure routes.

true

EnableDpd

boolean

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

Specifies whether to enable the Dead Peer Detection (DPD) feature. Valid values:

  • true (default): Enables the DPD feature. The IPsec initiator sends DPD packets to check whether the peer device is alive. If no correct response is received within the specified period of time, the peer is considered disconnected. The ISAKMP SA and the corresponding IPsec SA are deleted, and the security tunnel is also deleted.

  • false: Disables the DPD feature. The IPsec initiator does not send DPD probe packets.

true

EnableNatTraversal

boolean

No

This parameter is supported when you create an IPsec-VPN connection in single-tunnel mode.

Specifies whether to enable NAT traversal. Valid values:

  • true (default): Enables NAT traversal. After NAT traversal is enabled, the IKE negotiation process skips UDP port number verification and can discover NAT gateway devices in the VPN tunnel.

  • false: Disables NAT traversal.

true

RemoteCaCert

string

No

The CA certificate of the peer.

-----BEGIN CERTIFICATE----- MIIB7zCCAZW**** -----END CERTIFICATE-----

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 token can contain only ASCII characters.

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 is different.

123e4567-e89b-12d3-a456-4266****

Tags

array<object>

No

The list of tags to add to the IPsec-VPN connection.

object

No

The tag information.

Key

string

No

The tag key. This value cannot be an empty string.

The tag key can be up to 64 characters in length. It cannot start with aliyun or acs:, and cannot contain http:// or https://.

You can specify up to 20 tag keys at a time.

TagKey

Value

string

No

The tag value.

TagValue

ResourceGroupId

string

No

The ID of the resource group to which the IPsec-VPN connection belongs.

rg-acfmzs372yg****

TunnelOptionsSpecification

array<object>

No

Configures tunnels.

  • When you create a dual-tunnel IPsec-VPN connection, you can configure the parameters in the TunnelOptionsSpecification array.

  • When you create a dual-tunnel IPsec-VPN connection, you must add two tunnels to the IPsec-VPN connection to ensure link redundancy. Only two tunnels can be added to an IPsec-VPN connection.

array<object>

No

The tunnel configuration information.

CustomerGatewayId

string

No

The ID of the customer gateway associated with the tunnel.

cgw-p0w2jemrcj5u61un8****

EnableDpd

boolean

No

Specifies whether to enable the Dead Peer Detection (DPD) feature for the tunnel. Valid values:

true

EnableNatTraversal

boolean

No

Specifies whether to enable NAT traversal for the tunnel. Valid values:

  • true (default): Enables NAT traversal. After NAT traversal is enabled, the IKE negotiation process skips UDP port number verification and can discover NAT gateway devices in the tunnel.

  • false: Disables NAT traversal.

true

TunnelIndex

integer

No

The creation order of the tunnel.

1

TunnelBgpConfig

object

No

The BGP configuration for the tunnel.

LocalAsn

integer

No

The autonomous system number (ASN) on the Alibaba Cloud side of the tunnel. Valid values: 1 to 4294967295. Default value: 45104.

65530

LocalBgpIp

string

No

The BGP address on the Alibaba Cloud side of the tunnel. This address is an IP address within the BGP CIDR block.

169.254.10.1

TunnelCidr

string

No

The BGP CIDR block of the tunnel. The CIDR block must fall within 169.254.0.0/16 and have a mask length of 30. The CIDR block cannot be 169.254.0.0/30, 169.254.1.0/30, 169.254.2.0/30, 169.254.3.0/30, 169.254.4.0/30, 169.254.5.0/30, 169.254.6.0/30, or 169.254.169.252/30.

169.254.10.0/30

TunnelIkeConfig

object

No

The Phase 1 negotiation configuration.

IkeAuthAlg

string

No

The authentication algorithm for Phase 1 negotiation. Valid values: md5, sha1, sha256, sha384, and sha512. Default value: sha1.

sha1

IkeEncAlg

string

No

The encryption algorithm for Phase 1 negotiation. Valid values: aes, aes192, aes256, des, or 3des. Default value: aes.

aes

IkeLifetime

integer

No

The lifetime of the security association (SA) negotiated during Phase 1. Unit: seconds.

Valid values: 0 to 86400. Default value: 86400.

86400

IkeMode

string

No

The negotiation mode of the IKE version. Valid values: main or aggressive. Default value: main.

  • main: Main mode. The negotiation process is highly secure.

  • aggressive: Aggressive mode. Negotiation is fast and has a high success rate.

main

IkePfs

string

No

The Diffie-Hellman key exchange algorithm used in the first-phase negotiation. Default value: group2.

Valid values: group1, group2, group5, group14.

group2

IkeVersion

string

No

The version of the IKE protocol. Valid values: ikev1 or ikev2. Default value: ikev2.

Compared with IKEv1, IKEv2 simplifies the SA negotiation process and provides better support for multi-CIDR-block scenarios.

ikev2

LocalId

string

No

The identifier on the Alibaba Cloud side of the tunnel, used for Phase 1 negotiation. The value can be up to 100 characters in length and cannot contain spaces. The default value is the IP address of the tunnel.

47.XX.XX.1

Psk

string

No

The pre-shared key, which is used for identity authentication between the tunnel and the tunnel peer.

  • The key must be 1 to 100 characters in length and can contain digits, uppercase letters, lowercase letters, and the following characters: ~!\`@#$%^&*()_-+={}[]|;:',.<>/? It cannot contain spaces.

  • If you do not specify a pre-shared key, the system randomly generates a 16-character string as the pre-shared key. You can call the DescribeVpnAttachments operation to query the pre-shared key automatically generated by the system.

Note

The pre-shared keys of the tunnel and the tunnel peer must be the same. Otherwise, the tunnel cannot be established.

123456****

RemoteId

string

No

The identifier of the tunnel peer, used for Phase 1 negotiation. The value can be up to 100 characters in length and cannot contain spaces. The default value is the IP address of the customer gateway associated with the tunnel.

47.XX.XX.2

TunnelIpsecConfig

object

No

The Phase 2 negotiation configuration.

IpsecAuthAlg

string

No

The authentication algorithm for Phase 2 negotiation.

sha1

IpsecEncAlg

string

No

The encryption algorithm for Phase 2 negotiation. Valid values: aes, aes192, aes256, des, or 3des. Default value: aes.

aes

IpsecLifetime

integer

No

The lifetime of the SA negotiated in Phase 2. Unit: seconds.

86400

IpsecPfs

string

No

The Diffie-Hellman key exchange algorithm used in the second phase of negotiation. Default value: group2.

Valid values: disabled, group1, group2, group5, group14.

group2

EnableTunnelsBgp

boolean

No

This parameter is supported when you create an IPsec-VPN connection in dual-tunnel mode.

false

DryRun

boolean

No

Specifies whether to perform a dry run. Valid values:

  • true: performs a dry run without creating the IPsec-VPN connection. The system checks the required parameters, request syntax, and business limits. If the check fails, the corresponding error is returned. If the check passes, the error code DryRunOperation is returned.

  • false (default): performs the request. After the check passes, the IPsec-VPN connection is created.

false

TunnelBandwidth

string

No

The bandwidth specification of a single VPN tunnel. Valid values:

Standard

Response elements

Element

Type

Description

Example

object

The response parameters.

RequestId

string

The request ID.

88187252-0E26-3C4D-9D1D-32A04454EBBA

VpnConnectionId

string

The IPsec-VPN connection ID.

vco-p0wb09rama8qwwgfn****

Name

string

The name of the IPsec-VPN connection.

nametest

CreateTime

integer

The timestamp when the IPsec-VPN connection was created. Unit: milliseconds.

The timestamp is in the UNIX timestamp format, which represents the total number of milliseconds that have elapsed since January 1, 1970, 00:00:00 (UTC) to the time when the IPsec-VPN connection was created.

1658201810000

Code

string

The status code returned by the current task. A value of 200 indicates that the task is successful.

200

Message

string

The message returned by the current task.

successful

Success

boolean

Indicates whether the current task is successfully executed.

  • true: Successfully executed.

  • false: Not successfully executed.

true

Examples

Success response

JSON format

{
  "RequestId": "88187252-0E26-3C4D-9D1D-32A04454EBBA",
  "VpnConnectionId": "vco-p0wb09rama8qwwgfn****",
  "Name": "nametest",
  "CreateTime": 1658201810000,
  "Code": "200",
  "Message": "successful",
  "Success": true
}

Error codes

HTTP status code

Error code

Error message

Description

400 Resource.QuotaFull The quota of resource is full
400 InvalidVpnConnection.AlreadyExists Vpn connection already exists.
400 VpnRouteEntry.AlreadyExists The specified route entry is already exist. The route already exists.
400 VpnRouteEntry.Conflict The specified route entry has conflict. Route conflicts exist.
400 NotSupportVpnConnectionParameter.IpsecPfs The specified vpn connection ipsec Ipsec Pfs is not support. The PFS parameter set for the IPsec-VPN connection is not supported.
400 NotSupportVpnConnectionParameter.IpsecAuthAlg The specified vpn connection ipsec Auth Alg is not support. The authentication algorithm specified for the IPsec-VPN connection is not supported.
400 VpnRouteEntry.BackupRoute Validate backup route entry failed. Active/standby routes failed authentication.
400 VpnRouteEntry.InvalidWeight Invalid route entry weight value. The weight specified for the route is invalid.
400 InvalidParameter.VpnConnectionName The specified vpn connection name is invalid. The VPN connection name does not meet the requirements.
400 QuotaExceeded.PolicyBasedRoute The maximum number of policy-based routes is exceeded. Existing routes: %s. Routes to be created: %s. Maximum routes: %s. The quota of policy-based routes is reached. Existing routes: %s. Routes to be created: %s. Quota: %s.
400 MissingParameter.TunnelCidr The parameter TunnelCidr is mandatory when BGP is enabled. You must specify the tunnel CIDR block when you enable BGP.
400 OperationUnsupported.EnableBgp Current region does not support enable BGP. The error message returned because the current region does not support BGP.
400 MissingParam.CustomerGatewayAsn Asn of customer gateway is mandatory when BGP is enabled. The ASN of the customer gateway cannot be empty when you enable BGP.
400 IllegalParam.LocalAsn The specified LocalAsn is invalid. The local ASN is invalid.
400 InvalidParameter.BgpConfig The specified BgpConfig is invalid. The error message returned because the BGP configuration is invalid.
400 IllegalParam.EnableBgp VPN connection must enable BGP when VPN gateway has enabled BGP. The error message returned because the VPN connection must use BGP if BGP is enabled for the VPN gateway.
400 IllegalParam.TunnelCidr The specified TunnelCidr is invalid. The TunnelCidr parameter is set to an invalid value.
400 InvalidLocalBgpIp.Malformed The specified LocalBgpIp is malformed. The local BGP IP address is in an abnormal state.
400 IllegalParam.LocalBgpIp The specified LocalBgpIp is invalid. The local BGP IP address is invalid.
400 IllegalParam.LocalSubnet The specified "LocalSubnet" (%s) is invalid. The specified "LocalSubnet" (%s) is invalid.
400 IllegalParam.RemoteSubnet The specified "RemoteSubnet" (%s) is invalid. The specified "RemoteSubnet" (%s) is invalid.
400 OperationFailed.MissCertificate The VPN connecton has not associated any certificates. The error message returned because the VPN gateway is not associated with a certificate.
400 MissingParam.RemoteId The remote ID is mandatory when creating national standard VPN connection. The error message returned because the peer ID is not specified. You must specify the peer ID when you create a VPN connection encrypted by SM.
400 CustomerGateway.ConflictRouteEntry The specified customer gateway has conflict with route entry. The customer gateway conflicts with the current routes.
400 VpnTask.CONFLICT Vpn task has conflict. The VPN operation conflicts. Try again later.
400 Forbidden.TagKey.Duplicated The specified tag key already exists. The tag resources are duplicate.
400 OperationFailed.NoAvailableAmount The available amount of your account is less than 0, please recharge before attempting to purchase. Your account balance is negative. Top up your account before you can make a purchase.
400 SizeLimitExceeded.TagNum The maximum number of tags is exceeded. The number of tags has reached the upper limit.
400 InvalidParameter.TagValue The specified parameter TagValue is invalid. The error message returned because the specified tag value is invalid.
400 InvalidParameter.TagKey The specified parameter TagKey is invalid. The error message returned because the specified tag key is invalid.
400 Duplicated.TagKey The specified parameter TagKey is duplicated. The error message returned because the specified tag key already exists.
400 InternalError The request processing has failed due to some unknown error, exception or failure.
400 InvalidTunnelCidr.Malformed The specified TunnelCidr is malformed. The specified tunnel CIDR block is invalid.
400 CustomerGateway.ConflictVpnIp The customer gateway associated with the IPSec connection should not have the same IP address as the VPN gateway. The customer gateway and VPN gateway of an IPsec-VPN connection cannot use the same IP address.
400 MissingParameter.TunnelOptionsSpecification The required parameters are missing when creating a tunnel for dual-tunnel VPN. The required parameters are missing when creating a tunnel for dual-tunnel VPN.
400 CreateDbrRoutesQuotaFull.QuotaFull The number of created destination routes exceeds the quota limit. The number of created destination routes exceeds the quota limit.
400 DryRunOperation Request validation has been passed with DryRun flag set. The request passed the dry run.
400 VpnConnection.InvalidCreateTunnelOptions The master and slave tunnels must be created at the same time. The primary and secondary tunnels must be created at the same time.
400 OperationUnsupported.LargeTunnelBandwidth Large tunnelBandwidth VpnAttachment is unsupported. Large tunnelBandwidth VpnAttachment is unsupported.
400 IllegalParam.TunnelBandwidth TunnelBandwidth is illegal. TunnelBandwidth is illegal.
400 EncAlgInvalid.DesIncompatible Des/3des in IkeEncAlg and IpsecEncAlg does not support multi algorithm. Des/3des in IkeEncAlg and IpsecEncAlg does not support multi algorithm.
400 OperationFailed.OpenCdtServiceFirst The operation is failed because of %s. The billing method requires CDT billing enabled. Enable CDT billing and try again.
400 IkeVersionInvalid.GcmIncompatible Ikev1 does not support IkeEncAlg of gcm16. Ikev1 does not support IkeEncAlg of gcm16.
400 CustomerGateway.AsnNotConfigured ASN of CustomerGateway is required when enabling BGP on an IPSec connection. When BGP is enabled for IPSec connection, ASN needs to be configured on the customer gateway.
403 Forbbiden.SubUser User not authorized to operate on the specified resource as your account is created by another user.
403 Forbidden User not authorized to operate on the specified resource. You do not have the permissions to manage the specified resource. Apply for the permissions and try again.
404 InvalidCustomerGatewayInstanceId.NotFound The specified customer gateway instance id does not exist. The specified customer gateway does not exist. Check whether the ID of the customer gateway is correct.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.