tencent cloud

Feedback

CreateLoadBalancer

Last updated: 2024-09-05 19:28:54

    1. API Description

    Domain name for API request: clb.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 No String Common Params. This parameter is not required for this API.
    LoadBalancerType Yes String CLB instance network type:
    OPEN: public network; INTERNAL: private network.
    Forward No Integer CLB instance type. Valid value: 1 (generic CLB instance).
    LoadBalancerName No String CLB instance name, which takes effect only when only one instance is to be created in the request. It can consist 1 to 60 letters, digits, hyphens (-), or underscores (_).
    Note: if the name of the new CLB instance already exists, a default name will be generated automatically.
    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 A subnet ID must be specified when you purchase a private network CLB instance in a VPC, and the VIP of this instance will be generated in this subnet. This parameter is required for creating a 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 It's only applicable to public network CLB instances. IP version. Values: IPV4, IPV6 and IPv6FullChain (case-insensitive). Default: IPV4. Note: IPV6 indicates IPv6 NAT64, while IPv6FullChain indicates IPv6.
    Number No Integer Number of CLBs to be created. Default value: 1.
    MasterZoneId No String ID of the primary availability zone configured for cross-availability zone disaster recovery, such as 100001 or ap-guangzhou-1. It applies only to public network CLB.Note: The primary availability zone is the one that carries traffic. The replica availability zone does not carry traffic by default and is only used when the primary availability zone is unavailable. Currently, primary and replica availability zones are supported only for the IPv4 CLB instances in the regions of Guangzhou, Shanghai, Nanjing, Beijing, Chengdu, Shenzhen Finance Zone, Hong Kong (China), Seoul, Frankfurt, and Singapore. You can query the list of primary availability zones in a region through the DescribeResources API.
    ZoneId No String Specifies an AZ ID for creating a CLB instance, such as ap-guangzhou-1, which is applicable only to public network CLB instances.
    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 ISP of VIP. Values: CMCC (China Mobile), CUCC (China Unicom) and CTCC (China Telecom). You need to activate static single-line IPs. This feature is in beta and is only available in Guangzhou, Shanghai, Nanjing, Jinan, Hangzhou, Fuzhou, Beijing, Shijiazhuang, Wuhan, Changsha, Chengdu and Chongqing regions. To try it out, please contact your sales rep. If it's specified, the network billing mode must be BANDWIDTH_PACKAGE. If it's not specified, BGP is used by default. To query ISPs supported in a region, please use DescribeResources.
    Tags.N No Array of TagInfo Tags the CLB instance when purchasing it. Up to 20 tag key value pairs are supported.
    Vip No String Specifies the VIP for the application of a CLB instance. This parameter is optional. If you do not specify this parameter, the system automatically assigns a value for the parameter. IPv4 and IPv6 CLB instances support this parameter, but IPv6 NAT64 CLB instances do not.
    Note: If the specified VIP is occupied or is not within the IP range of the specified VPC subnet, you cannot use the VIP to create a CLB instance in a private network or an IPv6 BGP CLB instance in a public network.
    BandwidthPackageId No String Bandwidth package ID. If this parameter is specified, the network billing mode (InternetAccessible.InternetChargeType) will only support billing by bandwidth package (BANDWIDTH_PACKAGE). The attributes of the bandwidth package determine the settlement method. For IPv6 CLB instances purchased by bill-by-CVM users, if the ISP type is not BGP, the bandwidth package ID cannot be specified.
    ExclusiveCluster No ExclusiveCluster Information about the dedicated CLB instance. You must specify this parameter when you create a dedicated CLB instance in a private network.
    SlaType No String Specification of the LCU-supported instance.
    • 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
    • If you need to create a shared instance, this parameter is not required.
    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 cloud dedicated cluster. To apply for a public cloud exclusive cluster, submit a ticket. For cloud dedicated clusters, see the descriptions in Cloud Dedicated Cluster.
    ClientToken No String A unique string supplied by the client to ensure that the request is idempotent. Its maximum length is 64 ASCII characters. If this parameter is not specified, the idempotency of the request cannot be guaranteed.
    SnatPro No Boolean Whether Binding IPs of other VPCs feature switch
    SnatIps.N No Array of SnatIp Creates SnatIp when the binding IPs of other VPCs feature is enabled
    ClusterTag No String Tag for the STGW exclusive cluster.
    SlaveZoneId No String Specifies the secondary AZ ID for cross-AZ disaster recovery, such as 100001 or ap-guangzhou-1. It is applicable only to public network CLB.
    Note: The traffic only goes to the secondary AZ when the primary AZ is unavailable. You can query the list of primary and secondary AZ of a region by calling DescribeResources.
    EipAddressId No String Unique ID of an EIP, which can only be used when binding the EIP of a private network CLB instance. E.g., eip-11112222.
    LoadBalancerPassToTarget No Boolean Whether to allow CLB traffic to the target group. true: allows CLB traffic to the target group and verifies security groups only on CLB; false: denies CLB traffic to the target group and verifies security groups on both CLB and backend instances.
    DynamicVip No Boolean Upgrades to domain name-based CLB
    Egress No String Network egress point
    LBChargePrepaid No LBChargePrepaid Prepaid billing attributes of a CLB instance

    3. Output Parameters

    Parameter Name Type Description
    LoadBalancerIds Array of String Array of unique CLB instance IDs.
    This field may return null in some cases, such as there is delay during instance creation. You can query the IDs of the created instances by invoking DescribeTaskStatus with the RequestId or DealName returned by this API.
    Note: This field may return null, indicating that no valid values can be obtained.
    DealName String Order ID.
    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.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: CreateLoadBalancer
    <Common request parameters>
    
    
    
    {
        "Forward": 1,
        "ProjectId": 0,
        "LoadBalancerType": "OPEN",
        "VpcId": "vpc-30xqxt9p",
        "LoadBalancerName": "test"
    }
    

    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.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 Wrong parameter format.
    InvalidParameterValue Incorrect parameter value.
    InvalidParameterValue.Length Wrong parameter length.
    InvalidParameterValue.Range Wrong parameter value range.
    LimitExceeded Quota exceeded.
    MissingParameter Missing parameter.
    ResourceInsufficient Insufficient resources.
    UnauthorizedOperation Unauthorized operation.
    UnsupportedOperation Unsupported operation.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support