API Guide - NHN Cloud User Guide

Container > NHN Kubernetes Service (NKS) > API v2 Guide

This guide describes the API for configuring Kubernetes clusters. To use the API, you need an API endpoint, token, etc. Refer to API Preparations to prepare the necessary information to use the API.

All API calls are made using the kubernetes type endpoint.

Type	Region	Endpoint
kubernetes	Korea (Pangyo) Region Korea (Pyeongchon) Region	https://kr1-api-kubernetes-infrastructure.nhncloudservice.com https://kr2-api-kubernetes-infrastructure.nhncloudservice.com

Fields not specified in the guide may appear in API responses. These fields are used for internal use by NHN Cloud and are subject to change without prior notice, so we advise you not to use them.

Check the Information of Resources Used in API

The NHN Kubernetes Service (NKS) API uses several resources for configuring clusters and node groups. You can check the information of each resource as follows.

UUID of the VPC Network Attached to the Internet Gateway

You can query the VPC network attached to the internet gateway by using the router:external=True query parameter in the VPC network list query API.

GET /v2.0/networks?router:external=True

For more information about the network list query API, refer to List Networks.

List of UUIDs of Subnets Attached to the Internet Gateway

Enter the UUID of subnet associated with the VPC network attached to the internet gateway. If multiple subnets are found, enter them by concatenating them with a colon (:). For more information about the subnet list query API, refer to List Subnets.

VPC Network UUID

Enter the UUID of internal VPC network to associate with the node. For more information about the network list query API, refer to List Networks.

VPC Subnet UUID

Enter the UUID of subnet associated with the internal VPC network to associate with the node. For more information about the subnet list query API, refer to List Subnets.

Availability Zone UUID

Enter the UUID of availability zone in which to create the node. For more information about the availability zone list query API, see List Availability Zones.

Key Pair UUID

Enter the key pair to use when connecting to the node. For more information about the key pair list query API, refer to List Key Pairs.

Base Image UUID

Enter the base image UUID to use for creating a node. The base image name and UUID for each region is as follows:

Region	Base Image Name	Base Image UUID
Korea (Pangyo) region	CentOS 7.9	1b8da49b-c240-4940-a811-85dfdf18e263
	Debian 11.8 Bullseye	29a86d4d-e7c8-42bb-9ee1-4cdb30135432
	Rocky Linux 8.9	be708c35-c94b-4623-9333-fc600025861d
	Ubuntu Server 20.04.6 LTS	a4ade08e-538b-439e-ba2e-13fccdcb32ae
	Ubuntu Server 22.04.3 LTS	346ec84c-9430-41d5-83f8-05292b74d796
Korea (Pyeongchon) region	CentOS 7.9	b8275b50-4c28-45a2-9bf4-9c704b3842b0
	Debian 11.8 Bullseye	aadb772b-f568-4d9a-a5a6-e3f3597bc2bb
	Rocky Linux 8.9	c11d7da0-1e55-4898-9953-7cc88f5fe477
	Ubuntu Server 20.04.6 LTS	723797ab-6da6-46f1-abd1-e266531f9ab1
	Ubuntu Server 22.04.3 LTS	0e62b502-c5d8-4d0d-8614-95a5d8795f6a

Block Storage Type

Enter the block storage UUID to use for the node. For more information about the block storage type list query API, refer to List Volume Types .

Flavor UUID

Enter the UUID of flavor for the node to be created. For more information about the flavor list query API, refer to List Flavors.

Cluster

List Clusters

Retrieves a list of clusters.

GET /v1/clusters
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID

Response

Name	Type	Format	Description
clusters	Body	Array	Cluster information object list
clusters.uuid	Body	UUID	Cluster UUID
clusters.name	Body	String	Cluster name
clusters.flavor_id	Body	UUID	UUID of the flavor for the default worker node
clusters.keypair	Body	UUID	UUID of the key pair applied to the default worker node group
clusters.node_count	Body	Integer	Total number of worker nodes
clusters.stack_id	Body	UUID	UUID of the heat stack associated with the master node group
clusters.status	Body	String	Cluster status
clusters.labels	Body	Object	Cluster label
clusters.labels.kube_tag	Body	String	Kubernetes version of the master node group
clusters.labels.availability_zone	Body	String	Applied to the default worker node group: Availability zone
clusters.labels.node_image	Body	UUID	Applied to the default worker node group: Base image UUID
clusters.labels.external_network_id	Body	String	UUID of VPC network attached to the internet gateway
clusters.labels.external_subnet_id_list	Body	String	List of UUIDs of subnets attached to the internet gateway (separated by colons)
clusters.labels.cert_manager_api	Body	String	Whether to enable the certificate signing request (CSR) feature. Must be set to "True"
clusters.labels.master_lb_floating_ip_enabled	Body	String	Whether to create a public domain address for Kubernetes API endpoint ("True" / "False")
clusters.labels.strict_sg_rules	Body	String	Create only required security rules in worker node security groups ("True" / "False"), (available for clusters created on or after February 27, 2024)
clusters.labels.additional_network_id_list	Body	String	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
clusters.labels.additional_subnet_id_list	Body	String	Applied to the default worker node group: List of VPC subnet UUIDs for additional networks (separated by colons)
clusters.labels.cni_driver	Body	String	Cluster CNI (Available for clusters created on or after 2023.03.31)
clusters.labels.service_cluster_ip_range	Body	String	IP range assigned to ClusterIP when creating a service from K8s service network and clusters (Available for clusters created on or after 2023.05.30)
clusters.labels.pods_network_cidr	Body	String	Cluster pod network (Available for clusters created on or after 2023.05.30)
clusters.labels.pods_network_subnet	Body	String	Cluster pod subnet size (Available for clusters created on or after 2023.05.30)
clusters.labels.ncr_sgw	Body	String	Service gateway UUID of NCR type
clusters.labels.obs_sgw	Body	String	Service gateway UUID of OBS type

Example

