tencent cloud

Cloud Load Balancer

CreateLoadBalancer

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-06-17 17:27:09

1. API Description

Domain name for API request: clb.intl.tencentcloudapi.com.

This API (CreateLoadBalancer) is used to create a CLB instance. To use the CLB service, you first need to purchase one or more instances. After this API is called successfully, a unique instance ID will be returned. There are two types of instances: public network and private network. For more information, see the product types in the product documentation.
Note: (1) To apply for a CLB instance in the specified AZ and cross-AZ disaster recovery, please submit a ticket; (2) Currently, IPv6 is supported only in Beijing, Shanghai, and Guangzhou regions.
This is an async API. After it is returned successfully, you can call the DescribeLoadBalancers API to query the status of the instance (such as creating and normal) to check whether it is successfully created.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateLoadBalancer.
Version Yes String Common Params. The value used for this API: 2018-03-17.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
LoadBalancerType Yes String

Network type of the Cloud Load Balancer instance:
OPEN: public network attribute, INTERNAL: private network attribute.

Forward No Integer

Type of the Cloud Load Balancer instance. 1: Common CLB instance. Currently only support passing in 1.

LoadBalancerName No String

The name of the Cloud Load Balancer instance is effective only when creating an instance. Rule: 1-80 characters in internationally compatible languages such as English letters, Chinese characters, digits, connecting line "-", underscore "_", and other common characters (Unicode supplementary characters such as emoji and rare Chinese characters are forbidden). Note: If the name is identical to an existing Cloud Load Balancer instance name in the system, the system will automatically generate the name for the created CLB instance.

VpcId No String Network ID of the target device on the CLB backend, such as vpc-12345678, which can be obtained through the DescribeVpcEx API. If this parameter is not entered, DefaultVPC is used by default. This parameter is required when creating a private network instance.
SubnetId No String

When you purchase a private network CLB instance in a VPC, the subnet ID must be specified. The VIP of the private network CLB instance is generated in this subnet.
This parameter is required when you create a private network CLB instance or a CLB instance of the IPv6FullChain version.
It cannot be specified when you create a public network IPv4 CLB instance.

ProjectId No Integer ID of the project to which a CLB instance belongs, which can be obtained through the DescribeProject API. If this parameter is not entered, the default project will be used.
AddressIPVersion No String

Applicable only to public network CLB. IP version, valid values: IPV4, IPV6, IPv6FullChain, case-insensitive, default value IPV4. Description: A value of IPV6 means IPV6 NAT64 version; a value of IPv6FullChain means IPv6 version.

Number No Integer

Count of Cloud Load Balancers to create, default value is 1. The count must not exceed the maximum value allowed for the account, with a default creation maximum value of 20.

MasterZoneId No String

Applicable only to public network load balancing with IP version IPv4. Sets the primary AZ ID for cross-AZ disaster recovery. Both AZ ID and name are supported, such as 100001 or ap-guangzhou-1.
Note: The primary AZ loads traffic. The secondary AZ does not load traffic by default and is used only if the primary AZ becomes unavailable.

ZoneId No String

Applicable only to public network load balancing with IP version IPv4. AZ ID, availability zone id and name are supported. Specify availability zone to create a CLB instance. For example: 100001 or ap-guangzhou-1.

InternetAccessible No InternetAccessible

Maximum outbound bandwidth under the network billing mode. It applies only to LCU-supported instances of the private network type and all instances of the public network type.

VipIsp No String

Applicable only to public network CLB. Currently, only Guangzhou, Shanghai, Nanjing, Jinan, Hangzhou, Fuzhou, Beijing, Shijiazhuang, Wuhan, Changsha, Chengdu, and Chongqing regions support static single-line IP type. If you need to experience it, contact business manager to submit a request. After approval, you can select operator type of China Mobile (CMCC), China Unicom (CUCC), or China Telecom (CTCC). Only can be used network billing mode BANDWIDTH_PACKAGE. If this parameter is not specified, use BGP by default. You can query ISPs supported in a region via DescribeResources api.

Tags.N No Array of TagInfo

When purchasing a Cloud Load Balancer, you can tag it with up to 20 tag key-value pairs.

Vip No String

Specify VIP to apply for Cloud Load Balancer. This parameter is optional. If this parameter is not specified, VIP is automatically assigned. This parameter is supported for IPv4 and IPv6 types but not for IPv6 NAT64 type.
Note: When creating a private network instance or a public IPv6 BGP instance with a designated VIP, creation fails if the VIP is not within the IP range of the specified VPC subnet or if the VIP is already occupied.

BandwidthPackageId No String

Bandwidth package ID, which can be obtained through the DescribeBandwidthPackages API. When this parameter is specified, the network billing mode (InternetAccessible.InternetChargeType) supports only billing by bandwidth package (BANDWIDTH_PACKAGE), and the bandwidth package attributes determine the settlement method. For IPv6 Cloud Load Balancer instances purchased by non-promoted users with a non-BGP operator type, specifying bandwidth package ID is unsupported.

ExclusiveCluster No ExclusiveCluster

Dedicated instance info. This parameter is required when creating a private network CLB instance of exclusive type.

SlaType No String

