Reading a Specified Cluster

Function

This API is used to obtain details about a specified cluster.

URI

GET /api/v3/projects/{project_id}/clusters/{cluster_id}

Table 1 describes the parameters of this API.

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Project ID. For details about how to obtain the project ID, see How to Obtain Parameters in the API URI.

cluster_id

Yes

Cluster ID. For details about how to obtain the cluster ID, see How to Obtain Parameters in the API URI.

Request

Request parameters:

Table 2 lists the request parameters.

Table 2 Parameters in the request header

Parameter

Mandatory

Description

Content-Type

Yes

Message body type (format). Possible values:

  • application/json;charset=utf-8

  • application/json

X-Auth-Token

Yes

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 on how to obtain a user token, see API Usage Guidelines.

Example request:

N/A

Response

Response parameters:

Table 3 describes the response parameters.

Table 3 Response parameters

Parameter

Type

Description

kind

String

API type. The value is fixed at Cluster and cannot be changed.

apiVersion

String

API version. The value is fixed at v3 and cannot be changed.

metadata

metadata object

Cluster metadata, which is a collection of attributes.

spec

spec object

Detailed description of the cluster targeted by this API. CCE creates or updates objects by defining or updating its spec.

status

status object

Cluster status and jobID of the job that reads a specified cluster.

Table 4 Data structure of the spec field

Parameter

Type

Description

category

String

Cluster category:

  • CCE: CCE cluster

  • Turbo: CCE Turbo cluster

Note

This parameter is valid in cluster of v1.17.17 or higher.

type

String

Cluster type.

VirtualMachine: The master node architecture is x86.

flavor

String

Cluster flavor, which cannot be changed after the cluster is created.

  • cce.s1.small: small-scale, single-master cluster (<= 50 nodes)

  • cce.s1.medium: medium-scale, single-master cluster (<= 200 nodes)

  • cce.s2.small: small-scale, high availability cluster (<= 50 nodes)

  • cce.s2.medium: medium-scale, high availability cluster (<= 200 nodes)

  • cce.s2.large: large-scale, high availability cluster (<= 1,000 nodes)

  • cce.s2.xlarge: ultra-large-scale, high availability cluster (<= 2,000 nodes)

Note

  • s1: single-master cluster

  • s2: high availability cluster

  • For example, <= 50 nodes indicates that the maximum number of nodes that can be managed by the cluster is 50.

  • A single-master cluster has only one master node. If the master node is down, the cluster will become unavailable and stop serving new workloads. However, existing workloads in the cluster are not affected.

  • A high-availability cluster has multiple master nodes. Faults in a single master node will not take the cluster down.

version

String

Cluster's baseline Kubernetes version. The latest version is recommended.

platformVersion

String

Version of the CCE cluster platform, which is for viewing only and cannot be specified during cluster creation. The latest platform version corresponding to the cluster version is automatically selected during cluster creation.

Value format: cce.X.Y

  • X indicates the quarterly or regularly feature version number, starting from 1.

  • Y indicates the patch version of the cluster, starting from 0 (feature version). Other values indicate later patch versions after the feature version is released.

az

String

AZ of the cluster.

ipv6enable

Boolean

Whether the cluster supports IPv6 addresses. This field is supported in clusters of v1.25 and later versions.

supportIstio

String

Reserved. This parameter is not used in the current version.

Note

This field is not supported for the current version.

description

String

Cluster description.

customSan

Array of strings

Custom SAN field in the server certificate of the cluster API server, which must comply with the SSL and X509 format specifications.

  1. Duplicate names are not allowed.

  2. Must comply with the IP address and domain name formats.

example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34

hostNetwork

hostNetwork object

Node network parameters, including a VPC and subnet ID. hostNetwork is mandatory because nodes in a cluster communicate with each other by using a VPC.

containerNetwork

containerNetwork object

Container network parameters, including a container network model and container CIDR block.

eniNetwork

eniNetwork object

Configuration of Cloud Native Network 2.0. Specify this field when creating a CCE Turbo cluster.

publicAccess

PublicAccess object

Cluster API access control.

