High-availability virtual IP address (HAVIP)

Updated at：2025-10-16

Initialization

Confirm Endpoint

Before configuring the endpoint for SDK usage, please refer to the developer guide section on Subnet Domains to understand endpoint-related concepts. Baidu AI Cloud currently supports multiple regions. Please refer to Region Selection Guide.

Currently supported regions are: "North China-Beijing," "South China-Guangzhou," "East China-Suzhou," "Hong Kong," "Central Finance-Wuhan," and "North China-Baoding." Corresponding details:

Access region	Endpoint	Protocol
BJ	bcc.bj.baidubce.com	HTTP and HTTPS
GZ	bcc.gz.baidubce.com	HTTP and HTTPS
SU	bcc.su.baidubce.com	HTTP and HTTPS
HKG	bcc.hkg.baidubce.com	HTTP and HTTPS
FWH	bcc.fwh.baidubce.com	HTTP and HTTPS
BD	bcc.bd.baidubce.com	HTTP and HTTPS

Retrieve access key

To utilize Baidu AI Cloud's subnet, users need a valid AK (Access Key ID) and SK (Secret Access Key) for signature authentication. The AK/SK pairs are system-generated identifiers used for authentication and subnet access.

Your AK/SK information can be obtained and understood through the following steps:

Create AK/SK

Create a new HAVIP client

A HAVIP client acts as the interface for HAVIP services, providing developers with a variety of methods for interacting with these services.

Create a new HAVIP client with AK/SK

Users can refer to the following code to create a new HAVIP Client to access HAVIP with AK/SK:

1import (
2"github.com/baidubce/bce-sdk-go/services/havip"
3)
4func main() {
5 // User’s Access Key ID and Secret Access Key
6ACCESS_KEY_ID, SECRET_ACCESS_KEY := <your-access-key-id>, <your-secret-access-key>
7 // User-specified Endpoint
8ENDPOINT := <domain-name>
9 // Initialize a HAVIPClient
10havipClient, err := havip.NewClient(AK, SK, ENDPOINT)
11}

In the code above, ACCESS_KEY_ID corresponds to “Access Key ID” in the console. SECRET_ACCESS_KEY corresponds to “Access Key Secret” in the console. Refer to the Guide - How to Retrieve AKSK. The third parameter ENDPOINT is a user-specified domain name. If left empty, the default domain name will be used as the HAVIP service address.

Note:The endpoint parameter must be defined with the domain name of the specified region. For example, if the service is located in Beijing, the endpoint will be bcc.bj.baidubce.com.

Create a HAVIP client with STS

Request STS Token

HAVIP allows temporary third-party access through the STS mechanism. STS (Security Token Service) is a temporary authentication service provided by Baidu AI Cloud. Using STS, you can issue access credentials with specific validity periods and permissions, which third-party users can utilize to directly call Baidu AI Cloud APIs or SDKs to access cloud resources.

To access HAVIP through STS, users must initially request a certification string using the STS client.

Create HAVIP Client with STS Token

After acquiring the STS token, configure it in the HAVIP Client to enable the creation of STS-enabled HAVIP clients.

Code example

The GO SDK implements the STS service API. Below is a complete example for requesting an STS Token and creating an HAVIP Client object:

1import (
2  "fmt"
3 "github.com/baidubce/bce-sdk-go/auth"                    //Import the authentication module
4 "github.com/baidubce/bce-sdk-go/services/havip" //Import HAVIP service module
5 "github.com/baidubce/bce-sdk-go/services/sts"            //Import the Baige service module
6)
7func main() {
8 //Create a Client object for the STS service, using the default Endpoint
9  AK, SK := <your-access-key-id>, <your-secret-access-key>
10  stsClient, err := sts.NewClient(AK, SK)
11  if err != nil {
12    fmt.Println("create sts client object :", err)
13    return
14  }
15 //Obtain a temporary authentication token with a validity period of 60 seconds and an empty ACL
16  stsObj, err := stsClient.GetSessionToken(60, "")
17  if err != nil {
18    fmt.Println("get session token failed:", err)
19    return
20    }
21  fmt.Println("GetSessionToken result:")
22  fmt.Println("  accessKeyId:", stsObj.AccessKeyId)
23  fmt.Println("  secretAccessKey:", stsObj.SecretAccessKey)
24  fmt.Println("  sessionToken:", stsObj.SessionToken)
25  fmt.Println("  createTime:", stsObj.CreateTime)
26  fmt.Println("  expiration:", stsObj.Expiration)
27  fmt.Println("  userId:", stsObj.UserId)
28 //Create a HAVIP Client object using the requested temporary STS, with the default endpoint
29  havipClient, err := havip.NewClient(stsObj.AccessKeyId, stsObj.SecretAccessKey, "bcc.bj.baidubce.com")
30  if err != nil {
31    fmt.Println("create havip client failed:", err)
32    return
33  }
34  stsCredential, err := auth.NewSessionBceCredentials(
35    stsObj.AccessKeyId,
36    stsObj.SecretAccessKey,
37    stsObj.SessionToken)
38  if err != nil {
39    fmt.Println("create sts credential object failed:", err)
40    return
41  }
42  havipClient.Config.Credentials = stsCredential
43}

