DescribeProxyClusterForInstance - Query ODP clusters associated with an instance|OceanBase Cloud |docs|OceanBase Documentations

DescribeProxyClusterForInstance - Query ODP clusters associated with an instance

Last Updated：2026-09-22 07:23:31 Updated

Overview

This API retrieves details about the OceanBase Database Proxy (ODP) clusters associated with a specified OceanBase Cloud database instance. It returns cluster configurations, status, network addresses, and connections to the tenants in the instance to help you monitor and manage the database proxy layer.

API details

Constraints

You must have an AccessKey to access the OceanBase Cloud API. For information about how to obtain an AccessKey ID and an AccessKey Secret, see Manage AccessKeys.

Request path

GET /api/v2/instances/{instanceId}/proxies

Request parameters

Path

Parameter	Type	Required	Description	Example value
instanceId	String	Yes	OceanBase cluster ID.	obcluster-*****

Query

Parameter	Type	Required	Description	Example value
requestId	String	Yes	Request ID used for tracking.	d04eabba****

Response parameters

Field	Type	Description	Example value
success	Boolean	Whether the request succeeded.	true
errorCode	String	Error code.	INVALID_PARAMETER
errorMessage	String	Error message.	Invalid parameter
data	Object	Response data as an object.	None
cost	Number	Time taken to process the request.	1.0
server	String	Server address, typically an OBServer node IP address.	10.0.0.10
requestId	String	Request ID.	d04eabba****
totalCount	Number	Total number of records.	100.0
extra	Object	Additional information.	{}

`data` object fields

Field	Type	Description	Example value
instanceId	String	OceanBase cluster ID.	obcluster-*****
proxyClusterForTenantResponseMcList	Array	ODP clusters associated with tenants.	[{"tenantName": "pay_core", "tenantId": "t4louaeei****"}]

`data.proxyClusterForTenantResponseMcList[]` object fields

Field	Type	Description	Example value
tenantId	String	Tenant ID.	t4louaeei****
tenantName	String	Tenant name.	xxxxxx
describeTenantConnectionODPForMonitorResponseList	Array	ODP monitoring information associated with tenant endpoints.	[{"tenantName": "pay_core", "tenantId": "t4louaeei****"}]

`data.proxyClusterForTenantResponseMcList[].describeTenantConnectionODPForMonitorResponseList[]` object fields