authentication

authentication object

Configurations of the cluster authentication mode.

billingMode

Integer

Billing mode of a node.

Note

This field is not supported for the current version.

masters

No

MasterSpec objects

Advanced configurations of the master node.

extendParam

extendParam object

Extended fields in the format of key-value pairs.

kubernetesSvcIpRange

String

Service CIDR block or the IP address range which the kubernetes clusterIp must fall within. This parameter is available only for clusters of v1.11.7 and later.

kubeProxyMode

String

Service forwarding mode. Two modes are available:

  • iptables: Traditional kube-proxy uses iptables rules to implement service load balancing. In this mode, too many iptables rules will be generated when many services are deployed. In addition, non-incremental updates will cause a latency and even obvious performance issues in the case of heavy service traffic.

  • ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during service updates. It is suitable for large-sized clusters.

enableMasterVolumeEncryption

Boolean

The system disks and data disks of the master nodes in the cluster are encrypted. By default, the AES-256 encryption algorithm is used. This function is available in both CCE standard and Turbo clusters of v1.25 and later versions. The configuration cannot be modified after the cluster is created. After this function is enabled, there is some disk I/O performance loss.

Table 5 Data structure of the hostNetwork field

Parameter

Type

Description

vpc

String

ID of the VPC used to create a master node. The VPC ID is obtained from Creating a VPC and Subnet.

subnet

String

Network ID of the subnet. The value is obtained from Creating a VPC and Subnet.

SecurityGroup

String

Default worker node security group ID of the cluster. If specified, the cluster will be bound to the target security group. Otherwise, the system will automatically create a default worker node security group for you. The default worker node security group needs to allow access from certain ports to ensure normal communications.

Table 6 Data structure of the containerNetwork field

Parameter

Type

Description

mode

String

Container network model. Select one of the following possible values:

  • overlay_l2: an overlay_l2 network built for containers by using OpenVSwitch (OVS).

  • vpc-router: an underlay_l2 network built for containers by using ipvlan and custom VPC routes.

  • eni: cloud native 2.0 network model. This model deeply integrates the native ENI capability of VPC, uses the VPC CIDR block to allocate container addresses, and supports passthrough between load balancers and containers to provide high performance. You can use this network model when creating a CCE Turbo cluster.

Note

  • Tunnel network: Under this model, the container network is an overlay network on top of a VPC network based on the VXLAN technology. VXLAN encapsulates Ethernet packets as UDP packets for tunnel transmission. Though at some cost of performance, the tunnel encapsulation enables higher interoperability and compatibility with advanced features (such as network policy-based isolation), meeting the requirements of most applications.

  • VPC network: Routing is implemented within a VPC network according to custom VPC routes. Each node is assigned a CIDR block of a fixed size. vpc-router networks are free of tunnel encapsulation overheads and provide better container network performance than tunnel networks. In addition, as routes to node IP addresses and the containers have been configured on vpc-router, container instances can be directly accessed from outside the cluster.

cidr

String

Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing CIDR blocks, the system automatically selects another CIDR block.

This parameter cannot be modified after the cluster is created. Exercise caution when setting this parameter.(This parameter has been discarded. If cidrs has been configured, skip this parameter.)

Minimum: 0

Maximum: 64

cidrs

Array of ContainerCIDR objects

List of container CIDR blocks. In clusters of v1.21 and later, the cidrs field is used. When the cluster network type is vpc-router, you can add multiple container CIDR blocks. In versions earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block.

The configuration cannot be changed after the cluster is created.

Table 7 ContainerCIDR

Parameter

Mandatory

Type

Description

cidr

Yes

String

Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, and 192.168.0.0/16-19

Table 8 EniNetwork

Parameter

Mandatory

Type

Description

eniSubnetId

Yes

String

IPv4 Subnet ID of the ENI container subnet. Currently, IPv6 is not supported.

eniSubnetCIDR

Yes

String

ENI subnet CIDR block.

Table 9 PublicAccess

Parameter

Type

Description

cidrs

Array of strings