Note: Currently, when configuring a HAVIP client with STS, regardless of where the corresponding HAVIP service endpoint is located, the STS endpoint must be set to http://sts.bj.baidubce.com. This default is utilized when creating an STS object in the above code.

Configure HTTPS access to HAVIP

HAVIP supports the HTTPS transport protocol. To use HTTPS to access HAVIP services with the HAVIP Go SDK, specify HTTPS in the endpoint when creating the HAVIP client object.

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2 ENDPOINT := ""https://bcc.bj.baidubce.com" // Specify the use of HTTPS protocol
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4havipClient, _ := havip.NewClient(AK, SK, ENDPOINT)

Configure the HAVIP client

If users need to configure specific parameters for the HAVIP Client, they can customize the configuration using the exported Config field of the HAVIP Client object after its creation. This allows for configuring parameters such as proxy and maximum number of connections for the client.

Use a proxy

The following code snippet enables the client to access HAVIP service using a proxy:

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2 // Create an HAVIP Client object
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4ENDPOINT := "bcc.bj.baidubce.com"
5client, _ := havip.NewClient(AK, SK, ENDPOINT)
6 // Use the local port 8080 for the proxy
7client.Config.ProxyUrl = "127.0.0.1:8080"

Set network parameters

Users can configure network parameters using the following example code:

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3ENDPOINT := "bcc.bj.baidubce.com"
4client, _ := havip.NewClient(AK, SK, ENDPOINT)
5 // Configure to not retry, default: Back Off retry
6client.Config.Retry = bce.NewNoRetryPolicy()
7 // Configure connection timeout to 30 seconds
8client.Config.ConnectionTimeoutInMillis = 30 * 1000

Configure options for generating signature strings

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3ENDPOINT := "bcc.bj.baidubce.com"
4client, _ := havip.NewClient(AK, SK, ENDPOINT)
5 // Configure the HTTP request header Host for signing
6headersToSign := map[string]struct{}{"Host": struct{}{}}
7client.Config.SignOption.HeadersToSign = HeadersToSign
8 // Configure the validity period of the signature to 30 seconds
9client.Config.SignOption.ExpireSeconds = 30

Parameter description

When using the GO SDK to access HAVIP, the Config field of the created HAVIP Client object supports the following parameters, as shown in the table below:

ConfigMap name	Types	Meaning
Endpoint	string	Domain name for service requests
ProxyUrl	string	The proxy address for client requests
Region	string	Region for resource requests
UserAgent	string	User name, HTTP request’s User-Agent header
Credentials	*auth.BceCredentials	Authentication object for requests, divided into regular AK/SK and STS
SignOption	*auth.SignOptions	Options for authentication string signing
Retry	RetryPolicy	Retry policy for connections
ConnectionTimeoutInMillis	int	Connection timeout, in milliseconds, defaulting to 20 minutes

Description:

The Credentials is created using the auth.NewBceCredentials and auth.NewSessionBceCredentials functions. The former is used by default, while the latter is used for STS certification. See "Create a HAVIP client with STS" for details.
The SignOption field represents options when generating a signature string, as detailed in the table below:

Name	Types	Meaning
HeadersToSign	map[string]struct{}	HTTP headers used when generating the signature string
Timestamp	int64	Timestamp used in the generated signature string, defaulting to the value at the time of sending request
ExpireSeconds	int	Validity period of the signature string

Plain Text

