GetCluster - Key Management Service - Alibaba Cloud Documentation Center

Retrieves the details of a specified cluster.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-hsm:GetCluster

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
ClusterId	string	Yes	The cluster ID.	cluster-p94y1dud9ts****

Response elements

Element	Type	Description	Example
	object	PlainResult
RequestId	string	The ID of the request. Alibaba Cloud generates a unique ID for each request. You can use this ID to troubleshoot issues.	4C467B38-3910-447D-87BC-AC049166F216
Cluster	object	The cluster information.
ClusterId	string	The cluster ID.	cluster-p94y1dud9ts****
ClusterName	string	The name of the cluster.	cluster_polar_****
Status	string	The status of the cluster. NEW: Not initialized INITIALIZED: Initialized DELETED: Deleted SYNCHRONIZING: Synchronizing TO_DELETE: To be deleted	NEW
CreateTime	integer	The time when the cluster was created. This value is a UNIX timestamp in milliseconds.	1641275680000
RegionId	string	The ID of the region where the cluster resides.	cn-hangzhou
VpcId	string	The ID of the VPC to which the cluster belongs.	vpc-8vbt0fjdm29hofvbo****
Whitelist	string	The access whitelist of the cluster.	130.176.XX.XX
Zones	array<object>	The list of zones for the cluster.
	object	A zone.
VSwitchId	string	The vSwitch ID.	vsw-uf61s651p69bdgmki****
ZoneId	string	The zone ID.	cn-hangzhou-j
DeviceType	string	The device type.	jnta
ClusterCsr	string	The certificate signing request for the cluster.	-----BEGIN CERTIFICATE REQUEST-----\nMIIC5TCCAc0CAQAwgZ8xWTAJBgNVBAYTAlVTMAkGA1UECAwCQ0EwDQYDVQQKDAZD\nYXZpdW0wDQYDVQQLDAZOM0ZJUFMwDgYDVQQHDAdTYW5Kb3NlMBMGA1UdEQwMMTk**** -----END CERTIFICATE REQUEST-----
ClusterCertificate	string	The cluster certificate.	-----BEGIN CERTIFICATE----- MIIDfTCCAmWgAwIBAgIJAMRqQMr5if66MA0GCSqGSIb3DQEBCwUAMFUxCzAJBgNV BAYTAmNuMQswCQYDVQQIDAJ6ajELMAkGA1UEBwwCaHoxFjAUBgNVBAoMDUFsaWJh YmEgQ2xvdWQxFDA**** -----END CERTIFICATE-----
ClusterOwnerCertificate	string	The self-signed certificate of the cluster.	----BEGIN CERTIFICATE----- MIIDaTCCAlECAQEwDQYJKoZIhvcNAQELBQAwVTELMAkGA1UEBhMCY24xCzAJBgNV BAgMAnpqMQswCQYDVQQHDAJoejEWMBQGA1UECgwNQWxpYmFiYSBDbG91ZDEUMBIG A1UECwwLU2VjQ2xvdWRIc20wHhcNMjQwNzAzM**** -----END CERTIFICATE-----
Size	integer	The number of instances in the cluster.	2
Instances	array<object>	The list of cluster instances.
	object	The HSM instance information.
InstanceId	string	The ID of the HSM instance.	hsm-cn-g6z3v0uf****
NodeId	integer	The number of the HSM instance in the cluster.	1
Master	boolean	Indicates whether the instance is the master HSM. true: Yes false: No	true
ClusterMode	integer	The cluster mode. 2: Automatic synchronization cluster.	2
EntityCertExpireTime	string	The expiration time of the managed cluster certificate. This is a UNIX timestamp in milliseconds. This parameter is returned only when CertManaged is true.	1641275680000
CertManaged	boolean	Indicates whether the cluster certificate is managed. true: Managed false: Not managed	true

Examples

Success response

JSON format