Trustlist of network CIDRs that are allowed to access cluster APIs. You are advised to allow the traffic from VPC and container network CIDRs. By default, no trustlist is configured, and the value is ["0.0.0.0/0"].

Note

This parameter is valid only when a cluster is created.

Table 10 MasterSpec

Parameter

Mandatory

Type

Description

availabilityZone

No

String

Availability Zone.

For example, eu-de-01.

Table 11 Data structure of the extendParam field

Parameter

Type

Description

alpha.cce/fixPoolMask

String

Number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model (vpc-router).

This parameter determines the number of container IP addresses that can be allocated to a node. The maximum number of pods that can be created on a node is decided by this parameter and maxPods set during node creation.

The value is an integer ranging from 24 to 28.

kubernetes.io/cpuManagerPolicy

String

CPU management policy of the master node.

upgradefrom

String

Version from which this version is upgrade.

Table 12 Data structure of the status field

Parameter

Type

Description

phase

String

Cluster status. Possible values:

  • Available: The cluster is running properly.

  • Unavailable: The cluster is exhibiting unexpected behavior. Manually delete the cluster or contact the administrator to delete the cluster.

  • ScalingUp: Nodes are being added to the cluster.

  • ScalingDown: The cluster is being downsized to fewer nodes.

  • Creating: The cluster is being created.

  • Deleting: The cluster is being deleted.

  • Upgrading: The cluster is being upgraded.

  • Resizing: Cluster specifications are being changed.

  • Empty: The cluster has no resources.

reason

String

Reason of cluster state transition. This parameter is returned if the cluster is not in the Available state.

message

String

Detailed information about why the cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.

endpoints

endpoint object

Access address of the kube-apiserver in the cluster.

Table 13 Data structure of the endpoint field

Parameter

Type

Description

internal

String

Internal network address.

external

String

External network address.

external_otc

String

Endpoint of the cluster to be accessed through API Gateway.

Response example:

    "kind": "Cluster",
    "apiVersion": "v3",
    "metadata": {
        "name": "mycluster",
        "uid": "365b5e05-846a-11ea-9fe6-0255ac101107",
        "creationTimestamp": "2020-04-22 07:23:50.157883 +0000 UTC",
        "updateTimestamp": "2020-05-08 03:10:12.174334 +0000 UTC"
    },
    "spec": {
        "type": "VirtualMachine",
        "flavor": "cce.s1.small",
        "version": "v1.17.9-r0",
        "description": "new description",
        "az": "eu-de-01",
        "ipv6enable": false,
        "supportIstio": true,
        "hostNetwork": {
            "vpc": "23d3725f-6ffe-400e-8fb6-b4f9a7b3e8c1",
            "subnet": "c90b3ce5-e1f1-4c87-a006-644d78846438",
            "SecurityGroup": "7bf2a95b-f41d-4187-9e72-d0a9a4de8e6d"
        },
        "containerNetwork": {
            "mode": "overlay_l2",
            "cidr": "172.16.0.0/16"
        },
        "eniNetwork": {},
        "authentication": {
            "mode": "rbac",
            "authenticatingProxy": {}
        },
        "billingMode": 0,
        "extendParam": {
            "alpha.cce/fixPoolMask": "",
            "kubernetes.io/cpuManagerPolicy": "",
            "upgradefrom": ""
        },
        "kubernetesSvcIpRange": "10.247.0.0/16",
        "kubeProxyMode": "iptables"
    },
    "status": {
        "phase": "Available",
        "endpoints": [
            {
                "Internal": "https://192.168.0.61:5443",
            },
            {
                "External": "https://10.185.69.54:5443",
            },
           {
                "external_otc": "https://a140174a-2f3e-11e9-9f91-0255ac101405.cce.eu-de.otc.t-systems.com",            },
        ]
    }
}

Status Code

Table 14 describes the status code of this API.

Table 14 Status code

Status Code

Description

200

Information about the specified cluster is successfully obtained.

For details about error status codes, see Status Code.

last updated: 2024-12-13 13:16 UTC - commit: 637711c1b4cbb67ff8f1429f87a3eb6e1d7d78bc