Help Center/ Virtual Private Network/ API Reference/ API/ S2C VPN API/ S2C VPN Gateway/ Creating a VPN Gateway
Updated on 2024-12-03 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating a VPN Gateway

Function

This API is used to create a VPN gateway. Currently, only pay-per-use VPN gateways can be created.

Calling Method

For details, see Calling APIs.

URI

POST /v5/{project_id}/vpn-gateways
Table 1 Parameter description

Parameter

Type

Mandatory

Description

project_id

String

Yes

Specifies a project ID. You can obtain the project ID by referring to Obtaining the Project ID.

Request

  • Request parameters
    Table 2 Request parameters

    Parameter

    Type

    Mandatory

    Description

    vpn_gateway

    CreateVgwRequestBodyContent object

    Yes

    Specifies the VPN gateway object.
    Table 3 CreateVgwRequestBodyContent

    Parameter

    Type

    Mandatory

    Description

    name

    String

    No
    • Specifies the name of a VPN gateway.
    • The value is a string of 1 to 64 characters, which can contain digits, letters, underscores (_), hyphens (-), and periods (.).
    • If this parameter is not specified, a name in the format of vpngw-**** is automatically generated, for example, vpngw-a45b.

    network_type

    String

    No
    • Specifies the network type of the VPN gateway. A public VPN gateway (public) uses EIPs to connect to a customer gateway. A private VPN gateway (private) uses private IP addresses in a VPC to connect to a customer gateway.
    • The value can be public or private.
    • The default value is public.

    attachment_type

    String

    No
    • Specifies the association mode.
    • The value can be vpc or er.
    • The default value is vpc.

    ip_version

    String

    No
    • Specifies the IP protocol version of the VPN gateway.
    • The value is ipv4 or ipv6.
    • The default value is ipv4.

    er_id

    String

    No
    • Specifies the ID of the enterprise router instance to which the VPN gateway connects.
    • The value is a UUID containing 36 characters.

      Set this parameter only when attachment_type is set to er.

      Either er_id or vpc_id must be specified.

    vpc_id

    String

    No
    • Function description:
      • When attachment_type is set to vpc, vpc_id specifies the ID of the service VPC associated with the VPN gateway.
      • When attachment_type is set to er, vpc_id specifies the ID of the access VPC used by the VPN gateway. In this case, any VPC ID can be used.
    • The value is a UUID containing 36 characters.

      When attachment_type is set to vpc, this parameter is mandatory. When attachment_type is set to er, this parameter is optional; if both vpc_id and access_vpc_id are set, the access_vpc_id value is used.

      Either vpc_id or er_id must be specified.

    You can obtain the VPC ID by querying VPCs.

    local_subnets

    Array of String

    No
    • Specifies an IPv4 local subnet. This subnet is a cloud-side subnet that needs to communicate with an on-premises customer subnet through a VPN.

      A maximum of 50 local subnets can be specified for each VPN gateway. For example, a local subnet can be 192.168.52.0/24.

    • This parameter is mandatory only when attachment_type is set to vpc and ip_version is set to ipv4.

    local_subnets_v6

    Array of String

    No
    • Specifies an IPv6 local subnet. This subnet is a cloud-side subnet that needs to communicate with an on-premises customer subnet through a VPN.

      A maximum of 50 local subnets can be specified for each VPN gateway. For example, a local subnet can be 16af:cacc:1097::/48.

    • This parameter is mandatory only when attachment_type is set to vpc and ip_version is set to ipv6.

    connect_subnet

    String

    No
    • Specifies the ID of the VPC subnet used by the VPN gateway.
    • The value is a UUID containing 36 characters.

      When attachment_type is set to vpc, this parameter is mandatory. When attachment_type is set to er, this parameter is optional; if both connect_subnet and access_subnet_id are set, the access_subnet_id value is used.

      When attachment_type is set to er, the subnet must have at least two idle IP addresses.

      When attachment_type is set to vpc, the subnet must have at least four idle IP addresses if the values of access_subnet_id and connect_subnet are the same or must have at least two idle IP addresses if the values of access_subnet_id and connect_subnet are different.

    bgp_asn

    Long

    No
    • Specifies the BGP AS number of the VPN gateway.
    • The value ranges from 1 to 4294967295.
    • The default value is 64512.

    flavor

    String

    No
    • Specifies the specification of the VPN gateway. For the value range, see the Specification parameter on the page for creating a VPN gateway on the VPN console.
    • Value range:
      • Basic
      • Professional1
      • Professional2
      • Professional1-NonFixedIP
      • Professional2-NonFixedIP
      • GM
      For details about the features supported by different specifications, see Product Specifications of S2C VPN.
      • CN North-Ulanqab1: Basic, GM, Professional1, and Professional2
      • CN South-Guangzhou: Basic, Professional1, and Professional2
      • CN North-Beijing4: Basic, Professional1, and Professional2
      • CN East-Shanghai1: Basic, Professional1, and Professional2
      • CN Southwest-Guiyang1: Basic, Professional1, and Professional2
      • CN-Hong Kong: Professional1 and Professional2
      • AP-Bangkok: Professional1 and Professional2
      • AP-Singapore: Professional1 and Professional2
      • AP-Jakarta: Professional1 and Professional2
      • EU-Dublin: Professional1 and Professional2
      • ME-Abu Dhabi-OP5: Professional1 and Professional2
      • LA-Mexico City2: Professional1 and Professional2
      • TR-Istanbul: Professional1 and Professional2
    • This parameter cannot be set to Basic when network_type is private or when attachment_type is er.
    • The default value is Professional1.

    availability_zone_ids

    Array of String

    No
    • Specifies the AZ where the VPN gateway is to be deployed. If this parameter is not specified, one or two AZs are automatically selected for the VPN gateway. Before specifying AZs, you need to query the available AZ list by referring to Querying the AZs of VPN Gateways (V5.1), and determine the AZs supported for the VPN gateway based on the combination of parameters flavor, attachment_type, and ip_version.
    • Constraints: If two or more AZs are supported for the VPN gateway, specify two AZs. If only one AZ is supported for the VPN gateway, specify one AZ. If no AZ is supported, the VPN gateway cannot be created.

    enterprise_project_id

    String

    No
    • Specifies an enterprise project ID.
    • The value is a UUID (36 characters) or 0.
    • The default value is 0, indicating that the resource belongs to the default enterprise project.

    eip1

    CreateRequestEip object

    No
    • Specifies the first EIP of the VPN gateway using the active-active mode or the active EIP of the VPN gateway using the active-standby mode.
    • Set this parameter only when network_type is set to public.

    eip2

    CreateRequestEip object

    No
    • Specifies the second EIP of the VPN gateway using the active-active mode or the standby EIP of the VPN gateway using the active-standby mode.
    • Set this parameter only when network_type is set to public.

    access_vpc_id

    String

    No
    • Specifies the ID of the access VPC used by the VPN gateway.
    • The value is a UUID containing 36 characters.
    • By default, the value is the same as the value of vpc_id.

      You can obtain the VPC ID by querying VPCs.

    access_subnet_id

    String

    No
    • Specifies the ID of the subnet in the access VPC used by the VPN gateway.
    • The value is a UUID containing 36 characters.

      When attachment_type is set to er, the subnet must have at least two idle IP addresses.

      When attachment_type is set to vpc, the subnet must have at least four idle IP addresses if the values of access_subnet_id and connect_subnet are the same or must have at least two idle IP addresses if the values of access_subnet_id and connect_subnet are different.

    • By default, the value is the same as the value of connect_subnet.

    ha_mode

    String

    No
    • Specifies the HA mode of the gateway. The value can be active-active or active-standby.
    • Value range: active-active, active-standby
    • Default value: active-active

    access_private_ip_1

    String

    No
    • Specifies private IP address 1 of a private VPN gateway. Set this parameter if a private VPN gateway needs to use specified IP addresses. In active/standby gateway mode, the specified IP address is the active IP address. In active-active gateway mode, the specified IP address is active IP address 1.
    • Value range: allocatable IP addresses in the access subnet
    • This parameter must be specified together with access_private_ip_2, and the two parameters must have different values.

    access_private_ip_2

    String

    No
    • Specifies private IP address 2 of a private VPN gateway. Set this parameter if a private VPN gateway needs to use specified IP addresses. In active/standby gateway mode, the specified IP address is the standby IP address. In active-active gateway mode, the specified IP address is active IP address 2.
    • Value range: allocatable IP addresses in the access subnet
    • This parameter must be specified together with access_private_ip_1, and the two parameters must have different values.

    tags

    Array of VpnResourceTag objects

    No
    • Specifies a tag list.
    • A maximum of 20 tags can be specified.
    Table 4 CreateRequestEip

    Parameter

    Type

    Mandatory

    Description

    id

    String

    No
    • Specifies an EIP ID.
    • The value is a UUID containing 36 characters.
    • Set this parameter only when an existing EIP is used.

    You can obtain the EIP ID by referring to Querying EIPs.

    type

    String

    No
    • Specifies the EIP type.
    • The value is a string of 0 to 36 characters.

      For the value range, see the type field in Table 6 in Assigning an EIP. The value 5_bgp is preferred if it is supported.

    • Set this parameter only when a new EIP is used.

      For more constraints, see the type field in Table 3 in Assigning an EIP.

    charge_mode

    String

    No
    • Specifies the billing mode of EIP bandwidth.
    • Value range:

      bandwidth: billed by bandwidth

      traffic: billed by traffic

    • This parameter is mandatory only when a new EIP not binding to shared bandwidth is created.
    • The default value is bandwidth.

    bandwidth_size

    Integer

    No
    • Specifies the bandwidth (Mbit/s) of an EIP. The maximum EIP bandwidth varies according to regions and depends on the EIP service. You can submit a service ticket to increase the maximum EIP bandwidth under your account.
    • The value ranges from 1 to 1000. For details, see the EIP documentation.
    • This parameter is mandatory only when a new EIP not binding to shared bandwidth is created.

      The value cannot be greater than 100 when flavor is set to Basic. The value cannot be greater than 300 when flavor is set to Professional1. The value cannot be greater than 1000 when flavor is set to Professional2. The value cannot be greater than 500 when flavor is set to GM.

    bandwidth_name

    String

    No
    • Specifies the bandwidth name of an EIP.
    • The value is a string of 1 to 64 characters, which can contain digits, letters, underscores (_), hyphens (-), and periods (.).
    • This parameter is mandatory only when a new EIP not binding to shared bandwidth is created.
    • When a new EIP is used and this parameter is not set, an EIP bandwidth name in the format of vpngw-bandwidth-**** is automatically generated, for example, vpngw-bandwidth-e1fa.

    bandwidth_id

    String

    No
    • Specifies a bandwidth ID. You can specify existing shared bandwidth when creating an EIP.
    • The value is a UUID containing 36 characters.
    • This parameter is mandatory only when you want to bind shared bandwidth to an EIP.
    Table 5 VpnResourceTag

    Parameter

    Type

    Mandatory

    Description

    key

    String

    Yes
    • Specifies a tag key.
    • The value is a string of 1 to 128 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).

    value

    String

    Yes
    • Specifies a tag value.
    • The value is a string of 0 to 255 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).
  • Example requests
    1. Create a VPN gateway that uses existing EIPs and is associated with a VPC. 
      POST https://{Endpoint}/v5/{project_id}/vpn-gateways