1 Among configuration options, HeadersToSign defaults to `Host`, `Content-Type`, `Content-Length` and `Content-MD5`; TimeStamp is typically set to zero, indicating that the timestamp at the time of generating the certification string shall be used, and users generally shall not explicitly specify the value for this field; ExpireSeconds defaults to 1,800 seconds or 30 minutes.

The Retry field specifies the retry policy, currently supporting two types: NoRetryPolicy and BackOffRetryPolicy. By default, the latter is used. This retry policy specifies the maximum number of retries, the maximum retry duration, and the retry base. Retries increase exponentially based on the retry base multiplied by 2 until the maximum number of retries or the maximum retry duration is reached.

Acquire public services

Use the following code to acquire public services

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2result, err := client.GetServices()
3    if err != nil {
4        fmt.Printf("list public services error: %+v\n", err)
5        return
6    }
7r, err := json.Marshal(result)
8fmt.Println(string(r))

Create HAVIP

The following code demonstrates how to request an HAVIP.

Function declaration

1type CreateHaVipArgs struct {
2	ClientToken      string `json:"-"`
3	SubnetId         string `json:"subnetId"`
4	Name             string `json:"name"`
5	PrivateIpAddress string `json:"privateIpAddress"`
6	Description      string `json:"description"`
7}
8type CreateHavipResult struct {
9	HaVipId string `json:"haVipId"`
10}
11func (c *Client) CreateHaVip(args *CreateHaVipArgs) (*CreateHavipResult, error) {}

Parameter meaning

Please refer to the OpenAPI documentation Parameters for Creating High-availability Virtual IP Address

Response value

Operation succeeded

Plain Text

1{
2 "metadata": For details, refer to the metadata section in the appendix,
3    "haVipId":"havip-w2d4kgc3x0y1"
4}

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_create_havip.go

Query HAVIP list

The following code shows how to query the HAVIP list.

Function declaration

1type ListHaVipArgs struct {
2	VpcId   string
3	Marker  string
4	MaxKeys int
5}
6type ListHaVipResult struct {
7	HaVips      []HaVip `json:"haVips"`
8	Marker      string  `json:"marker"`
9	IsTruncated bool    `json:"isTruncated"`
10	NextMarker  string  `json:"nextMarker"`
11	MaxKeys     int     `json:"maxKeys"`
12}
13func (c *Client) ListHaVip(args *ListHaVipArgs) (*ListHaVipResult, error) {}

Parameter meaning

Please refer to the OpenAPI documentation: Parameters for Querying High-availability Virtual IP Address List

Response value

Operation succeeded

Plain Text

1{
2    "haVips":[
3        {
4            "haVipId":"havip-jshdu47sk",
5            "name":"test_havip",
6            "description":"",
7            "vpcId":"vpc-r625rqw3wuer",
8            "subnetId":"sbn-i4d47zb73ztx",
9            "status":"available",
10            "privateIpAddress":"192.168.1.221",
11            "publicIpAddress":"180.76.245.166",
12            "createdTime":"2022-08-31T11:42:19Z"
13        },
14        {
15            "haVipId":"havip-jshdu47sk",
16            "name":"test_havip",
17            "description":"",
18            "vpcId":"vpc-r625rqw3wuer",
19            "subnetId":"sbn-i4d47zb73ztx",
20            "status":"available",
21            "privateIpAddress":"192.168.1.221",
22            "publicIpAddress":"180.76.245.166",
23            "createdTime":"2022-08-31T11:42:19Z"
24        },
25        
26    ],
27    is_truncated:False,
28    max_keys:1000,
29    marker:,
30 metadata: For details, refer to the metadata section in the appendix
31}

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer toexample_list_havip.go

Query HAVIP details

The following code illustrates how to query HAVIP details.

Function declaration

1type HaVip struct {
2	HaVipId          string                `json:"haVipId"`
3	Name             string                `json:"name"`
4	Description      string                `json:"description"`
5	VpcId            string                `json:"vpcId"`
6	SubnetId         string                `json:"subnetId"`
7	Status           string                `json:"status"`
8	PrivateIpAddress string                `json:"privateIpAddress"`
9	PublicIpAddress  string                `json:"publicIpAddress,omitempty"`
10	BindedInstances  []HaVipBindedInstance `json:"bindedInstances,omitempty"`
11	CreatedTime      string                `json:"createdTime"`
12}
13func (c *Client) GetHaVipDetail(haVipId string) (*HaVip, error) {}

Parameter meaning