{
    "clusters": [
        {
            "cluster_template_id": "b4503d97-6012-499d-a31a-5200f94a7890",
            "create_timeout": 60,
            "docker_volume_size": null,
            "flavor_id": "6ef27f21-c774-4c0e-84ff-7dd4a762571f",
            "health_status": "HEALTHY",
            "keypair": "testkeypair",
            "labels": {
                "availability_zone": "kr2-pub-b",
                "cert_manager_api": "True",
                "clusterautoscale": "nodegroupfeature",
                "etcd_volume_size": "10",
                "external_network_id": "751b8227-7b45-440a-9349-dbf829d0aba5",
                "external_subnet_id_list": "59ddc195-76b1-431d-9693-f09880747dc6",
                "flavor_type": "core",
                "hypervisor_type": "qemu",
                "kube_tag": "v1.23.3",
                "login_username": "centos",
                "master_lb_floating_ip_enabled": "true",
                "strict_sg_rules": "True",
                "node_image": "f462a2a5-ba24-46d6-b7a1-9a9febcd3cfc",
                "os_arch": "amd64",
                "os_distro": "CentOS",
                "os_type": "linux",
                "os_version": "7.8",
                "project_domain": "NORMAL",
                "server_group_meta": "k8s_2b778d83-8b67-45b1-920e-b0c5ad5c2f30_561c3f55-a23f-4e1a-b2fa-a5459b2c0575",
                "service_cluster_ip_range": "10.254.0.0/16",
                "pods_network_cidr" : "10.100.0.0/16",
                "pods_network_subnet" : "24"
            },
            "links": [
                {
                    "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/v1/clusters/f0af4484-0a16-433a-a15c-295d9ba6537d",
                    "rel": "self"
                },
                {
                    "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/clusters/f0af4484-0a16-433a-a15c-295d9ba6537d",
                    "rel": "bookmark"
                }
            ],
            "name": "k8s-test",
            "node_count": 1,
            "stack_id": "7f497472-9729-4b89-9124-1c097335b856",
            "status": "CREATE_COMPLETE",
            "uuid": "2b778d83-8b67-45b1-920e-b0c5ad5c2f30"
        }
    ]
}

Get a Cluster

Retrieves information of an individual cluster.

GET /v1/clusters/{CLUSTER_ID_OR_NAME}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name

Response

Name	Type	Format	Description
uuid	Body	UUID	Cluster UUID
name	Body	String	Cluster name
flavor_id	Body	UUID	UUID of the flavor for the default worker node
keypair	Body	UUID	UUID of the key pair applied to the default worker node group
node_count	Body	Integer	Total number of worker nodes
stack_id	Body	UUID	UUID of the heat stack associated with the master node group
status	Body	String	Cluster status
status_reason	Body	String	Reason for the node group status (can be null)
api_address	Body	String	Kubernetes API endpoint
project_id	Body	String	Project (tenant) ID
fixed_network	Body	UUID	VPC UUID
fixed_subnet	Body	UUID	VPC Subnet UUID
node_addresses	Body	String List	Worker node IP address list
created_at	Body	String	Created time (UTC)
updated_at	Body	String	Last updated time (UTC)
labels	Body	Object	Cluster label
labels.kube_tag	Body	String	Kubernetes version of the master node group
labels.availability_zone	Body	String	Applied to the default worker node group: Availability zone
labels.node_image	Body	UUID	Applied to the default worker node group: Base image UUID
labels.external_network_id	Body	String	UUID of the VPC network attached to the internet gateway
labels.external_subnet_id_list	Body	String	List of UUIDs of subnets attached to the internet gateway (separated by colons)
labels.cert_manager_api	Body	String	Whether to enable the certificate signing request (CSR) feature. Must be set to "True"
labels.master_lb_floating_ip_enabled	Body	String	Whether to create a public domain address for Kubernetes API endpoint ("True" / "False")
labels.strict_sg_rules	Body	String	Create only required security rules in worker node security groups ("True" / "False"), (available for clusters created on or after February 27, 2024)
labels.additional_network_id_list	Body	String	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.additional_subnet_id_list	Body	String	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.cni_driver	Body	String	Cluster CNI (Available for clusters created on or after 2023.03.31)
labels.service_cluster_ip_range	Body	String	Cluster CIDR, IP range allocated to ClusterIP when creating the service in the cluster and K8s service networks (Available for clusters created on or after 2023.05.30)
labels.pods_network_cidr	Body	String	Cluster pod network (Available for clusters created on or after 2023.05.30)
labels.pods_network_subnet	Body	String	Cluster pod subnet size (Available for clusters created on or after 2023.05.30)
labels.ncr_sgw	Body	String	Service Gateway UUID of NCR type
labels.obs_sgw	Body	String	Service gateway UUID of OBS type

Example

{
    "api_address": "https://2b778d83-kr2-k8s.container.cloud.toast.com:6443",
    "cluster_template_id": "b4503d97-6012-499d-a31a-5200f94a7890",
    "coe_version": "v1.23.3",
    "container_version": "1.12.6",
    "create_timeout": 60,
    "created_at": "2021-08-05T01:48:39+00:00",
    "docker_volume_size": null,
    "fixed_network": "eb212079-b6ec-430c-ba57-14280a457bcb",
    "fixed_subnet": "4fdf5b80-3d35-43f5-a5c1-010a3b6c8e90",
    "flavor_id": "6ef27f21-c774-4c0e-84ff-7dd4a762571f",
    "floating_ip_enabled": false,
    "health_status": "HEALTHY",
    "health_status_reason": {
        {"test-k8s-default-w-bnga636xulqk-node-0.Ready": "True", "api": "ok"}
    },
    "keypair": "test-keypair",
    "labels": {
        "availability_zone": "kr2-pub-b",
        "cert_manager_api": "True",
        "clusterautoscale": "nodegroupfeature",
        "etcd_volume_size": "10",
        "external_network_id": "751b8227-7b45-440a-9349-dbf829d0aba5",
        "external_subnet_id_list": "59ddc195-76b1-431d-9693-f09880747dc6",
        "flavor_type": "core",
        "hypervisor_type": "qemu",
        "kube_tag": "v1.23.3",
        "kube_version_status": "NEED_UPGRADE",
        "login_username": "centos",
        "master_lb_floating_ip_enabled": "true",
        "strict_sg_rules": "True",
        "node_image": "f462a2a5-ba24-46d6-b7a1-9a9febcd3cfc",
        "os_arch": "amd64",
        "os_distro": "CentOS",
        "os_type": "linux",
        "os_version": "7.8",
        "project_domain": "NORMAL",
        "server_group_meta": "k8s_2b778d83-8b67-45b1-920e-b0c5ad5c2f30_561c3f55-a23f-4e1a-b2fa-a5459b2c0575",
        "service_cluster_ip_range": "10.254.0.0/16",
        "pods_network_cidr" : "10.100.0.0/16",
        "pods_network_subnet" : "24"
    },
    "links": [
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/v1/clusters/2b778d83-8b67-45b1-920e-b0c5ad5c2f30",
            "rel": "self"
        },
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/clusters/2b778d83-8b67-45b1-920e-b0c5ad5c2f30",
            "rel": "bookmark"
        }
    ],
    "name": "test-k8s",
    "node_addresses": [
        "192.168.0.5"
    ],
    "node_count": 1,
    "project_id": "1ffeaca9bbf94ab1aa9cffdec29a258a",
    "stack_id": "7f497472-9729-4b89-9124-1c097335b856",
    "status": "CREATE_COMPLETE",
    "status_reason": null,
    "updated_at": "2021-08-05T04:39:49+00:00",
    "user_id": "12ba32bebc414c4992a2c9be3952a64c",
    "uuid": "2b778d83-8b67-45b1-920e-b0c5ad5c2f30"
}

