Kubernetes Clusters on Hyperstack - API Guide

Hyperstack supports on-demand provisioning of managed Kubernetes clusters, providing a quick and efficient way to deploy and manage your containerized applications. Similar to other major cloud providers, you only need to specify the target Kubernetes version, node type, and a few basic parameters. The platform takes care of the rest, ensuring a streamlined and hassle-free experience.

In this document, you will find step-by-step instructions to create a Kubernetes cluster on Hyperstack. By following these guidelines, you will be able to leverage the full power of Kubernetes for orchestration, scalability, and management of your applications with minimal effort.

note

Hyperstack's on-demand Kubernetes is currently in Beta testing. There are a couple of limitations:

Cluster names must consist only of lowercase alphanumeric characters and hyphens. Uppercase letters, special characters, and spaces are not allowed.
Depending on the number of clusters being created, there may be a delay or a failure in cluster creation.
No (auto-)scaling is available for the cluster.
To view the details of the cluster, you need to use the API. We are working on a UI to display the cluster details.

How to create a Kubernetes cluster

1. Choose a supported Kubernetes cluster version

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/versions`

To obtain the Kubernetes cluster versions supported by Hyperstack, call the 'List Kubernetes Versions' endpoint. This will return a list of available versions, as shown in the example request. Choose the version you want to use for your Kubernetes cluster.

No parameters

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/versions" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"

Response
{
  "status": true,
  "message": "Retrieved Cluster Versions.",
  "kubernetes_version": [
    "1.27.8",
    ...
  ]
}

Save the supported Kubernetes version as it will be used in the next step to 'Create a Kubernetes cluster'.

2. Create a Kubernetes cluster

POST `https://infrahub-api.nexgencloud.com/v1/core/clusters`

To create a Kubernetes cluster, you need to specify its configuration details by completing the payload of the request with the required fields. These fields include information such as the cluster name, node type, Kubernetes version, hardware configuration, and other relevant parameters. Once you have filled out the payload with the necessary information, send the request to the /core/clusters API using the POST method to create the Kubernetes clusters with the provided configuration.

Please note: cluster creation can take between 5-20 minutes, depending on the cluster size and the number of clusters being created. You can check the status of the cluster by calling the 'Check cluster status' API. If your cluster is not in the ACTIVE state after 30 minutes, please remove the cluster and try again.

If you encounter an error due to insufficient permissions, ensure the following steps:

1: Check Account Role: Confirm that you’re not using an account without an assigned Role. Without proper permissions, you won’t be able to perform certain actions.

2: Admin Actions Required: Only Admins can assign Roles. If you’re not the Admin, ask them to:

Go to “My Organisation” in the Hyperstack WebUI.
Select “Create a new User role”, name it (e.g., “Operator”), and enable all permissions.

3: Assign Role:

In “My Organisation”, find your account.
Click “Change Role” and assign the newly created “Operator” role to your account.

See more details on User Roles here.

Request body parameters

name `string` Required

The name assigned to the Kubernetes cluster.

note

Cluster names must consist only of lowercase alphanumeric characters and hyphens. Uppercase letters, special characters, and spaces are not allowed.

environment_name `string` Required

The name of the environment where the cluster will be created.
To learn how to create a new environment, click here.

keypair_name `integer` Required

The name of the SSH key used to securely access your cluster.
To learn how to create a new SSH key, click here.

image_name `string` optional

Name of the operating system image to be installed on your cluster. Use the GET /core/images API to retrieve a list of images offered by Hyperstack.

Recommended image: `Ubuntu Server 22.04 LTS R535 CUDA 12.2`

kubernetes_version `string` Required

The Kubernetes cluster version you obtained in the previous step by calling the GET /core/clusters/versions API.

Recommended version: `1.27.8`

master_flavor_name `string` Required

The flavor of the master node determines its hardware configuration, including the CPUs, RAM, and disk storage capacity.

The master node requires a CPU-only flavor. Select the size that best suits your workload. Please note that there are no running costs associated with the resources consumed by the master node.