Please refer to the OpenAPI documentation: Parameters for Querying Specified High-availability Virtual IP Address

Response value

Operation succeeded

Plain Text

1{
2    "haVipId": "havip-jshdu47sk",
3    "name": "test_havip",
4    "description": "",
5    "vpcId": "vpc-r625rqw3wuer",
6    "subnetId": "sbn-i4d47zb73ztx",
7    "status": "available",
8    "privateIpAddress": "192.168.1.221",
9    "publicIpAddress": "180.76.245.166",
10    "createdTime": "2022-08-31T11:42:19Z",
11    "bindedInstances": [
12        {
13            "instanceId": "eni-w2kmnu1peqxg",
14            "instanceType": "ENI",
15            "master": true
16        },
17        {
18            "instanceId": "eni-7c9yzhkfn9c2",
19            "instanceType": "ENI",
20            "master": false
21        }
22    ],
23 "metadata": For details, refer to the metadata section in the appendix
24}

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_get_havip_detail.go

Update HAVIP

The following code can be used to update HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type UpdateHaVipArgs struct {
3	HaVipId     string `json:"-"`
4	ClientToken string `json:"-"`
5	Name        string `json:"name"`
6	Description string `json:"description,omitempty"`
7}
8func (c *Client) UpdateHaVip(args *UpdateHaVipArgs) error {}

Parameter meaning

Please refer to the OpenAPI documentation Parameters for Updating High-availability Virtual IP Address

Response value

Operation succeeded

No response value
Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_update_havip.go

Delete HAVIP

Use the code below to release the specified HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type DeleteHaVipArgs struct {
3	HaVipId     string
4	ClientToken string
5}
6func (c *Client) DeleteHaVip(args *DeleteHaVipArgs) error {}

Parameter meaning

Please refer to the OpenAPI documentation: Parameters for Deleting High-availability Virtual IP Address

Response value

Operation succeeded

No response value
Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer toexample_delete_havip.go

Note:

Delete specified HAVIP; released HAVIP can nor be recovered

Bind instance to HAVIP

Use the code below to bind an instance to HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type HaVipInstanceArgs struct {
3	HaVipId      string   `json:"-"`
4	InstanceIds  []string `json:"instanceIds"`
5	InstanceType string   `json:"instanceType"`
6	ClientToken  string   `json:"-"`
7}
8func (c *Client) HaVipAttachInstance(args *HaVipInstanceArgs) error {}

Parameter meaning

Refer to OpenAPI documentation: Parameters for Binding Instance for High-availability Virtual IP Address

Response value

Operation succeeded

No response value
Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_havip_attach_instance.go

Unbind instance from HAVIP

Use the code below to unbind an instance from HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type HaVipInstanceArgs struct {
3	HaVipId      string   `json:"-"`
4	InstanceIds  []string `json:"instanceIds"`
5	InstanceType string   `json:"instanceType"`
6	ClientToken  string   `json:"-"`
7}
8func (c *Client) HaVipDetachInstance(args *HaVipInstanceArgs) error {}

Parameter meaning

Refer to OpenAPI documentation: Parameters for Unbinding Instance from High-availability Virtual IP Address

Response value

Operation succeeded

No response value

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_havip_detach_instance.go

Bind public IP to HAVIP

Use the code below to bind a public IP to a HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type HaVipBindPublicIpArgs struct {
3	HaVipId         string `json:"-"`
4	ClientToken     string `json:"-"`
5	PublicIpAddress string `json:"publicIpAddress"`
6}
7func (c *Client) HaVipBindPublicIp(args *HaVipBindPublicIpArgs) error {}

Parameter meaning

Refer to OpenAPI documentation: Parameters for Binding EIP to High-availability Virtual IP Address

Response value

Operation succeeded

No response value

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_havip_bind_public_ip.go

Unbind public IP from HAVIP

Use the code below to unbind a public IP from a HAVIP.

Function declaration

1// import "github.com/baidubce/bce-sdk-go/services/havip"
2type HaVipUnbindPublicIpArgs struct {
3	HaVipId     string
4	ClientToken string
5}
6func (c *Client) HaVipUnbindPublicIp(args *HaVipUnbindPublicIpArgs) error {}

Parameter meaning

Refer to OpenAPI documentation: Parameters for Unbinding EIP from High-availability Virtual IP Address

Response value

Operation succeeded

No response value

Operation failed

For response exception list of operation failure, refer to the Exception List.