{
    "vpn_gateway": {
        "vpc_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "local_subnets": [
            "192.168.0.0/24", "192.168.1.0/24"
        ],
        "connect_subnet": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "eip1": {
            "id": "cff40e5e-demo-a8df-va86-7366077bf097"
        },
        "eip2": {
            "id": "d290f1ee-demo-a8df-va86-d701748f0851"
        }
    }
}
    2. Create a VPN gateway that uses new EIPs and is associated with an enterprise router. 
      POST https://{Endpoint}/v5/{project_id}/vpn-gateways

{
    "vpn_gateway": {
        "name": "vpngw-1234",
        "attachment_type": "er",
        "er_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "vpc_id": "584a238f-demo-a8df-va86-edca746f6277",
        "connect_subnet": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "bgp_asn": 65533,
        "flavor": "Professional2",
        "availability_zone_ids": [
            "cn-south-1f",
            "cn-south-1e"
        ],
        "eip1": {
            "type": "5_bgp",
            "charge_mode": "bandwidth",
            "bandwidth_size": 1000,
            "bandwidth_name": "vpngw-bandwidth-1391"
        },
        "eip2": {
            "type": "5_bgp",
            "charge_mode": "bandwidth",
            "bandwidth_size": 1000,
            "bandwidth_name": "vpngw-bandwidth-1392"
        }
    }
}
    3. Create a private VPN gateway associated with a VPC. 
      POST https://{Endpoint}/v5/{project_id}/vpn-gateways