Click here to see the available CPU-only flavors and their hardware configurations

Flavor Name	CPU Cores	CPU Sockets	RAM (GB)	Disk (GB)
`n1-cpu-small`	4	2	4	100
`n1-cpu-medium`	8	2	8	100
`n1-cpu-large`	16	2	16	200

node_flavor_name `string` Required

The flavor used for the worker nodes which determines its hardware configuration, including the GPU model and quantity, CPUs, RAM, and disk storage capacity.
Call the GET /core/flavors API to retrieve a list of available flavors.

node_count `integer` Required

The number of worker nodes in the cluster.

Example request
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/clusters" \
  -H "accept: application/json"\
  -H "api_key: YOUR API KEY"\
  -H "content-type: application/json" \
  -d '{
    "name": "example-cluster",
    "environment_name": "example-environment",
    "keypair_name": "example-ssh-key",
    "image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
    "kubernetes_version": "1.27.8",
    "master_flavor_name": "",
    "node_flavor_name": "n3-A100x1",
    "node_count": 3
  }'

Response
{
  "status": true,
  "message": "Success",
  "cluster": {
    "id": 1,
    "name": "example-cluster",
    "environment_name": "example-environment",
    "kubernetes_version": "1.27.8",
    "api_address": "",
    "kube_config": "",
    "status": "CREATING",
    "status_reason": String,
    "node_count": 3,
    "node_flavor": {
        "name": "n3-A100x1",
        "cpu": 28,
        "ram": 120.0,
        "disk": 100,
        "ephemeral": 750,
        "gpu": "A100-80G-PCIe",
        "gpu_count": 1
    },
    "node_addresses": [""],
    "keypair_name": "example-ssh-key",
    "created_at": "2024-06-17T09:33:46",
  }
}

Save the cluster ID returned, as it will be used in the next step to 'Check cluster status'.

3. Check cluster status

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}`

The last step in deploying a cluster is to confirm that the cluster is ACTIVE and ready for use. To check its status, use the 'Retrieve Cluster Details' API, which provides information about the deployed cluster, including the status field indicating its operational state. Send the request to the /core/clusters/{id} API using the GET method, replacing {id}in the path with the clusterid` obtained in the previous step.

Path parameters

id `integer` Required

The ID of the cluster for which we are retrieving details.
This is obtained from the id field in the response of the `Create Cluster' API call from the previous step.

Attributes

Click here for descriptions of the fields within the cluster object.

id `integer`

The unique identifier assigned to the cluster.

name `string`

The name of the Kubernetes cluster.

environment name `string`

The name of the environment where the cluster is deployed.

kubernetes_version `string`

The version of Kubernetes running on the cluster.

kube_config `string`

A string representing the kubeconfig file contents required for connecting to the cluster.

status_reason `string`

A message providing information about the status of the cluster, especially in case of errors.

status `string`

The current status of the Kubernetes cluster.

Possible values:

CREATING: The cluster is being created.
ACTIVE: The cluster is active and operational.
ERROR: An error occurred during cluster creation or operation. Check the status_reason field for more details.

node_count `number`

The number of nodes (virtual machines) in the cluster.

node_flavor `object`

Details about the flavor (hardware configuration) of the nodes in the cluster.

node_addresses `array of strings`

A list of public IP addresses assigned to the nodes in the cluster.

keypair_name `string`

The name of the key pair used for SSH access to the nodes.

created_at `datetime`

The date and time when the cluster was created.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"

Response
{
  "status": true,
  "message": "Success",
  "cluster": {
    "id": 1,
    "name": "example-cluster",
    "environment_name": "example-environment",
    "kubernetes_version": "1.27.8",
    "kube_config": "",
    "status": "ACTIVE",
    "status_reason": String,
    "node_count": 3,
    "node_flavor": {
        "name": "n3-A100x1",
        "cpu": 28,
        "ram": 120.0,
        "disk": 100,
        "ephemeral": 750,
        "gpu": "A100-80G-PCIe",
        "gpu_count": 1
    },
    "node_addresses": [""],
    "keypair_name": "example-ssh-key",
    "created_at": "2024-06-17T09:33:46",
  }
}

A status of ACTIVE indicates that your cluster has been deployed successfully and is ready for use.

Other Kubernetes cluster APIs

Retrieve a list of clusters

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters`