Code example

For specific code examples, refer to example_havip_unbind_public_ip.go

Error handling

The Go language uses the error type to identify errors. HAVIP supports two types of errors as shown in the table below:

Error type	Description
BceClientError	Errors caused by user operations
BceServiceError	Errors returned by the HAVIP service

When users call HAVIP-related APIs through the SDK, the system not only returns the required results but also provides error information. Users can retrieve and handle these errors. An example is as follows:

Plain Text

1// havipClient is the created HAVIP Client object
2args := &havip.ListHaVipArgs{}
3result, err := client.ListHaVip(args)
4if err != nil {
5  switch realErr := err.(type) {
6  case *bce.BceClientError:
7    fmt.Println("client occurs error:", realErr.Error())
8  case *bce.BceServiceError:
9    fmt.Println("service occurs error:", realErr.Error())
10  default:
11    fmt.Println("unknown error:", err)
12  }
13}

Client exception

A client exception arises when the client faces issues while sending requests or transmitting data to HAVIP. For instance, if the network connection is unavailable during a request, a BceClientError will be returned.

Server exception

A server exception is generated when HAVIP server-side errors occur. The service returns detailed error messages to assist troubleshooting. For common server exceptions, refer to HAVIP Error Code

SDK logging

The HAVIP GO SDK has a logging module that supports six levels, three output destinations (standard output, standard error, file), and basic format settings. Its import path is github.com/baidubce/bce-sdk-go/util/log. When outputting to a file, it supports setting five log rolling modes (no rolling, rolling by day, rolling by hour, rolling by minute, rolling by size). In this case, the directory for output log files also needs to be set.

Default logging

The HAVIP GO SDK itself uses a package-level global log object, which does not record logs by default. If Users need to output SDK-related logs, users must specify the output method and level by themselves. See the following examples for details:

Plain Text

1// import "github.com/baidubce/bce-sdk-go/util/log"
2 // Specify output to standard error, output INFO and above levels
3log.SetLogHandler(log.STDERR)
4log.SetLogLevel(log.INFO)
5 // Specify output to standard error and file, DEBUG and above levels, rolling by 1 GB file size
6log.SetLogHandler(log.STDERR | log.FILE)
7log.SetLogDir("/tmp/gosdk-log")
8log.SetRotateType(log.ROTATE_SIZE)
9log.SetRotateSize(1 << 30)
10 // Output to standard output, only output level and log message
11log.SetLogHandler(log.STDOUT)
12log.SetLogFormat([]string{log.FMT_LEVEL, log.FMT_MSG})

Description:

The default log output level is DEBUG
If set to output to a file, the default log output directory is /tmp, and it rolls by hour by default
If set to output to a file and roll by size, the default rolling size is 1 GB
The default log output format is: FMT_LEVEL, FMT_LTIME, FMT_LOCATION, FMT_MSG

Project usage

This logging module has no external dependencies. When users develop projects using the GO SDK, they can directly reference this logging module for use in their projects. Users can continue to use the package-level log object used by the GO SDK or create new log objects. See the following examples for details:

Plain Text

1// Directly use the package-level global log object (will be output together with the GO SDK’s own logs)
2log.SetLogHandler(log.STDERR)
3log.Debugf("%s", "logging message using the log package in the HAVIP go sdk")
4 // Create a new log object (output logs according to custom settings, separated from the GO SDK’s log output)
5myLogger := log.NewLogger()
6myLogger.SetLogHandler(log.FILE)
7myLogger.SetLogDir("/home/log")
8myLogger.SetRotateType(log.ROTATE_SIZE)
9myLogger.Info("this is my own logger from the HAVIP go sdk")

Exception handling

Initialization

VPC VPC

VPC VPC

High-availability virtual IP address (HAVIP)

Initialization

Confirm Endpoint

Retrieve access key

Create a new HAVIP client

Create a new HAVIP client with AK/SK

Create a HAVIP client with STS

Configure HTTPS access to HAVIP

Configure the HAVIP client

Use a proxy

Set network parameters

Configure options for generating signature strings

Acquire public services

Create HAVIP

Query HAVIP list

Query HAVIP details

Update HAVIP

Delete HAVIP

Bind instance to HAVIP

Unbind instance from HAVIP

Bind public IP to HAVIP

Unbind public IP from HAVIP

Error handling

Client exception

Server exception

SDK logging

Default logging

Project usage