View Task History List

Views a list of the cluster's job history.

GET /v1/clusters/{CLUSTER_UUID}/events
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_UUID	URL	UUID	O	Cluster UUID

Response

Name	Type	Format	Description
events	Body	Array	Task history object list
events.id	Body	Integer	Task ID
events.uuid	Body	UUID	Task UUID
events.project_id	Body	String	Project (tenant) ID
events.cluster_uuid	Body	String	Cluster UUID
events.cluster_name	Body	String	Cluster name
events.resource_uuid	Body	String	Target UUID for the task
events.resource_name	Body	String	Target name
events.resource_type	Body	String	Target type ("cluster" / "nodegroup")
events.type	Body	String	Task type
events.state	Body	String	Task status ("SUCCESS" / "FAIL" / "IN_PROGRESS")
events.contents	Body	String	Task progress (null when successful)
events.created_at	Body	String	Task start time (UTC)
events.updated_at	Body	String	Task end time (UTC)

Example

{
    "events": [
        {
            "id": 3683,
            "uuid": "868f218a-9446-4500-b6b3-8c1a95e3d7c3",
            "project_id": "5d8cc67593754d5581f7e8986badf358",
            "cluster_uuid": "388794e6-14dc-48ee-9a4f-9c40df5d97ec",
            "cluster_name": "nks-cluster",
            "resource_uuid": "388794e6-14dc-48ee-9a4f-9c40df5d97ec",
            "resource_name": "nks-cluster",
            "resource_type": "cluster",
            "type": "CLUSTER_CREATE",
            "state": "SUCCESS",
            "contents": null,
            "created_at": "2024-01-30T01:31:06+00:00",
            "updated_at": "2024-01-30T01:42:39+00:00"
        }
    ]
}

List Task History

Lists the job history of a cluster.

GET /v1/clusters/{CLUSTER_UUID}/events/{EVENT_UUID}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_UUID	URL	UUID	O	Cluster UUID
EVENT_UUID	URL	UUID	O	Task UUID

Response

Name	Type	Format	Description
id	Body	Integer	Task ID
uuid	Body	UUID	Task UUID
project_id	Body	String	Project (tenant) ID
cluster_uuid	Body	UUID	Cluster UUID
cluster_name	Body	String	Cluster name
resource_uuid	Body	UUID	Target UUID for the task
resource.name	Body	String	Target name
resource_type	Body	String	Target type ("cluster" / "nodegroup")
type	Body	String	Task type
state	Body	String	Task status ("SUCCESS" / "FAIL" / "IN_PROGRESS")
contents	Body	String	Task progress (null when successful)
created_at	Body	String	Task start time (UTC)
updated_at	Body	String	Task end time (UTC)

Example

{
    "id": 3683,
    "uuid": "868f218a-9446-4500-b6b3-8c1a95e3d7c3",
    "project_id": "5d8cc67593754d5581f7e8986badf358",
    "cluster_uuid": "388794e6-14dc-48ee-9a4f-9c40df5d97ec",
    "cluster_name": "nks-cluster",
    "resource_uuid": "388794e6-14dc-48ee-9a4f-9c40df5d97ec",
    "resource_name": "nks-cluster",
    "resource_type": "cluster",
    "type": "CLUSTER_CREATE",
    "state": "SUCCESS",
    "contents": null,
    "created_at": "2024-01-30T01:31:06+00:00",
    "updated_at": "2024-01-30T01:42:39+00:00"
}

Create a Cluster

Creates a cluster.