Field	Type	Description	Example value
tenantId	String	Tenant ID.	t4louaeei****
vpcId	String	VPC ID.	vpc-xxxx****
userVpcOwnerId	String	ID of the account that owns the user's VPC.	20000600****
vSwitchId	String	vSwitch ID.	vsw-xxxx****
connectionZones	Array	Connection zones.	["zone-********-i"]
tenantEndpointId	String	Tenant endpoint ID added in multi-cloud v5.	te-xxxxx****
addressId	String	Address ID, which is the VIP service group name in the multi-cloud environment.	rs-private-internet-*****
addressStatus	String	Connection status.	ONLINE
serviceType	String	Address type.	PRIVATE
addressType	String	Address type: MASTER or READONLY.	MASTER
networkType	String	Network type.	INTRANET
role	String	Connection role: READWRITE or READONLY. A primary address may also need to distinguish between these roles. The primary address of a standby database is read-only.	READWRITE
userNameFormat	String	Username format for this address: one-part or two-part.	TWO_PART
useSSL	Boolean	Whether SSL is enabled.	false
proxyClusterId	String	Dedicated Kubernetes proxy cluster ID.	proxy-12****
proxyClusterInfo	Object	ODP cluster information associated with the tenant connection.	None
proxyClusterInfo.proxyClusterId	String	ODP cluster ID.	proxy-12****
proxyClusterInfo.proxyMode	String	ODP mode.	DEDICATED
proxyClusterInfo.zone	String	Zone.	zone-********-i
proxyClusterInfo.unitSpec	String	Unit specifications.	2C4G
proxyClusterInfo.unitNum	Number	Number of units.	1.0
proxyClusterInfo.sharedUnitNumLimit	Integer	Maximum number of units for the Kubernetes proxy service in shared mode.	3
proxyClusterInfo.exclusiveUnitNumLimit	Integer	Maximum number of units for the Kubernetes proxy service in dedicated mode.	3
proxyClusterInfo.status	String	Current task or resource status.	ONLINE
proxyClusterInfo.proxyServiceVersion	String	Architecture version.	4.2.1.0
proxyClusterInfo.proxyVersion	String	Proxy version.	4.2.1.0
proxyClusterInfo.createTime	String	Creation time in UTC.	2026-02-25T15:40:43+00:00
proxyClusterInfo.expireTime	String	"2020-12-23T04:14:48Z" Expiration time.	2020-12-23T04:14:48+00:00
proxyClusterInfo.deployMode	String	Data replica layout (n/n-n/n-n-n).	1-1-1
proxyClusterInfo.maxUnitNum	Number	Serverless ODP scaling upper limit, as specified by Kubernetes ODPClusterSpec.maxUnitNum.	3.0
proxyClusterInfo.slaveZone	String	Standby node zone, added with ODP commercialization. Returned only for primary-standby deployments across two or three zones.	zone-********-i
proxyClusterInfo.nodeDistribution	String	Node distribution, added with ODP commercialization to replace deployMode.	zone-******-i:1,zone-******-j:1
proxyClusterInfo.nodeCpu	Number	Node specifications, added with ODP commercialization to replace unitSpec * unitNum.	4.0
proxyClusterInfo.nodeNum	Integer	Number of nodes, added with ODP commercialization.	3
proxyClusterInfo.deploymentArchitecture	String	Deployment architecture, added with ODP commercialization. Existing ODP clusters that have not been commercialized return SINGLE_AZ_DEPLOYMENT, DUAL_AZ_DEPLOYMENT, or MULTI_AZ_DEPLOYMENT.	SINGLE_ZONE
proxyClusterInfo.proxyServerIds	Array	ODP node IDs.	["resource-123456"]
proxyClusterInfo.enableArchitectureUpgrade	Boolean	Whether architecture upgrade is enabled.	true
odpVersion	String	ODP version.	4.2.1
readStrategyConfigResponse	Object	Read traffic strategy configuration for the tenant endpoint.	None
readStrategyConfigResponse.odpVersion	String	ODP version.	4.2.1
readStrategyConfigResponse.trafficStrategy	String	Traffic strategy.	ZONE_FIRST
readStrategyConfigResponse.replicaParams	Array	Selected replicas.	None
readStrategyConfigResponse.disasterRecoveryReplicaParams	Array	Disaster recovery replicas.	None
readStrategyConfigResponse.balancedStrategy	String	Load balancing strategy.	BALANCED
readStrategyConfigResponse.disasterRecoveryStrategy	String	Disaster recovery strategy. Queries are automatically routed to the primary replica when replicas are unavailable.	PRIMARY_FIRST
deleteSingleTunnelAddress	Boolean	Whether the primary private address on Alibaba Cloud can be deleted.	true
internetAddress	String	Public address.	8.8.8.8
internetPort	Integer	Public port.	2881
internetDomain	String	Public address.	pay-core-public.oceanbase.example.com
internetAddressStatus	String	Public address status.	ONLINE
internetMaxConnectionNum	Integer	Maximum number of public network connections.	10000
enableUpdateMaxConnectionNum	Boolean	Whether the maximum number of public network connections can be changed.	true
internetMaxConnectionNumLimit	Integer	Upper limit for the maximum number of public network connections.	20000
internetRpcPort	Integer	Public RPC port.	2882
internetProxyClusterId	String	Public network proxy cluster ID.	proxy-12****
intranetAddress	String	Private address.	10.0.0.10
intranetPort	Integer	Private port.	2881
intranetDomain	String	Private address.	pay-core-private.oceanbase.example.com
intranetAddressStatus	String	Private address status.	ONLINE
maxConnectionNum	Integer	Maximum number of private network connections.	10000
maxConnectionNumLimit	Integer	Upper limit when changing the maximum number of private network connections.	20000
intranetRpcPort	Integer	Private RPC port.	2882
enableRPc	Boolean	Whether RPC is enabled for Direct Load.	true
intranetAddressMasterZoneId	String	Primary zone ID.	zone-********
intranetAddressSlaveZoneId	String	Standby zone ID.	zone-********
intranetProxyClusterId	String	Private network proxy cluster ID.	proxy-12****
privateLinkList	Array	PrivateLink connections.	[{"id": "resource-123456"}]
intranetPeeringAddress	String	Peering address.	10.1.0.10
intranetPeeringPort	Integer	Peering address port.	2881
intranetPeeringDomain	String	Peering address domain name.	pay-core-peering.oceanbase.example.com
intranetPeeringAddressStatus	String	Peering address status.	ONLINE
intranetPeeringMaxConnectionNum	Integer	Maximum number of connections to the peering address.	10000
peeringDstVpcId	String	Peer VPC ID.	vpc-peer****
peeringDstCidrList	String	Peer CIDR block.	10.1.0.0****
peeringId	String	Peering connection ID.	pcx-xxxx****
intranetPeeringProxyClusterId	String	Proxy cluster ID for the private peering address.	proxy-12****
proxyServerList	Array	Node information.	[{"id": "resource-123456"}]

