Obtaining a Cluster Access Certificate

Function

This API is used to obtain the access certificate of a cluster.

Constraints

This API is applicable to clusters of v1.13 and later.

Calling Method

For details, see Calling APIs.

URI

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/clustercert

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Details: Project ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Constraints: None Options: Project IDs of the account Default value: N/A
cluster_id	Yes	String	Details: Cluster ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Constraints: None Options: Cluster IDs Default value: N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Definition: Type (or format) of the request body. The default value is application/json. Other values of this field will be provided for specific APIs, if any. Constraints: GET requests are not validated. Range: N/A Default Value: N/A
X-Auth-Token	Yes	String	Details: Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details, see Obtaining a User Token. Constraints: None Options: N/A Default value: N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
duration	No	Integer	Definition Validity period of a cluster certificate. Constraints Either duration or expire_at must be specified. If both parameters are specified, the expire_at parameter is used. Range The minimum value is 1 day, and the maximum value is 1827 days (5 years). If there is one leap year within the five-year period, the maximum value is 1826 days. If the value is -1, it indicates 5 years. Default Value N/A
expire_at	No	String	Definition Expiration time of a cluster certificate. Constraints Either duration or expire_at must be specified. If both parameters are specified, the expire_at parameter is used. Range The certificate expiration time must be 15 minutes to 5 years later than the current time. An example is 2025-01-01 16:00:00 +0000 UTC. Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response header parameters
Parameter	Type	Description
Port-ID	String	Definition Port ID of the cluster control plane node Constraints N/A Range N/A Default Value N/A

**Table 5** Response body parameters
Parameter	Type	Description
kind	String	Definition API type Range N/A
apiVersion	String	Definition API version Range N/A
preferences	Object	Definition This field is not in use. Range N/A
clusters	Array of Clusters objects	Definition Cluster list
users	Array of Users objects	Definition Certificate information and client key information of a specified user
contexts	Array of Contexts objects	Definition Context list
current-context	String	Definition Current context Range external: public network access internal: private network access publicIp (a VM's EIP) is present, the value is external. If publicIp is not present, the value is internal.

**Table 6** Clusters
Parameter	Type	Description
name	String	Definition Cluster name Range internalCluster: a cluster that can be accessed through a private network externalCluster: a cluster that can be accessed through the public network publicIp (a VM's EIP) is not present, there is only one cluster in the cluster list, and the value of this parameter is internalCluster. If publicIp is present, there are more than one cluster in the cluster list, and the value of name of all extended clusters is externalCluster.
cluster	ClusterCert object	Definition Cluster information

**Table 7** ClusterCert
Parameter	Type	Description
server	String	Definition Server address Range N/A
certificate-authority-data	String	Definition Certificate authorization data Range N/A
insecure-skip-tls-verify	Boolean	Definition Whether to skip server certificate verification. Range true: Server certificate verification is skipped. false: The server certificate is verified. externalCluster, the value is true.

**Table 8** Users
Parameter	Type	Description
name	String	Definition Name Range N/A
user	User object	Definition Certificate information and client key information of a specified user

**Table 9** User
Parameter	Type	Description
client-certificate-data	String	Definition Client certificate Range N/A
client-key-data	String	Definition PEM encoding data from the TLS client key file Range N/A

**Table 10** Contexts
Parameter	Type	Description
name	String	Definition Context name Range internal: private network access external: public network access publicIp (a VM's EIP) is not present, there is only one cluster in the cluster list, and the value of this parameter is internal. If publicIp is present, there are more than one cluster in the cluster list, and the value of name of all extended contexts is external.
context	Context object	Definition Context

**Table 11** Context
Parameter	Type	Description
cluster	String	Definition Cluster context Range N/A
user	String	Definition User context Range N/A

Example Requests

Apply for a cluster access certificate that is valid until 16:00 (UTC) on January 1, 2025.

{
  "expire_at" : "2025-01-01 16:00:00 +0000 UTC"
}

Example Responses

Status code: 200

{
  "kind" : "Config",
  "apiVersion" : "v1",
  "preferences" : { },
  "clusters" : [ {
    "name" : "internalCluster",
    "cluster" : {
      "server" : "https://192.168.1.7:5443",
      "certificate-authority-data" : "Q2VydGlmaWNhdGU6******FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
    }
  } ],
  "users" : [ {
    "name" : "user",
    "user" : {
      "client-certificate-data" : "LS0tLS1CRUdJTiBDR******QVRFLS0tLS0K",
      "client-key-data" : "LS0tLS1CRUdJTi******BLRVktLS0tLQo="
    }
  } ],
  "contexts" : [ {
    "name" : "internal",
    "context" : {
      "cluster" : "internalCluster",
      "user" : "user"
    }
  } ],
  "current-context" : "internal"
}

Status Codes

Status Code	Description
200	The certificate of the specified cluster is successfully obtained. For details about the certificate file format, see the Kubernetes v1.Config structure.

Error Codes

See Error Codes.

Parent topic: Cluster Management

Previous topic: Waking Up a Cluster

Next topic: Revoking a Cluster Access Certificate