POST /v1/clusters
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
keypair	Body	String	O	UUID of the key pair applied to the default worker node group
name	Body	String	O	Cluster name
cluster_template_id	Body	String	O	Cluster template ID. Must be set to "iaas_console"
node_count	Body	String	O	Number of nodes to apply to the default worker node group
labels	Body	Object	O	Cluster creation information object
labels.availability_zone	Body	String	O	Applied to the default worker node group: Availability zone
labels.node_image	Body	UUID	O	Applied to the default worker node group: Base image UUID
labels.boot_volume_type	Body	String	O	Applied to the default worker node group: Block storage type
labels.boot_volume_size	Body	String	O	Applied to the default worker node group: Block storage size (GB)
labels.boot_volume_key_id	Body	String	X	(Symmetric key ID to apply to encrypted block storage (if using encrypted block storage)
labels.boot_volume_appkey	Body	String	X	The appkey for the symmetric key to apply to encrypted block storage (if using encrypted block storage)
labels.external_network_id	Body	String	X	UUID of the VPC network attached to the internet gateway Must be set when a router associated with a VPC subnet is attached to the internet gateway
labels.external_subnet_id_list	Body	String	X	List of UUIDs of subnets attached to the internet gateway (separated by colon) Must be set when a router associated with a VPC subnet is attached to the internet gateway
labels.cert_manager_api	Body	String	O	Whether to enable the certificate signing request (CSR) feature. Must be set to "True"
labels.ca_enable	Body	String	O	Applied to the default worker node group: Autoscaler: Whether to enable the feature ("True" / "False")
labels.ca_max_node_count	Body	String	X	Applied to the default worker node group: Autoscaler: Maximum number of nodes
labels.ca_min_node_count	Body	String	X	Applied to the default worker node group: Autoscaler: Minimum number of nodes
labels.ca_scale_down_enable	Body	String	X	Applied to the default worker node group: Autoscaler: Whether to enable scale-down ("True" / "False")
labels.ca_scale_down_unneeded_time	Body	String	X	Applied to the default worker node group: Autoscaler: Scale down unneeded time
labels.ca_scale_down_util_thresh	Body	String	X	Applied to the default worker node group: Autoscaler: Scale down utilization threshold
labels.ca_scale_down_delay_after_add	Body	String	X	Applied to the default worker node group: Auto Scaler: Scale down delay after add
labels.kube_tag	Body	String	O	Kubernetes Version
labels.user_script	Body	String	X	User script (old)
labels.user_script_v2	Body	String	X	User script
labels.master_lb_floating_ip_enabled	Body	String	O	Whether to create a public domain address for Kubernetes API endpoint ("True" / "False")
labels.strict_sg_rules	Body	String	X	Create only required security rules in the worker node security group ("True" / "False"), default: "False"
labels.additional_network_id_list	Body	String	X	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.additional_subnet_id_list	Body	String	X	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.service_cluster_ip_range	Body	String	X	K8s service network, the IP band assigned to the ClusterIP when creating a service in the cluster. See fixed_subnet, pods_network_cidr, and service_cluster_ip_range input rules.
labels.pods_network_cidr	Body	String	X	Cluster Pod Network. See fixed_subnet, pods_network_cidr, service_cluster_ip_range input rules
labels.pods_network_subnet	Body	Integer	X	Cluster Pod subnet size. See pods_network_subnet input rules
labels.ncr_sgw	Body	String	X	Service gateway UUID of NCR type
labels.obs_sgw	Body	String	X	Service gateway UUID of OBS type
flavor_id	Body	UUID	O	Applied to the default worker node group: Node instance flavor UUID
fixed_network	Body	UUID	O	VPC Network UUID
fixed_subnet	Body	UUID	O	VPC subnet UUID. Note the rules for entering fixed_subnet, pods_network_cidr, and service_cluster_ip_range.

[Caution] The CIDRs for fixed_subnet, pods_network_cidr, and service_cluster_ip_range must be entered in the following conventions - CIDR cannot overlap with the link-local address band (169.254.0.0/16). - The fixed_subnet, pods_network_cidr, and service_cluster_ip_range bands cannot overlap. - CIDR cannot overlap with the IP band (198.18.0.0/19) being used inside the NKS. - You cannot enter a CIDR block greater than /24. (The following CIDR blocks are not available: /26, /30). - For clusters of v1.23.3 or earlier, they cannot overlap with BIP (bridged IP range) (172.17.0.0/16). pod_network_subnet must be entered in the following rules. - Values between 20 and 28 (included) are allowed. The pods_network_subnet value must be at least 2 greater than the pods_network_cidr prefix value. Normal example (Pod subnet size: 24, Pod network: 10.100.0.0/22)

Example

{
    "cluster_template_id": "iaas_console",
    "create_timeout": 60,
    "fixed_network": "eb212079-b6ec-430c-ba57-14280a457bcb",
    "fixed_subnet": "4fdf5b80-3d35-43f5-a5c1-010a3b6c8e90",
    "flavor_id": "6ef27f21-c774-4c0e-84ff-7dd4a762571f",
    "keypair": "test-keypair",
    "labels": {
        "availability_zone": "kr2-pub-b",
        "boot_volume_size": "20",
        "boot_volume_type": "General HDD",
        "ca_enable": "false",
        "ca_max_node_count": "10",
        "ca_min_node_count": "1",
        "ca_scale_down_delay_after_add": "3",
        "ca_scale_down_enable": "true",
        "ca_scale_down_unneeded_time": "3",
        "ca_scale_down_util_thresh": "50",
        "cert_manager_api": "True",
        "clusterautoscale": "nodegroupfeature",
        "external_network_id": "751b8227-7b45-440a-9349-dbf829d0aba5",
        "external_subnet_id_list": "59ddc195-76b1-431d-9693-f09880747dc6",
        "kube_tag": "v1.23.3",
        "master_lb_floating_ip_enabled": "true",
        "strict_sg_rules": "True",
        "node_image": "f462a2a5-ba24-46d6-b7a1-9a9febcd3cfc",
        "user_script_v2": ""
    },
    "name": "test-k8s",
    "node_count": 1
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Cluster UUID

Example

{
    "uuid": "5801ef8a-3760-4858-b467-fc4c1201241d"
}

Delete a Cluster

Deletes a Cluster.

DELETE /v1/clusters/{CLUSTER_ID_OR_NAME}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name

Response

This API does not return a response body.

Resize

Adjusts the number of nodes in the cluster.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/actions/resize
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
nodegroup	Body	UUID	O	Target worker node group name / UUID
node_count	Body	Integer	O	Number of worker nodes to change
nodes_to_remove	Body	String List	X	UUID of the node to delete

Caution
- If you are scaling down nodes (i.e., deleting some nodes), you must set nodes_to_remove to specify which nodes to delete. If you do not specify the nodes to delete, the nodes to be deleted are selected randomly.
- node_count: min 1, max 10 (however, the max value can be adjusted with quota)

Scale-up Example

{
    "node_count": 3,
    "nodegroup": "default-worker"
}

Scale-down Example

{
    "node_count": 1,
    "nodegroup": "default-worker",
    "nodes_to_remove": [
        "593e4aee-697f-4808-aa5b-d3c8703795ff",
        "ce2e2d2a-ddf5-41da-a338-72e7f5237088"
    ]
}

Response

Name	Type	Format	Description
uuid	Body	String	Target cluster UUID

Example

{
    "uuid": "5bac7acd-58b7-4cf5-95f5-a25d67da13a2"
}

Get kubeconfig of a Cluster

Retrieves the cluster configuration file (kubeconfig).

GET /v1/clusters/{CLUSTER_ID_OR_NAME}/config
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name

Response

Name	Type	Format	Description
config	Body	String	kubeconfig file body

Example

{
    "config": "apiVersion: v1\nclusters:\n- cluster:\n    certificate-authority-data: LS0tLS1CRU... \n    server: https://96742ac4-kr2-k8s.container.cloud.toast.com:6443\n  name: \"toast-robot-e2e-1-18\"\ncontexts:\n- context:\n    cluster: \"toast-robot-e2e-1-18\"\n    user: admin\n  name: default\ncurrent-context: default\nkind: Config\npreferences: {}\nusers:\n- name: admin\n  user:\n    client-certificate-data: LS0tLS1CRU...\n    client-key-data: LS0tLS1CRU...\n"
}

Change Cluster CNI

Changes the cluster CNI (container network interface). You can change Flannel CNI to a different CNI. For more information on the types of CNIs you can change and the conditions under which they can be changed, see User Guide.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/actions/cni_update
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
cni	Body	String	O	Configure a CNI to change (Selectable CNI list: calico)
num_buffer_nodes	Body	Integer	X	Number of buffer nodes. Default: 1, minimum: 0, maximum: number of additional nodes that can be created in each worker node group (maximum number of nodes per worker node group - current number of nodes in that worker node group)
num_max_unavailable_nodes	Body	Integer	X	Maximum number of unavailable nodes. minimum: 1, maximum: current number of nodes for the cluster, default: 1
pod_cidr	Body	String	O	calico pod cidr settings, see the input rules of pod_cidr
pod_subnet	Body	String	O	calico pod cidr subnet settings, Default: 24, see the input rules of pod_subnet

pod_cidr must be entered in the following rules. * CIDR cannot overlap with the link-local address band (169.254.0.0/16). * CIDR cannot overlap with the service IP band (K8s service network) used in NKS clusters. * CIDR cannot overlap with the IP band (198.18.0.0/19) being used inside the NKS. * CIDR cannot overlap with bands of the VPC network subnet or additional network subnets connected to NKS clusters. * CIDR cannot overlap with a pod network band that is currently being used for NKS clusters. * You cannot enter a CIDR block greater than /24. (The following CIDR blocks are not available: /26, /30)

pod_subnet must be entered in the following rules. * Values between 20 and 28 (included) are allowed. * The value of pod_subnet must be at least 2 greater than the prefix value of pod_cidr. Normal example (pod subnet size: 24, pod network: 10.100.0.0/22)

Example

{
    "cni": "calico",
    "num_max_unavailable_nodes": 1,
    "num_buffer_nodes": 1,
    "pod_cidr": "10.200.0.0/16"
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Cluster UUID

Example

{
    "uuid": "0641db9f-5e71-4df9-9571-089c7964d82e"
}

Enforce IP Access Control to Cluster API Endpoints

You can enforce or disable IP access control to cluster API endpoints. For more information about IP access control features, see IP access control. For more information about IP access control rules for Cluster API endpoints, see the user guide.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/api_ep_ipacl
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
enable	Body	String	O	Can be set to either 'true' or 'false'. Default: 'false' Enforce IP Access Control to Cluster API Endpoints false: Disable IP access control for cluster API endpoints, all sub-settings are ignored when set to false
Endpoint stage ID	Body	String	O (if the enable setting is true)	IP access control type, can be set to either ALLOW or DENY
ipacl_targets	Body	List of Object	O (if the enable setting is true)	IP access control target object
ipacl_targets.cidr_address	Body	String	O (if the enable setting is true)	IP access control target. You can enter an IP address or a range of IP addresses in CIDR format.
ipacl_targets.descripion	Body	String	X	IP access control target description

Example

{
    "enable": "True",
    "action": "ALLOW",
    "ipacl_targets": [
        {
            "cidr_address" : "192.168.0.5"
        },
        {
            "cidr_address" : "10.10.22.3/24",
            "description": "Your Friends"
        }
    ]   
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Cluster UUID

Example

{
    "uuid": "0641db9f-5e71-4df9-9571-089c7964d82e"
}

Get Cluster API Endpoint IP Access Control

You can view IP access control information applied to your cluster API endpoints.

GET /v1/clusters/{CLUSTER_ID_OR_NAME}/api_ep_ipacl
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name

Response

Name	Type	Format	Description
cluster_uuid	Body	UUID	Cluster UUID
enable	Body	String	true: IP access control is applied to the cluster API endpoint, false: IP access control is off for the cluster API endpoint
Endpoint stage ID	Body	String	IP access control type ALLOW, DENY can be checked
ipacl_targets	Body	List of Object	IP access control target object
ipacl_targets.cidr_address	Body	String	IP access control target. You can enter an IP address or a range of IP addresses in CIDR format.
ipacl_targets.descripion	Body	String	IP access control target description

Example when enable: true

{
    "cluster_uuid" : "8be87215-9db7-45ed-a03c-38e6db939915",
    "enable": "true",
    "action": "ALLOW",
    "ipacl_targets": [
        {
            "cidr_address" : "192.168.0.5",
            "description": "My Friend"
        },
        {
            "cidr_address" : "10.10.22.3/24"
        }
    ]   
}

Example when enable: false

{
    "cluster_uuid" : "8be87215-9db7-45ed-a03c-38e6db939915",
    "enable": "false"
}

Node Group

List Node Groups

Retrieves a list of node groups.

GET /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name

Response

Name	Type	Format	Description
nodegroups	Body	Array	Node group information object list
nodegroups.uuid	Body	UUID	Node group UUID
nodegroups.flavor_id	Body	UUID	Node group flavor UUID
nodegroups.image_id	Body	UUID	Node group base image UUID
nodegroups.max_node_count	Body	Integer	Maximum number of nodes in a node group
nodegroups.min_node_count	Body	Integer	Minimum number of nodes in a node group
nodegroups.name	Body	String	Node Group Name
nodegroups.node_count	Body	Integer	Number of nodes in a node group
nodegroups.role	Body	String	Node group role
nodegroups.stack_id	Body	UUID	UUID of the heat stack associated with the node group
nodegroups.status	Body	String	Node group status

Example

{
    "nodegroups": [
        {
            "flavor_id": "069bdcff-e9b6-42c8-83ce-4c743ea30394",
            "image_id": "96aff4ab-d221-4688-8364-2fcf02d50547",
            "is_default": false,
            "max_node_count": 10,
            "min_node_count": 1,
            "name": "default-worker",
            "node_count": 2,
            "role": "worker",
            "stack_id": "f04c157a-78e3-4bfc-a83e-fbe7c01ab616",
            "status": "UPDATE_COMPLETE",
            "uuid": "018b06c5-1293-4081-8242-167a1cb9f262"
        }
    ]
}

Get a Node Group

Retrieves information of an individual node group.

GET /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name

Response

Name	Type	Format	Description
uuid	Body	UUID	Node group UUID
name	Body	String	Node Group Name
cluster_id	Body	UUID	UUID of the cluster to which the node group belongs
flavor_id	Body	UUID	UUID of the flavor used by the node
image_id	Body	UUID	UUID of the base image used by the node
labels	Body	Object	Node group creation information object
labels.availability_zone	Body	String	Applied to the worker node group: Availability zone
labels.node_image	Body	UUID	Applied to the worker node group: Base image UUID
labels.boot_volume_type	Body	String	Applied to the worker node group: Block storage type
labels.boot_volume_size	Body	String	Applied to the worker node group: Block storage size (GB)
labels.boot_volume_key_id	Body	String	ID of symmetric key applied to block storage (when using encrypted block storage)
labels.boot_volume_appkey	Body	String	Appkey of symmetric key applied to block storage (when using encrypted block storage)
labels.external_network_id	Body	String	UUID of the VPC network attached to the internet gateway
labels.external_subnet_id_list	Body	String	List of UUIDs of subnets attached to the internet gateway (separated by colons)
labels.cert_manager_api	Body	String	Whether to enable the certificate signing request (CSR) feature. Must be set to "True"
labels.ca_enable	Body	String	Applied to the worker node group: Autoscaler: Whether to enable the feature ("True" / "False")
labels.ca_max_node_count	Body	String	Applied to the worker node group: Autoscaler: Maximum number of nodes
labels.ca_min_node_count	Body	String	Applied to the worker node group: Autoscaler: Minimum number of nodes
labels.ca_scale_down_enable	Body	String	Applied to the worker node group: Autoscaler: Whether to enable scale-down ("True" / "False")
labels.ca_scale_down_unneeded_time	Body	String	Applied to the worker node group: Autoscaler: Scale down unneeded time
labels.ca_scale_down_util_thresh	Body	String	Applied to the worker node group: Autoscaler: Scale down utilization threshold
labels.ca_scale_down_delay_after_add	Body	String	Applied to the worker node group: Auto Scaler: Scale down delay after add
labels.kube_tag	Body	String	Kubernetes version of the worker node group
labels.user_script	Body	String	User Script (old)
labels.user_script_v2	Body	String	User Script
labels.additional_network_id_list	Body	String	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.additional_subnet_id_list	Body	String	Applied to the default worker node group: List of VPC subnet UUIDs for additional networks (separated by colons)
labels.strict_sg_rules	Body	String	Create only required security rules in worker node security groups ("True" / "False"), (available for clusters created on or after February 27, 2024)
max_node_count	Body	Integer	Maximum Node Count
min_node_count	Body	Integer	Minimum Node Count
node_addresses	Body	String list	List of node IP addresses
node_count	Body	Integer	Node Count
project_id	Body	String	Project (tenant) ID
role	Body	String	Node group role
stack_id	Body	UUID	UUID of the heat stack associated with the node group
status	Body	String	Node group status
status_reason	Body	String	Reason for the node group status (can be null)
created_at	Body	String	Created time (UTC)
updated_at	Body	String	Last updated time (UTC)

Example

{
    "cluster_id": "96742ac4-02e7-4b1d-a242-02876c0bd3f8",
    "created_at": "2021-10-23T10:06:19+00:00",
    "docker_volume_size": null,
    "flavor_id": "069bdcff-e9b6-42c8-83ce-4c743ea30394",
    "id": 2697,
    "image_id": "96aff4ab-d221-4688-8364-2fcf02d50547",
    "is_default": false,
    "labels": {
        "availability_zone": "",
        "boot_volume_size": "20",
        "boot_volume_type": "General HDD",
        "ca_enable": "True",
        "ca_image": "k8s.gcr.io/autoscaling/cluster-autoscaler:v1.19.0",
        "ca_max_node_count": "10",
        "ca_min_node_count": "2",
        "ca_scale_down_delay_after_add": "10",
        "ca_scale_down_enable": "True",
        "ca_scale_down_unneeded_time": "10",
        "ca_scale_down_util_thresh": "50",
        "cert_manager_api": "true",
        "clusterautoscale": "nodegroupfeature",
        "external_network_id": "751b8227-7b45-440a-9349-dbf829d0aba5",
        "external_subnet_id_list": "59ddc195-76b1-431d-9693-f09880747dc6",
        "flavor_type": "memory",
        "hypervisor_type": "qemu",
        "kube_tag": "v1.19.13",
        "kube_version_status": "LATEST",
        "login_username": "centos",
        "master_lb_floating_ip_enabled": "true",
        "strict_sg_rules": "True",
        "node_image": "96aff4ab-d221-4688-8364-2fcf02d50547",
        "os_arch": "amd64",
        "os_distro": "CentOS",
        "os_type": "linux",
        "os_version": "7.8",
        "project_domain": "NORMAL",
        "server_group_meta": "k8s_96742ac4-02e7-4b1d-a242-02876c0bd3f8_018b06c5-1293-4081-8242-167a1cb9f262"
    },
    "links": [
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/v1/clusters/96742ac4-02e7-4b1d-a242-02876c0bd3f8/nodegroups/018b06c5-1293-4081-8242-167a1cb9f262",
            "rel": "self"
        },
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/clusters/96742ac4-02e7-4b1d-a242-02876c0bd3f8/nodegroups/018b06c5-1293-4081-8242-167a1cb9f262",
            "rel": "bookmark"
        }
    ],
    "max_node_count": 10,
    "min_node_count": 2,
    "name": "default-worker",
    "node_addresses": [
        "192.168.0.40",
        "192.168.0.19"
    ],
    "node_count": 2,
    "project_id": "1ffeaca9bbf94ab1aa9cffdec29a258a",
    "role": "worker",
    "stack_id": "f04c157a-78e3-4bfc-a83e-fbe7c01ab616",
    "status": "UPDATE_COMPLETE",
    "status_reason": "Stack UPDATE completed successfully",
    "updated_at": "2021-10-28T02:13:15+00:00",
    "uuid": "018b06c5-1293-4081-8242-167a1cb9f262",
    "version": null
}

Create a Node Group

Creates a node group.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
flavor_id	Body	UUID	O	UUID of the flavor used by the node
image_id	Body	UUID	O	UUID of the base image used by the node
labels	Body	Object	O	Node group creation information object
labels.availability_zone	Body	String	O	Applied to the default worker node group: Availability zone
labels.boot_volume_type	Body	String	O	Applied to the default worker node group: Block storage type
labels.boot_volume_size	Body	String	O	Applied to the default worker node group: Block storage size (GB)
labels.ca_enable	Body	String	O	Applied to the default worker node group: Autoscaler: Whether to enable the feature ("True" / "False")
labels.ca_max_node_count	Body	String	X	Applied to the default worker node group: Autoscaler: Maximum number of nodes
labels.ca_min_node_count	Body	String	X	Applied to the default worker node group: Autoscaler: Minimum number of nodes
labels.ca_scale_down_enable	Body	String	X	Applied to the default worker node group: Autoscaler: Whether to enable scale-down ("True" / "False")
labels.ca_scale_down_unneeded_time	Body	String	X	Applied to the default worker node group: Autoscaler: Scale down unneeded time
labels.ca_scale_down_util_thresh	Body	String	X	Applied to the default worker node group: Autoscaler: Scale down utilization threshold
labels.ca_scale_down_delay_after_add	Body	String	X	Applied to the default worker node group: Auto Scaler: Scale down delay after add
labels.ca_scale_down_util_thresh	Body	String	X	Applied to the default worker node group: Autoscaler: Scale down utilization threshold
labels.ca_scale_down_delay_after_add	Body	String	X	Applied to the default worker node group: Auto Scaler: Scale down delay after add
labels.user_script	Body	String	X	User Script (old)
labels.user_script_v2	Body	String	X	User Script
labels.additional_network_id_list	Body	String	X	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.additional_subnet_id_list	Body	String	X	Applied to the default worker node group: List of VPC subnet UUIDs for additional networks (separated by colons))
name	Body	String	O	Node Group Name
node_count	Body	Integer	X	Number of nodes (Default: 1)

Example

{
    "name": "added-nodegroup",
    "node_count": 1,
    "flavor_id": "6ef27f21-c774-4c0e-84ff-7dd4a762571f",
    "image_id": "f462a2a5-ba24-46d6-b7a1-9a9febcd3cfc",
    "labels": {
        "availability_zone": "kr2-pub-b",
        "boot_volume_size": "20",
        "boot_volume_type": "General HDD",
        "ca_enable": "false"
    }
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node group UUID
cluster_id	Body	UUID	UUID of the cluster to which the node group belongs
flavor_id	Body	UUID	UUID of the flavor used by the node
image_id	Body	UUID	UUID of the base image used by the node
labels	Body	Object	Node group creation information object
labels.availability_zone	Body	String	Applied to the default worker node group: Availability zone
labels.boot_volume_type	Body	String	Applied to the default worker node group: Block storage type
labels.boot_volume_size	Body	String	Applied to the default worker node group: Block storage size (GB)
labels.ca_enable	Body	String	Applied to the default worker node group: Autoscaler: Whether to enable the feature ("True" / "False")
labels.ca_max_node_count	Body	String	Applied to the default worker node group: Autoscaler: Maximum number of nodes
labels.ca_min_node_count	Body	String	Applied to the default worker node group: Autoscaler: Minimum number of nodes
labels.ca_scale_down_enable	Body	String	Applied to the default worker node group: Autoscaler: Whether to enable scale-down ("True" / "False")
labels.ca_scale_down_unneeded_time	Body	String	Applied to the default worker node group: Autoscaler: Scale down unneeded time
labels.ca_scale_down_util_thresh	Body	String	Applied to the default worker node group: Autoscaler: Scale down utilization threshold
labels.ca_scale_down_delay_after_add	Body	String	Applied to the default worker node group: Auto Scaler: Scale down delay after add
labels.user_script	Body	String	User Script (old)
labels.user_script_v2	Body	String	User Script
labels.additional_network_id_list	Body	String	Applied to the default worker node group: List of VPC network UUIDs for additional networks (separated by colons)
labels.additional_subnet_id_list	Body	String	Applied to the default worker node group: List of VPC subnet UUIDs for additional networks (separated by colons)
max_node_count	Body	Integer	Maximum Node Count
min_node_count	Body	Integer	Minimum Node Count
name	Body	String	Node Group Name
node_count	Body	Integer	Number of nodes (Default: 1)
project_id	Body	String	Project (tenant) ID
role	Body	String	Node group role

Example

{
    "cluster_id": "96742ac4-02e7-4b1d-a242-02876c0bd3f8",
    "flavor_id": "6ef27f21-c774-4c0e-84ff-7dd4a762571f",
    "image_id": "f462a2a5-ba24-46d6-b7a1-9a9febcd3cfc",
    "labels": {
        "availability_zone": "kr2-pub-b",
        "boot_volume_size": "20",
        "boot_volume_type": "General HDD",
        "ca_enable": "false",
        "ca_max_node_count": "10",
        "ca_min_node_count": "1",
        "ca_scale_down_enable": "true",
        "ca_scale_down_unneeded_time": "10",
        "ca_scale_down_util_thresh": "50",
        "clusterautoscale": "nodegroupfeature",
        "user_script_v2": ""
    },
    "links": [
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/v1/clusters/96742ac4-02e7-4b1d-a242-02876c0bd3f8/nodegroups/a3366f2f-a1f3-45ef-8390-10536e8060ff",
            "rel": "self"
        },
        {
            "href": "https://kr2-api-kubernetes-infrastructure.nhncloudservice.com/clusters/96742ac4-02e7-4b1d-a242-02876c0bd3f8/nodegroups/a3366f2f-a1f3-45ef-8390-10536e8060ff",
            "rel": "bookmark"
        }
    ],
    "max_node_count": null,
    "min_node_count": 1,
    "name": "added-nodegroup",
    "node_count": 1,
    "project_id": "1ffeaca9bbf94ab1aa9cffdec29a258a",
    "role": "worker",
    "uuid": "a3366f2f-a1f3-45ef-8390-10536e8060ff"
}

Delete a Node Group

Deletes the specified node group.

DELETE /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name

Response

This API does not return a response body.

Stop a Node Group

Stops the specified node group.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/stop_node
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name
node_list	Body	String	O	List of UUIDs of node instances separated by colon (`:`)

Example

{
    "node_list": "bdaa560c-7a30-4249-9438-2df27fa1e9d38:68ff49ee-4111-4212-8e9e-88835cb0ebaa"
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node Group UUID

Example

{
    "uuid": "439aa682-398f-4061-a4d1-116da6b1154e"
}

Start a Node

Start the specified node list.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/start_node
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name
node_list	Body	String	O	List of UUIDs of node instances separated by colon (`:`)

Example

{
    "node_list": "bdaa560c-7a30-4249-9438-2df27fa1e9d38"
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node Group UUID

Example

{
    "uuid": "439aa682-398f-4061-a4d1-116da6b1154e"
}

View Autoscaler Configuration of a Node Group

Views the autoscaler configuration of a node group.

GET /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/autoscale
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name

Response

Name	Type	Format	Description
ca_enable	Body	String	Whether to enable the feature ("True" / "False")
ca_max_node_count	Body	String	Maximum Node Count
ca_min_node_count	Body	String	Minimum Node Count
ca_scale_down_enable	Body	String	Whether to enable scale-down ("True" / "False")
ca_scale_down_unneeded_time	Body	String	Scale Down Unneeded Time
ca_scale_down_util_thresh	Body	String	Scale Down Utilization Threshold
ca_scale_down_delay_after_add	Body	String	Scale Down Delay After Add

Example

{
    "ca_enable": true,
    "ca_image": "k8s.gcr.io/autoscaling/cluster-autoscaler:v1.19.0",
    "ca_max_node_count": 10,
    "ca_min_node_count": 2,
    "ca_scale_down_delay_after_add": 10,
    "ca_scale_down_enable": true,
    "ca_scale_down_unneeded_time": 10,
    "ca_scale_down_util_thresh": 50,
    "clusterautoscale": "nodegroupfeature"
}

Change Autoscaler Configuration of a Node Group

Changes the autoscaler configuration of a node group.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/autoscale
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name
ca_enable	Body	String	O	Whether to enable the feature ("True" / "False")
ca_max_node_count	Body	String	X	Maximum Node Count
ca_min_node_count	Body	String	X	Minimum Node Count
ca_scale_down_enable	Body	String	X	Whether to enable scale-down ("True" / "False")
ca_scale_down_unneeded_time	Body	String	X	Scale Down Unneeded Time
ca_scale_down_util_thresh	Body	String	X	Scale Down Utilization Threshold
ca_scale_down_delay_after_add	Body	String	X	Scale Down Delay After Add

Example

{
    "ca_enable": true,
    "ca_max_node_count": 10,
    "ca_min_node_count": 1,
    "ca_scale_down_delay_after_add": 30,
    "ca_scale_down_enable": true,
    "ca_scale_down_unneeded_time": 20,
    "ca_scale_down_util_thresh": 40
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node group UUID

Example

{
    "uuid": "018b06c5-1293-4081-8242-167a1cb9f262"
}

Upgrade a Cluster

Upgrades a cluster.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/upgrade
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name Set to default-master when upgrading the master components
version	Body	String	O	Kubernetes Version
num_buffer_nodes	Body	Integer	X	Number of buffer nodes. Minimum value: 0, Maximum value: (Maximum number of nodes per the worker node group - the current number of nodes for the worker node group), Default value: 1
num_max_unavailable_nodes	Body	Integer	X	Maximum number of unavailable nodes. Minimum value: 1, Maximum value: The current number of nodes for the worker node group, Default value: 1

To upgrade a cluster, you must upgrade the master components and then upgrade the worker components. Master and worker component upgrades are performed on a per node group basis.

Upgrading master components
- Set the node group name to default-master.
Upgrading worker components
- Set the name of node group to upgrade.

Example

{
    "version": "v1.19.13"
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node group UUID

Example

{
    "uuid": "018b06c5-1293-4081-8242-167a1cb9f262"
}

Change User Script

Changes the user script of the node group.

POST /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}/userscript
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name Set to default-master when upgrading master components
contents	Body	String	O	User script content

Example

{
    "contents": "user script contents here..."
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node Group UUID

Example

{
    "uuid": "018b06c5-1293-4081-8242-167a1cb9f262"
}

Change Instance Flavor

You can change the instance flavor of a node group.

PATCH /v1/clusters/{CLUSTER_ID_OR_NAME}/nodegroups/{NODEGROUP_ID_OR_NAME}
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID
CLUSTER_ID_OR_NAME	URL	UUID or String	O	Cluster UUID or cluster name
NODEGROUP_ID_OR_NAME	URL	UUID or String	O	Node group UUID or node group name
type	Body	String	O	Set to `flavor_id`
flavor_id	Body	String	O	Flavor UUID
num_buffer_nodes	Body	Integer	X	Number of buffer nodes. Minimum: 0, Maximum: (maximum number of nodes per worker node group - current number of nodes in that worker node group), Default: 1
num_max_unavailable_nodes	Body	Integer	X	Maximum number of unavailable nodes. Minimum: 1, Maximum: Current number of nodes in the worker node group, Default: 1)

Example

{
    "type": "flavor_id",
    "flavor_id": "1d0d6983-8e9d-44dc-810e-d7689afa372c",
    "num_buffer_nodes": 1,
    "num_max_unavailable_nodes":1
}

Response

Name	Type	Format	Description
uuid	Body	UUID	Node group UUID

Example

{
    "uuid": "018b06c5-1293-4081-8242-167a1cb9f262"
}

Other Features

See the Supported Kubernetes Versions

Retrieves the Kubernetes versions supported by NHN Kubernetes Service (NKS).

GET /v1/supports
Accept: application/json
Content-Type: application/json
OpenStack-API-Version: container-infra latest
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name	Type	Format	Required	Description
tokenId	Header	String	O	Token ID

Response

Name	Type	Format	Description
supported_k8s	Body	Object	Supported Kubernetes version object
supported_k8s."version name"	Body	String	Whether the Kubernetes version is valid or not (True/False)
supported_event_type."task type"	Body	Object	Supported task type objects (cluster_events/nodegroup_events)
supported_event_type."task type"."task name"	Body	Object	Task type and description

Example

{
    "supported_k8s": {
        "v1.17.6": false,
        "v1.18.19": false,
        "v1.19.13": false,
        "v1.20.12": false,
        "v1.21.6": false,
        "v1.22.3": false,
        "v1.23.3": false,
        "v1.24.3": false,
        "v1.25.4": true,
        "v1.26.3": true,
        "v1.27.3": true
        "v1.28.3": true
    },
    "supported_event_type": {
        "cluster_events": {
            "CLUSTER_CREATE": "Create a cluster",
            "CLUSTER_DELETE": "Delete a cluster",
            "CLUSTER_HANDOVER": "Cluster OWNER change",
            "CLUSTER_CNI_UPDATE": "Change CNI"
        },
        "nodegroup_events": {
            "NODEGROUP_CREATE": "Node group creation",
            "NODEGROUP_DELETE": "Delete a node group",
            "CLUSTER_RESIZE": "Resize the cluster",
            "NODEGROUP_UPDATE_FLAVOR": "Change instance type",
            "NODEGROUP_UPGRADE": "Upgrade a node group",
            "NODEGROUP_USERSCRIPT_UPDATE": "Change userscript",
            "NODEGROUP_SET_CLUSTER_AUTOSCALER": "Change Auto Scaler settings",
            "NODEGROUP_NODE_ACTION_NODE_START": "Start worker node",
            "NODEGROUP_NODE_ACTION_NODE_STOP": "Stop worker node"
        }
    }
}

Container > NHN Kubernetes Service (NKS) > API v2 Guide
Check the Information of Resources Used in API
UUID of the VPC Network Attached to the Internet Gateway
List of UUIDs of Subnets Attached to the Internet Gateway
VPC Network UUID
VPC Subnet UUID
Availability Zone UUID
Key Pair UUID
Base Image UUID
Block Storage Type
Flavor UUID
Cluster
List Clusters
Get a Cluster
View Task History List
List Task History
Create a Cluster
Delete a Cluster
Resize
Get kubeconfig of a Cluster
Change Cluster CNI
Enforce IP Access Control to Cluster API Endpoints
Get Cluster API Endpoint IP Access Control
Node Group
List Node Groups
Get a Node Group
Create a Node Group
Delete a Node Group
Stop a Node Group
Start a Node
View Autoscaler Configuration of a Node Group
Change Autoscaler Configuration of a Node Group
Upgrade a Cluster
Change User Script
Change Instance Flavor
Other Features
See the Supported Kubernetes Versions

TOP