Creating a Kubernetes Cluster Using the kubegrid API

Kubegrid provides an API that allows you to create and manage Kubernetes clusters via code instead of using the kubegrid web UI. This tutorial will walk you through creating a Kubernetes cluster using the kubegrid API, assuming you have created a kubegrid account. The API documentation is available here.

API Token

The first step in the process is to use the kubegrid web UI to generate an API token. This is the only step that uses the kubegrid web UI. See the API token documentation page for instructions on how to generate a new API token.

In all API calls that you make, set the Authorization header to: “Bearer <your-token-value>”. For example, if the token value was “abcde12345”, set the Authorization header to “Bearer abcde12345”.

Set Up Hosting Provider Configuration

Clusters are created on a specified hosting provider, so before you can create a cluster, you must first create a hosting provider. Supported hosting providers include: AWS, Azure, Google Cloud Platform, Linode, and self-managed servers. This tutorial will use AWS. The JSON payload for the call to create a hosting provider record will have varying required content depending on the hosting provider you are using. Please see the API documentation for details on required payload content for each hosting provider.

For this tutorial, we’ll be using Postman to call the API. However, you can use whatever method you’d like to generate and send HTTPS requests.

Creating a hosting provider is done by making a call to the hosting-providers endpoint with the payload applicable for your hosting provider. Below is a snapshot of our call to the hosting-providers endpoint.

Upon making this call, we’ll receive a response which contains our hosting provider information, including its id. Make note of this value, as we’ll use it in the call to create our Kubernetes cluster. For this tutorial, we’ll assume the value is 1.

Create Kubernetes Cluster

To create a cluster, you will POST a JSON to https://api.kubegrid.com/v1/clusters. This JSON defines key characteristics of your cluster, including: the hosting provider on which to build the cluster, the instance size and storage allocation for the master node, the number of Linux worker nodes and their respective size and storage allocation, the number of Windows worker nodes and their respective size and storage allocation, and whether or not to include the Kubernetes Web UI (Dashboard) in the deployment.

See the kubegrid API documentation for details on the values in this POST call. Below is a snapshot of our example call to the clusters endpoint.

The server will return a response containing the id of your cluster, among other information. This cluster ID can be used to query for more information about your cluster.

Cluster Nodes

Now that you’ve created a cluster, you want to see the details of the nodes that comprise it, such as their IP addresses. You can list the details of all the nodes in the cluster with the cluster/{id}/nodes endpoint. This will return a plethora of information about each node in the cluster, including its hostname and IP address.

Access Your Cluster

You will also want to know how to access the cluster. The kubegrid API exposes two ways to do this: directly log into the node(s) or use a kubeconfig file with kubectl.

Log In to Nodes

For either Windows or Linux-based nodes on most cloud providers, the username will be core. For Azure-based clusters, the username will be azureuser.

For Linux-based nodes, you can log in using an SSH key. The SSH key can be accessed via the clusters/{id}/ssh endpoint. A GET call to this endpoint will return a plaintext response with the SSH key. Save this to a file and use it to log into any of the Linux-based nodes in your cluster. The master node is always Linux-based, regardless of whether the workers nodes are Linux or Windows-based.

For Windows-based nodes, you can log in using Windows Remote Desktop or winrm. The password can be accessed via the clusters/{id}/windows_pw endpoint. A GET call to this endpoint will return a plaintext response with the password.

Get kubeconfig

You can retrieve the kubeconfig file for your cluster for use with kubectl via the clusters/{id}/kubeconfig endpoint. A GET call to this endpoint will return a plaintext response with the contents of the kubeconfig file. Save this information to a file and use it with kubectl to control your Kubernetes cluster.