Updated on 2025-08-05 GMT+08:00

Configuring IP Whitelist Groups

Function

This API is used to configure IP address whitelist groups for a specific instance, including creating, disabling, editing, and deleting a whitelist. New whitelist settings will overwrite the existing setting. Therefore, save the existing whitelist before you add a new one.

Calling Method

For details, see Calling APIs.

URI

PUT /v2/{project_id}/instance/{instance_id}/whitelist

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition:

Project ID. For details, see Obtaining a Project ID.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

instance_id

Yes

String

Definition:

Instance ID. It can be viewed on the instance details page on the DCS console.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

instance_id

No

String

Definition:

Instance ID.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

enable_whitelist

Yes

Boolean

Definition:

Whether to enable the whitelist.

Constraints:

N/A

Range:

true: Yes

false: No

Default Value:

N/A

whitelist

Yes

Array of Whitelist objects

Definition:

IP whitelist group. New whitelist settings will overwrite the existing setting. Therefore, save the existing whitelist before you add a new one.

Constraints:

N/A

Table 3 Whitelist

Parameter

Mandatory

Type

Description

group_name

Yes

String

Definition:

Whitelist group name.

Constraints:

Each instance supports four whitelist groups. The group name must be unique, contain more than four characters, and start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed.

Range:

N/A

Default Value:

N/A

ip_list

Yes

Array of strings

Definition:

IP list in a whitelist group. Separate multiple IP addresses or IP address ranges with commas (,).

Constraints:

An instance's IPs must be unique. IP 0.0.0.0 and CIDP are not supported.

Range:

N/A

Default Value:

N/A

Response Parameters

Status code: 204

Definition:

IP whitelist groups configured successfully.

Status code: 400

Table 4 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 401

Table 5 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 500

Table 8 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Example Requests

  • Enabling the whitelist and configuring IP addresses allowed to access the instance

    PUT https://{dcs_endpoint}/v2/{project_id}/instance/{instance_id}/whitelist
    
    {
      "enable_whitelist" : true,
      "whitelist" : [ {
        "group_name" : "test001",
        "ip_list" : [ "10.10.10.1", "10.10.10.2" ]
      } ]
    }
  • Enabling the whitelist and configuring subnet mask allowed to access the instance.

    PUT https://{dcs_endpoint}/v2/{project_id}/instance/{instance_id}/whitelist

Example Responses

None

SDK Sample Code

The SDK sample code is as follows.

Enabling the whitelist and configuring IP addresses allowed to access the instance

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.dcs.v2.region.DcsRegion;
import com.huaweicloud.sdk.dcs.v2.*;
import com.huaweicloud.sdk.dcs.v2.model.*;

import java.util.List;
import java.util.ArrayList;

public class UpdateIpWhitelistSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        DcsClient client = DcsClient.newBuilder()
                .withCredential(auth)
                .withRegion(DcsRegion.valueOf("<YOUR REGION>"))
                .build();
        UpdateIpWhitelistRequest request = new UpdateIpWhitelistRequest();
        request.withInstanceId("{instance_id}");
        ModifyIpWhitelistBody body = new ModifyIpWhitelistBody();
        List<String> listWhitelistIpList = new ArrayList<>();
        listWhitelistIpList.add("10.10.10.1");
        listWhitelistIpList.add("10.10.10.2");
        List<Whitelist> listbodyWhitelist = new ArrayList<>();
        listbodyWhitelist.add(
            new Whitelist()
                .withGroupName("test001")
                .withIpList(listWhitelistIpList)
        );
        body.withWhitelist(listbodyWhitelist);
        body.withEnableWhitelist(true);
        request.withBody(body);
        try {
            UpdateIpWhitelistResponse response = client.updateIpWhitelist(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

Enabling the whitelist and configuring IP addresses allowed to access the instance

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkdcs.v2.region.dcs_region import DcsRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkdcs.v2 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = DcsClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(DcsRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = UpdateIpWhitelistRequest()
        request.instance_id = "{instance_id}"
        listIpListWhitelist = [
            "10.10.10.1",
            "10.10.10.2"
        ]
        listWhitelistbody = [
            Whitelist(
                group_name="test001",
                ip_list=listIpListWhitelist
            )
        ]
        request.body = ModifyIpWhitelistBody(
            whitelist=listWhitelistbody,
            enable_whitelist=True
        )
        response = client.update_ip_whitelist(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

Enabling the whitelist and configuring IP addresses allowed to access the instance

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    dcs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        Build()

    client := dcs.NewDcsClient(
        dcs.DcsClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.UpdateIpWhitelistRequest{}
	request.InstanceId = "{instance_id}"
	var listIpListWhitelist = []string{
        "10.10.10.1",
	    "10.10.10.2",
    }
	var listWhitelistbody = []model.Whitelist{
        {
            GroupName: "test001",
            IpList: listIpListWhitelist,
        },
    }
	request.Body = &model.ModifyIpWhitelistBody{
		Whitelist: listWhitelistbody,
		EnableWhitelist: true,
	}
	response, err := client.UpdateIpWhitelist(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

204

Definition:

IP whitelist groups configured successfully.

400

Definition:

Invalid request.

401

Definition:

Authentication failed.

403

Definition:

Request rejected.

404

Definition:

Incorrect path.

500

Definition:

Internal error.

Error Codes

See Error Codes.