`data.proxyClusterForTenantResponseMcList[].describeTenantConnectionODPForMonitorResponseList[].connectionZones[]` elements

Field	Type	Description	Example value
data.proxyClusterForTenantResponseMcList[].describeTenantConnectionODPForMonitorResponseList[].connectionZones[]	String	Connection zone.	None

`data.proxyClusterForTenantResponseMcList[].describeTenantConnectionODPForMonitorResponseList[].privateLinkList[]` object fields

Field	Type	Description	Example value
privateLinkStatus	String	PrivateLink activation status.	ONLINE
privateLinkServiceId	String	PrivateLink service ID.	resource****
privateLinkEndpointId	String	PrivateLink endpoint ID.	resource****
privateLinkEndpointVpcId	String	ID of the VPC that contains the PrivateLink endpoint.	vpc-xxxx****
privateLinkEndpointSubnetId	String	Subnet ID of the PrivateLink endpoint.	resource****
privateLinkServiceAccount	String	Primary account for the PrivateLink service.	3
privateLinkUserAccount	String	User account on the PrivateLink allowlist.	3
privateLinkDomain	String	Private domain name.	pay-core.oceanbase.example.com
intranetAddress	String	Private address.	10.0.0.10
intranetDomain	String	Private address.	pay-core-private.oceanbase.example.com
deletePrivateLink	Boolean	Whether the primary private address can be deleted. It cannot be deleted if associated with a global address.	true

`data.proxyClusterForTenantResponseMcList[].describeTenantConnectionODPForMonitorResponseList[].proxyServerList[]` object fields

Field	Type	Description	Example value
proxyServerId	String	ODP node ID.	proxy-12****
proxyServerIp	String	ODP node IP address.	10.0.0.10
spec	String	Specifications.	2C4G
zone	String	Zone.	zone-********-i
version	String	"2.2.52" OceanBase Database version.	2.2.52
status	String	Current task or resource status.	ONLINE
servicePort	Integer	Service port.	2881
diskType	String	"cloud_essd_pl1" \| "ephemeral_ssd" Storage type: ESSD cloud disk \| local SSD.	cloud_essd
diskPl	String	Disk performance level.	200
diskId	String	Disk ID.	xxxxxx
diskSize	String	Disk size.	200
resources	Array	Resources.	[{"id": "resource-123456"}]

Examples

Request example

curl -X GET \
  --digest -u '<Your AccessKey ID:AccessKey Secret>' \
  'https://api-cloud.oceanbase.com/api/v2/instances/{instanceId}/proxies?requestId=d04eabba****'

Response example

JSON format