{
  "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  "Cluster": {
    "ClusterId": "cluster-p94y1dud9ts****",
    "ClusterName": "cluster_polar_****",
    "Status": "NEW",
    "CreateTime": 1641275680000,
    "RegionId": "cn-hangzhou",
    "VpcId": "vpc-8vbt0fjdm29hofvbo****",
    "Whitelist": "130.176.XX.XX",
    "Zones": [
      {
        "VSwitchId": "vsw-uf61s651p69bdgmki****",
        "ZoneId": "cn-hangzhou-j"
      }
    ],
    "DeviceType": "jnta",
    "ClusterCsr": "-----BEGIN CERTIFICATE REQUEST-----\\nMIIC5TCCAc0CAQAwgZ8xWTAJBgNVBAYTAlVTMAkGA1UECAwCQ0EwDQYDVQQKDAZD\\nYXZpdW0wDQYDVQQLDAZOM0ZJUFMwDgYDVQQHDAdTYW5Kb3NlMBMGA1UdEQwMMTk****\n-----END CERTIFICATE REQUEST-----",
    "ClusterCertificate": "-----BEGIN CERTIFICATE-----\nMIIDfTCCAmWgAwIBAgIJAMRqQMr5if66MA0GCSqGSIb3DQEBCwUAMFUxCzAJBgNV\nBAYTAmNuMQswCQYDVQQIDAJ6ajELMAkGA1UEBwwCaHoxFjAUBgNVBAoMDUFsaWJh\nYmEgQ2xvdWQxFDA****\n-----END CERTIFICATE-----",
    "ClusterOwnerCertificate": "----BEGIN CERTIFICATE-----\nMIIDaTCCAlECAQEwDQYJKoZIhvcNAQELBQAwVTELMAkGA1UEBhMCY24xCzAJBgNV\nBAgMAnpqMQswCQYDVQQHDAJoejEWMBQGA1UECgwNQWxpYmFiYSBDbG91ZDEUMBIG\nA1UECwwLU2VjQ2xvdWRIc20wHhcNMjQwNzAzM****\n-----END CERTIFICATE-----",
    "Size": 2,
    "Instances": [
      {
        "InstanceId": "hsm-cn-g6z3v0uf****",
        "NodeId": 1,
        "Master": true
      }
    ],
    "ClusterMode": 2,
    "EntityCertExpireTime": "1641275680000",
    "CertManaged": true
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	SwitchMaster.InstanceInvalid	Instance not in the cluster.
400	LeaveCluster.MasterLast	Master instance can not leave a cluster until all other instances are left.
400	Certificate.ChainInvalid	Certificate chain invalid. Please make sure issuer certificate is the trust anchor and cluster certificate is signed by issuer certificate.
400	Certificate.FormatInvalid	Certificate format invalid. Cluster/Issuer certificate must be in PEM format.
400	ConfigClusterSubnet.DuplicateZone	VSwitches should not contain duplicate zones.
400	InvalidApiParam.Error	api param is invalid
400	InvalidClusterName	Invalid parameter clusterName.
400	InvalidPageSize	Invalid parameter pageSize.
400	InvalidCurrentPage	Invalid parameter currentPage.
400	InvalidRegionId	Invalid parameter regionId.
400	InvalidVSwitch	Invalid parameter vSwitch.
400	InvalidVpc	Invalid parameter vpcId.
400	InvalidIp	Invalid parameter IP.
400	InvalidAliuid	Invalid parameter aliuid.
400	InvalidClusterId	Invalid parameter clusterId.
400	InvalidInstanceId	Invalid parameter instanceId.
400	InvalidBackupId	Invalid parameter backupId.
400	InvalidImageId	Invalid parameter imageId.
400	HsmInstanceNotExist.Error	hsm instance not exist
400	HSMIntanceNotActived.Error	hsm intance is not actived
400	WhiteListMaxCount.Error	whilte list is more than max count
400	ClusterIdIsNotExists.Error	cluster ID non-exists
400	InstanceListIsEmpty.Error	instance list is empty
400	InstanceIdIsEmpty.Error	instance id is empty
400	InstanceIsNotExistsInCluster.Error	cluster has no such instance
400	InstanceIsExistsInCluster.Error	instance already in the cluster
400	RegionNoEmpty.Error	region no. is empty
400	ClusterNameEmpty.Error	empty cluster name not allowed
400	ClusterNameIsExists.Error	the cluster name is already taken
400	IpNotValid.Error	ip not valid
400	ClusterIsEmpty.Error	cluster is empty
400	NoMasterFoundInCluster.Error	cluster has no master instance
400	HsmInstanceIdNotFound.Error	no such instance
400	NoInstanceFoundInCluster.Error	cluster is empty
400	Whitelist.Invalid	Whitelist blocks not in CIDR format.
400	Whitelist.TooLong	Whitelist too long, exceeds 10 CIDR blocks.
500	ConfigWhitelistFailed.Error	config white list error
500	ActionFailed.Error	internal error, please try again
500	InternalError	The request processing has failed due to some unknown error.	Unknown error caused request processing to fail.
403	NoPermission	Caller has no permission on the resource.
403	InstanceNotPaused	Please pause the instance before reset.
403	InstanceNotActive	Instance is not active.
403	ConfigIp.IncorrectState	Instance not in pending or active state, can not config IP address.
403	SwitchMaster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	SyncCluster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	LeaveCluster.InstanceInvalid	The instance is not in the cluster.
403	DeleteCluster.IncorrectState	Cluster not empty, please remove all instances first.
403	JoinCluster.InstanceVSwitchNotInCluster	Instance's vSwitch is not in cluster config, please change instance's vSwitch first.
403	JoinCluster.InstanceInitialized	Initialized instance can not join a cluster.
403	JoinCluster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	InitializeCluster.InstanceNotInitialized	Cluster master instance not initialized, please initialize cluster master instance first.
403	InitializeCluster.IncorrectConfig	Cluster subnet not configured, please config cluster subnet first.
403	InitializeCluster.IncorrectState	Cluster initialized, do not re-initialize.
403	Cluster.CN.ActionForbidden	This API is forbidden for non-international site cluster.
403	Cluster.INTL.ActionForbidden	This API is forbidden for international site cluster.
403	ConfigClusterCertificate.IncorrectState	Cluster initialized or certificates already configured.
403	ConfigClusterSubnet.InvalidVpcId	VPC Id invalid. Cluster VPC is the same as cluster master's VPC.
403	ConfigClusterSubnet.InvalidVSwitchId	VSwitch Id invalid. VSwitches should contain all current cluster vSwitches.
403	ConfigClusterSubnet.IncorrectState	Cluster not in NEW state, can not config cluster subnet.
403	ClusterName.Exist	Cluster name already exists, please use another name.
403	Whitelist.InstanceInCluster	Whitelist.InstanceInCluster
404	Resource.NotFound	Resource not found.
405	ClusterAPI.NotSupported	ClusterAPI not supported in this region.
409	Conflict	Resource is being updated by a previous request. Current request is redundant.
409	Cluster.Conflict	The cluster is being updated by a previous request. Please try again later.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.