Retrieve a list of your current clusters, providing detailed information for each, including configuration, cluster ID, operational status, environment, flavor (hardware configuration), and more.

Parameters

No parameters.

Attributes

status `boolean`

Indicates the success status of the API response.

message `string`

A description of the success or failure of the API request.

clusters `array of objects`

An array of objects containing information about Kubernetes clusters.

Click here to see child attributes

id `integer`

The unique identifier assigned to the cluster.

name `string`

The name of the Kubernetes cluster.

environment name `string`

The name of the environment where the cluster is deployed.

kubernetes_version `string`

The version of Kubernetes running on the cluster.

kube_config `string`

A string representing the kubeconfig file contents required for connecting to the cluster.

status `string`

The current status of the Kubernetes cluster.

Possible values:

CREATING: The cluster is being created.
ACTIVE: The cluster is active and operational.
ERROR: An error occurred during cluster creation or operation. Check the status_reason field for more details.

status_reason `string`

A message providing information about the status of the cluster, particularly useful in case of errors.

node_count `number`

The number of nodes (virtual machines) in the cluster.

node_flavor `object`

Details about the flavor (hardware configuration) of the nodes in the cluster.

Click here to see attributes

name `string`

The model name of the VM configuration.

cpu `integer`

The number of CPU cores.

ram `number`

The amount of RAM in GB.

disk `integer`

The size of the primary disk in GB.

ephemeral `integer`

The size of the ephemeral storage in GB.

gpu `string`

The GPU model.

gpu_count `integer`

The number of GPUs.

node_addresses `array of strings`

A list of public IP addresses assigned to the nodes in the cluster.

keypair_name `string`

The name of the key pair used for SSH access to the nodes.

created_at `datetime`

The date and time when the cluster was created.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"

Response
{
  "status": true,
  "message": "Success",
  "clusters": [
    {
      "id": 1,
      "name": "example-cluster",
      "environment_name": "example-environment",
      "kubernetes_version": "1.27.8",
      "kube_config": "",
      "status": "ACTIVE",
      "status_reason": String,
      "node_count": 3,
      "node_flavor": {
        "name": "n3-A100x1",
        "cpu": 28,
        "ram": 120.0,
        "disk": 100,
        "ephemeral": 750,
        "gpu": "A100-80G-PCIe",
        "gpu_count": 1
      },
      "node_addresses": [""],
      "keypair_name": "example-ssh-key",
      "created_at": "2024-06-17T09:33:46",
    },
    {...}
  ]
}

Delete a cluster

DELETE `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}`

To delete a cluster, include its ID in the path replacing the placeholder {id}`.

Path parameters

id `integer` Required

The ID of the cluster to be deleted.

Attributes

Example request
curl -X DELETE "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"

Response
{
  "status": true,
  "message": "Success"
}

Retrieve events for a cluster

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events`