{
    "success": true,
    "errorCode": null,
    "errorMessage": null,
    "data": {
        "instanceId": "obcluster-*****",
        "proxyClusterForTenantResponseMcList": [
            {
                "tenantName": "xxxxxx",
                "tenantId": "t4louaeei****",
                "describeTenantConnectionODPForMonitorResponseList": [
                    {
                        "tenantName": "pay_core",
                        "tenantId": "t4louaeei****",
                        "vpcId": "vpc-xxxx****",
                        "userVpcOwnerId": "20000600****",
                        "vSwitchId": "vsw-xxxx****",
                        "connectionZones": [
                            "zone-********-i"
                        ],
                        "tenantEndpointId": "te-xxxxx****",
                        "addressId": "rs-private-internet-*****",
                        "addressStatus": "ONLINE",
                        "serviceType": "PRIVATE",
                        "addressType": "MASTER",
                        "networkType": "INTRANET",
                        "role": "READWRITE",
                        "userNameFormat": "TWO_PART",
                        "useSSL": false,
                        "proxyClusterId": "proxy-12****",
                        "proxyClusterInfo": {
                            "proxyClusterId": "proxy-12****",
                            "proxyMode": "DEDICATED",
                            "zone": "zone-********-i",
                            "unitSpec": "2C4G",
                            "unitNum": 1.0,
                            "sharedUnitNumLimit": 3,
                            "exclusiveUnitNumLimit": 3,
                            "status": "ONLINE",
                            "proxyServiceVersion": "4.2.1.0",
                            "proxyVersion": "4.2.1.0",
                            "createTime": "2026-02-25T15:40:43+00:00",
                            "expireTime": "2020-12-23T04:14:48+00:00",
                            "deployMode": "1-1-1",
                            "maxUnitNum": 3.0,
                            "slaveZone": "zone-********-i",
                            "nodeDistribution": "zone-********-i:1,zone-********-j:1",
                            "nodeCpu": 4.0,
                            "nodeNum": 3,
                            "deploymentArchitecture": "SINGLE_ZONE",
                            "proxyServerIds": [
                                "resource-123456"
                            ],
                            "enableArchitectureUpgrade": true
                        },
                        "odpVersion": "4.2.1",
                        "readStrategyConfigResponse": {
                            "odpVersion": "4.2.1",
                            "trafficStrategy": "ZONE_FIRST",
                            "replicaParams": [],
                            "disasterRecoveryReplicaParams": [],
                            "balancedStrategy": "BALANCED",
                            "disasterRecoveryStrategy": "PRIMARY_FIRST"
                        },
                        "deleteSingleTunnelAddress": true,
                        "internetAddress": "xxx.xxx.x.xxx:xxx",
                        "internetPort": 2881,
                        "internetDomain": "pay-core-public.oceanbase.example.com",
                        "internetAddressStatus": "ONLINE",
                        "internetMaxConnectionNum": 10000,
                        "enableUpdateMaxConnectionNum": true,
                        "internetMaxConnectionNumLimit": 20000,
                        "internetRpcPort": 2882,
                        "internetProxyClusterId": "proxy-12****",
                        "intranetAddress": "xxx.xxx.x.xxx:xxx",
                        "intranetPort": 2881,
                        "intranetDomain": "pay-core-private.oceanbase.example.com",
                        "intranetAddressStatus": "ONLINE",
                        "maxConnectionNum": 10000,
                        "maxConnectionNumLimit": 20000,
                        "intranetRpcPort": 2882,
                        "enableRPc": true,
                        "intranetAddressMasterZoneId": "zone-********",
                        "intranetAddressSlaveZoneId": "zone-********",
                        "intranetProxyClusterId": "proxy-12****",
                        "privateLinkList": [
                            {
                                "id": "resource-123456",
                                "privateLinkStatus": "ONLINE",
                                "privateLinkServiceId": "resource****",
                                "privateLinkEndpointId": "resource****",
                                "privateLinkEndpointVpcId": "vpc-xxxx****",
                                "privateLinkEndpointSubnetId": "resource****",
                                "privateLinkServiceAccount": "3",
                                "privateLinkUserAccount": "3",
                                "privateLinkDomain": "pay-core.oceanbase.example.com",
                                "intranetAddress": "xxx.xxx.x.xxx:xxx",
                                "intranetDomain": "pay-core-private.oceanbase.example.com",
                                "deletePrivateLink": true
                            }
                        ],
                        "intranetPeeringAddress": "xxx.xxx.x.xxx:xxx",
                        "intranetPeeringPort": 2881,
                        "intranetPeeringDomain": "pay-core-peering.oceanbase.example.com",
                        "intranetPeeringAddressStatus": "ONLINE",
                        "intranetPeeringMaxConnectionNum": 10000,
                        "peeringDstVpcId": "vpc-peer****",
                        "peeringDstCidrList": "10.1.0.0****",
                        "peeringId": "pcx-xxxx****",
                        "intranetPeeringProxyClusterId": "proxy-12****",
                        "proxyServerList": [
                            {
                                "id": "resource-123456",
                                "proxyServerId": "proxy-12****",
                                "proxyServerIp": "xxx.xxx.x.xxx:xxx",
                                "spec": "2C4G",
                                "zone": "zone-********-i",
                                "version": "2.2.52",
                                "status": "ONLINE",
                                "servicePort": 2881,
                                "diskType": "cloud_essd",
                                "diskPl": "200",
                                "diskId": "xxxxxx",
                                "diskSize": "200",
                                "resources": [
                                    {
                                        "id": "resource-123456"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "cost": 1.0,
    "server": "10.0.0.10",
    "requestId": "d04eabba****",
    "totalCount": 100.0,
    "extra": {}
}

OceanBase

Customer Stories

Documentation