Performance capacity specification.

  • If you need to create an LCU-supported instance, this parameter is required. Valid values:
    • clb.c2.medium: Standard
    • clb.c3.small: Advanced 1
    • clb.c3.medium: Advanced 2
    • clb.c4.small: Super Large 1
    • clb.c4.medium: Super Large 2
    • clb.c4.large: Super Large 3
    • clb.c4.xlarge: Super Large 4
  • For Chinese site users who need to create a shared instance, this parameter is not required. International site users will purchase a standard instance by default if this parameter is not passed.
For specification details, see Instance Specifications Comparison.
ClusterIds.N No Array of String

Cluster ID. This cluster identifier is used for configuring a public cloud exclusive cluster or a local dedicated cluster. To apply for a public cloud exclusive cluster, submit a ticket. For local dedicated clusters, refer to the description in Local Dedicated Cluster.

ClientToken No String

String used to ensure request idempotency. This string is generated by the customer and must be unique among different requests, with a maximum value of 64 ASCII characters. If not specified, request idempotency cannot be guaranteed.

SnatPro No Boolean

Whether binding cross-regional or cross-Vpc IP addresses is supported.

SnatIps.N No Array of SnatIp

Enable the cross-regional or cross-Vpc IP binding feature to create a SnatIp.

ClusterTag No String

Tag of the Stgw exclusive cluster.

SlaveZoneId No String

Applicable only to public network load balancing with IP version IPv4. Sets the secondary AZ ID for cross-AZ disaster recovery. AZ ID and name are supported, such as 100001 or ap-guangzhou-1.
Note: The secondary AZ is the availability zone that needs to carry traffic after primary availability zone failure. Query a region's list of primary/secondary AZs via the DescribeResources API. [If you need to trial the feature, submit a ticket application via Work Order]

EipAddressId No String

The unique ID of EIP can be accessed through the DescribeAddresses api for the query. Example: eip-qhx8udkc, applicable only to bind EIP for private network CLB.

LoadBalancerPassToTarget No Boolean

Allow CLB traffic to the Target. Enable (true): verify security groups on CLB; deny CLB traffic to the Target (false): verify security groups on both CLB and backend instances. IPv6 CLB security group default permit, this parameter is not required.

DynamicVip No Boolean

Create a domain-name based CLB.

Egress No String

Network outbound

LBChargePrepaid No LBChargePrepaid

Prepaid billing attributes of the CLB instance

LBChargeType No String

Billing type of the CLB instance. Valid values: POSTPAID_BY_HOUR and PREPAID. Default value: POSTPAID_BY_HOUR.

Enumeration values:

  • POSTPAID_BY_HOUR: Pay-As-You-Go
  • PREPAID: Monthly Subscription
AccessLogTopicId No String

L7 access log topic ID

AdvancedRoute No Boolean

Whether layer-7 advanced routing is enabled

AvailableZoneAffinityInfo No AvailableZoneAffinityInfo

Availability zone affinity info

3. Output Parameters

Parameter Name Type Description
LoadBalancerIds Array of String

An array consisting of the unique IDs of Cloud Load Balancer instances.
In certain scenarios, such as delay in creation, this field may return null. At this point, you can query the created resource ID through the DescribeTaskStatus API using the RequestId or DealName parameter returned by the API.


Note: This field may return null, indicating that no valid values can be obtained.
DealName String

Order number.


Note: This field may return null, indicating that no valid values can be obtained.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Creating a Public Network CLB Instance

This example shows you how to create a public network CLB instance in a VPC.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateLoadBalancer
<Common request parameters>

{
    "Forward": 1,
    "ProjectId": 0,
    "LoadBalancerType": "OPEN",
    "VpcId": "vpc-30xqxt9p",
    "LoadBalancerName": "test-open"
}

Output Example

{
    "Response": {
        "LoadBalancerIds": [
            "lb-6efswuxa"
        ],
        "DealName": "20220101660009831340631",
        "RequestId": "9b3f0b57-fb64-4918-8dd6-ce02604fb52c"
    }
}

Example2 Creating a Private Network CLB Instance

This example shows you how to create a private network CLB instance in a VPC.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateLoadBalancer
<Common request parameters>

{
    "Forward": 1,
    "SubnetId": "subnet-k57djpow",
    "LoadBalancerType": "INTERNAL",
    "VpcId": "vpc-30xqxt9p",
    "LoadBalancerName": "test_internal"
}

Output Example

{
    "Response": {
        "LoadBalancerIds": [
            "lb-kmfrnqci"
        ],
        "DealName": "20211230660009761735781",
        "RequestId": "7ffa6830-cd1b-4bc4-8e24-1688885f594a"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation Operation failed.
InternalError Internal error.
InvalidParameter Parameter error.
InvalidParameter.ClientTokenLimitExceeded To ensure no resource leakage and maintain the ID idempotence of created resources, ClientToken is used to create resources. If the order process has ended and shipment failed, or the order process has not been updated for a long time, a message will indicate that the current ClientToken has timed out.
InvalidParameter.FormatError Incorrect parameter format.
InvalidParameterValue Parameter value error.
InvalidParameterValue.Length Invalid parameter length.
InvalidParameterValue.Range Invalid parameter value range.
LimitExceeded The quota limit is exceeded.
MissingParameter Parameters are missing.
ResourceInsufficient Insufficient resources.
UnauthorizedOperation Unauthorized operation.
UnsupportedOperation The operation is not supported.

Ajuda e Suporte

Esta página foi útil?

comentários