Retrieve a complete history of events for a specified cluster by including its ID in the path replacing the placeholder {id}`. The returned cluster events provide detailed information about actions executed on the cluster, including the user, organization, time of the event, and specifics about what event took place and why.

Path parameters

id `integer` Required

The ID of the cluster for which to retrieve the event history.

Attributes

status `boolean`

Indicates whether the API call was successful.

message `string`

A message describing the result of the API call.

cluster_events `array of objects`

An array of event objects related to the specified cluster.

Click here to see child attributes

id `integer`

The unique identifier of the event.

cluster_id `integer`

The identifier of the cluster associated with the event.

user_id `integer`

The identifier of the user who triggered the event.

org_id `integer`

The organization identifier associated with the event.

time `datetime`

The timestamp when the event occurred.

type `string`

The type of the event.

reason `string`

The reason for the event, describing why the event was triggered.

object `string`

Additional details associated with the event.

message `string`

A descriptive message associated with the event, providing more details about what happened.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"

Response
{
  "status": true,
  "message": "Success",
  "cluster_events": [
    {
      "id": 1,
      "cluster_id": 2,
      "user_id": 3,
      "org_id": 4,
      "time": "",
      "type": "",
      "reason": "",
      "object": "",
      "message": ""
    },
    {...}
  ]
}

Kubernetes Clusters on Hyperstack - API Guide

In this article​

How to create a Kubernetes cluster​

1. Choose a supported Kubernetes cluster version​

GET https://infrahub-api.nexgencloud.com/v1/core/clusters/versions​

No parameters​

2. Create a Kubernetes cluster​

POST https://infrahub-api.nexgencloud.com/v1/core/clusters​

Request body parameters​

name string Required​

environment_name string Required​

keypair_name integer Required​

image_name string optional​

Recommended image: Ubuntu Server 22.04 LTS R535 CUDA 12.2​

kubernetes_version string Required​

Recommended version: 1.27.8​

master_flavor_name string Required​

node_flavor_name string Required​

node_count integer Required​

3. Check cluster status​

GET https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}​

Path parameters​

id integer Required​

Attributes​

id integer​

name string​

environment name string​

kubernetes_version string​

kube_config string​

status_reason string​

status string​

Possible values:​

node_count number​

node_flavor object​

node_addresses array of strings​

keypair_name string​

created_at datetime​

Other Kubernetes cluster APIs​

Retrieve a list of clusters​

GET https://infrahub-api.nexgencloud.com/v1/core/clusters​

Parameters​

Attributes​

status boolean​

message string​

clusters array of objects​

id integer​

name string​

environment name string​

kubernetes_version string​

kube_config string​

status string​

Possible values:​

status_reason string​

node_count number​

node_flavor object​

name string​

cpu integer​

ram number​

disk integer​

ephemeral integer​

gpu string​

gpu_count integer​

node_addresses array of strings​

keypair_name string​

created_at datetime​

Delete a cluster​

DELETE https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}​

Path parameters​

id integer Required​

Attributes​

Retrieve events for a cluster​

GET https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events​

Path parameters​

id integer Required​

Attributes​

status boolean​

message string​

cluster_events array of objects​

id integer​

cluster_id integer​

In this article

How to create a Kubernetes cluster

1. Choose a supported Kubernetes cluster version

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/versions`

No parameters

2. Create a Kubernetes cluster

POST `https://infrahub-api.nexgencloud.com/v1/core/clusters`

Request body parameters

name `string` Required

environment_name `string` Required

keypair_name `integer` Required

image_name `string` optional

Recommended image: `Ubuntu Server 22.04 LTS R535 CUDA 12.2`

kubernetes_version `string` Required

Recommended version: `1.27.8`

master_flavor_name `string` Required

node_flavor_name `string` Required

node_count `integer` Required

3. Check cluster status

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}`

Path parameters

id `integer` Required

Attributes

id `integer`

name `string`

environment name `string`

kubernetes_version `string`

kube_config `string`

status_reason `string`

status `string`

Possible values:

node_count `number`

node_flavor `object`

node_addresses `array of strings`

keypair_name `string`

created_at `datetime`

Other Kubernetes cluster APIs

Retrieve a list of clusters

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters`

Parameters

Attributes

status `boolean`

message `string`

clusters `array of objects`

id `integer`

name `string`

environment name `string`

kubernetes_version `string`

kube_config `string`

status `string`

Possible values:

status_reason `string`

node_count `number`

node_flavor `object`

name `string`

cpu `integer`

ram `number`

disk `integer`

ephemeral `integer`

gpu `string`

gpu_count `integer`

node_addresses `array of strings`

keypair_name `string`

created_at `datetime`

Delete a cluster

DELETE `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}`

Path parameters

id `integer` Required

Attributes

Retrieve events for a cluster

GET `https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}/events`

Path parameters

id `integer` Required

Attributes

status `boolean`

message `string`

cluster_events `array of objects`

id `integer`

cluster_id `integer`

user_id `integer`