{
    "vpn_gateway": {
        "vpc_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "local_subnets": [
            "192.168.0.0/24", "192.168.1.0/24"
        ],
        "connect_subnet": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "network_type": "private"
    }
}

Response

  • Response parameters

    Returned status code 201: successful operation

    Table 6 Parameters in the response body

    Parameter

    Type

    Description

    vpn_gateway

    ResponseVpnGateway object

    Specifies the VPN gateway object.

    request_id

    String

    Specifies a request ID.
    Table 7 ResponseVpnGateway

    Parameter

    Type

    Description

    id

    String
    • Specifies a VPN gateway ID.
    • The value is a UUID containing 36 characters.

    name

    String
    • Specifies the name of a VPN gateway.
    • The value is a string of 1 to 64 characters, which can contain digits, letters, underscores (_), and hyphens (-).

    network_type

    String
    • Specifies the network type of the VPN gateway.
    • The value can be public or private.
    • The default value is public.

    attachment_type

    String
    • Specifies the association mode.
    • The value can be vpc or er.

    ip_version

    String
    • Specifies the IP protocol version of the VPN gateway.
    • The value is ipv4 or ipv6.

    certificate_id

    String
    • Specifies the certificate ID.
    • The value is a UUID containing 36 characters.

    er_id

    String

    Specifies the ID of the enterprise router instance to which the VPN gateway connects. This parameter is available only when attachment_type is set to er.

    vpc_id

    String

    When attachment_type is set to vpc, vpc_id specifies the ID of the service VPC associated with the VPN gateway.

    This parameter is not returned when attachment_type is set to er. To view the ID of the access VPC used by the VPN gateway, check the access_vpc_id field.

    local_subnets

    Array of String

    Specifies an IPv4 local subnet. This subnet is a cloud-side subnet that needs to communicate with an on-premises network through a VPN. An example subnet is 192.168.52.0/24. This parameter is returned only when attachment_type is set to vpc and ip_version is set to ipv4.

    local_subnets_v6

    Array of String

    Specifies an IPv6 local subnet. This subnet is a cloud-side subnet that needs to communicate with an on-premises network through a VPN. An example subnet is 16af:cacc:1097::/48. This parameter is returned only when attachment_type is set to vpc and ip_version is set to ipv6.

    connect_subnet

    String

    Specifies the ID of the VPC subnet used by the VPN gateway.

    bgp_asn

    Long

    Specifies the BGP AS number of the VPN gateway.

    flavor

    String
    • Specifies the specification of the VPN gateway. For the value range, see the Specification parameter on the page for creating a VPN gateway on the VPN console.
    • Value range:

      v300: The maximum forwarding bandwidth is 300 Mbit/s. This value has been deprecated, but is retained for compatibility purposes. Using this value is not recommended.

      v1g: The maximum forwarding bandwidth is 1 Gbit/s. This value has been deprecated, but is retained for compatibility purposes. Using this value is not recommended.

      Basic: The maximum forwarding bandwidth is 100 Mbit/s.

      Professional1: The maximum forwarding bandwidth is 300 Mbit/s.

      Professional1-NonFixedIP: The maximum forwarding bandwidth is 300 Mbit/s.

      Professional2: The maximum forwarding bandwidth is 1 Gbit/s.

      Professional2-NonFixedIP: The maximum forwarding bandwidth is 1 Gbit/s.

      GM: The maximum forwarding bandwidth is 500 Mbit/s.

    connection_number

    Integer

    Specifies the maximum number of VPN connections supported for the VPN gateway.

    used_connection_number

    Integer

    Specifies the number of VPN connections that have been used by the VPN gateway.

    used_connection_group

    Integer

    Specifies the number of VPN connection groups that have been used by the VPN gateway. A connection group consists of two connections between a customer gateway and a VPN gateway. By default, 10 VPN connection groups are included free of charge with the purchase of a VPN gateway.

    enterprise_project_id

    String
    • Specifies an enterprise project ID.
    • The value is a UUID (36 characters) or 0.

    access_vpc_id

    String
    • Specifies the ID of the access VPC used by the VPN gateway.
    • The value is a UUID containing 36 characters.

    access_subnet_id

    String
    • Specifies the ID of the subnet in the access VPC used by the VPN gateway.
    • The value is a UUID containing 36 characters.

    ha_mode

    String
    • Specifies the HA mode of the gateway. The value can be active-active or active-standby.
    • Value range: active-active, active-standby
    • Default value: active-active

    policy_template

    PolicyTemplate object

    Specifies a policy template. This parameter is returned only for a VPN gateway that supports access via non-fixed IP addresses.

    tags

    Array of VpnResourceTag objects

    Specifies a tag list.
    Table 8 VpnResourceTag

    Parameter

    Type

    Description

    key

    String
    • Specifies a tag key.
    • The value is a string of 1 to 128 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).

    value

    String
    • Specifies a tag value.
    • The value is a string of 0 to 255 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).
    Table 9 PolicyTemplate

    Parameter

    Type

    Description

    ike_policy

    IkePolicy object

    Specifies the IKE policy object.

    ipsec_policy

    IpsecPolicy object

    Specifies the IPsec policy object.
    Table 10 IkePolicy

    Parameter

    Type

    Description

    encryption_algorithm

    String
    • Specifies an encryption algorithm.
    • The value can be aes-256-gcm-16, aes-128-gcm-16, aes-256, aes-192, or aes-128.

    dh_group

    String
    • Specifies the DH group used for key exchange in phase 1.
    • The value can be group14, group15, group16, group19, group20, group21, or disable.

    authentication_algorithm

    String
    • Specifies an authentication algorithm.
    • The value can be sha2-512, sha2-384, or sha2-256.

    lifetime_seconds

    Integer
    • Specifies the SA lifetime. When the lifetime expires, an IKE SA is automatically updated.
    • The value ranges from 60 to 604800, in seconds.
    Table 11 IpsecPolicy

    Parameter

    Type

    Description

    authentication_algorithm

    String
    • Specifies an authentication algorithm.
    • The value can be sha2-512, sha2-384, or sha2-256.

    encryption_algorithm

    String
    • Specifies an encryption algorithm.
    • The value can be aes-256-gcm-16, aes-128-gcm-16, aes-256, aes-192, or aes-128.

    pfs

    String
    • Specifies the DH key group used by PFS.
    • The value can be group14, group15, group16, group19, group20, group21, or disable.

    lifetime_seconds

    Integer
    • Specifies the lifetime of a tunnel established over an IPsec connection.
    • The value ranges from 30 to 604800, in seconds.
  • Example responses
    1. Response to the request for creating a VPN gateway that uses existing EIPs and is associated with a VPC 
      {
    "vpn_gateway": {
        "id": "134f9fb1-demo-a8df-va86-2040a5c13325",
        "name": "vpngw-9f24",
        "network_type": "public",
        "attachment_type": "vpc",
        "vpc_id": "0cf79a3f-demo-a8df-va86-d7ace626b0fa",
        "local_subnets": ["192.168.0.0/24"],
        "connect_subnet": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "bgp_asn": 64512,
        "flavor": "Professional1",
        "connection_number": 200,
        "used_connection_number": 0,
        "used_connection_group": 0,
        "enterprise_project_id": "0",
        "access_vpc_id": "0cf79a3f-demo-a8df-va86-d7ace626b0fa",
        "access_subnet_id": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "ha_mode": "active-active"
    },
    "request_id": "7b37532a-d6e4-46b9-98dc-9169ec2ca58f"
}
    2. Response to the request for creating a VPN gateway that uses new EIPs and is associated with an enterprise router 
      {
    "vpn_gateway": {
        "id": "80ac167b-demo-a8df-va86-a9a2a23223b8",
        "name": "vpngw-1234",
        "network_type": "public",
        "attachment_type": "er",
        "ip_version": "ipv4",
        "er_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "bgp_asn": 65533,
        "flavor": "Professional2",
        "connection_number": 200,
        "used_connection_number": 0,
        "used_connection_group": 0,
        "enterprise_project_id": "0",
        "access_vpc_id": "0cf79a3f-demo-a8df-va86-d7ace626b0fa",
        "access_subnet_id": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "ha_mode": "active-active"
    },
    "request_id": "cd71cade-bfbd-410b-b672-4bfe46cfc311"
}
    3. Response to the request for creating a private VPN gateway associated with a VPC 
      {
    "vpn_gateway": {
        "id": "80ac167b-demo-a8df-va86-a9a2a23223b8",
        "name": "vpngw-1234",
        "network_type": "private",
        "attachment_type": "vpc",
        "vpc_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "local_subnets": ["192.168.0.0/24", "192.168.1.0/24"],
        "connect_subnet": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "bgp_asn": 65533,
        "flavor": "Professional2",
        "connection_number": 200,
        "used_connection_number": 0,
        "used_connection_group": 0,
        "enterprise_project_id": "0",
        "access_vpc_id": "cb4a631d-demo-a8df-va86-ca3fa348c36c",
        "access_subnet_id": "f5741286-demo-a8df-va86-2c82bd9ee114",
        "ha_mode": "active-active"
    },
    "request_id": "cd71cade-bfbd-410b-b672-4bfe46cfc311"
}

Status Codes

For details, see Status Codes.

Parent topic: S2C VPN Gateway