NAV Navbar
http

Introduction

Welcome to the kubegrid API! You can use our API to access kubegrid API endpoints, through which you can control your cluster infrastructure and services.

API Token

In order to use the kubegrid API, you'll need to include an API token in the Authorization header.

First, generate an API token as described here. The value to place in the Authorization header is the string "Bearer" in front of the API token. For example, if the token value is "abcdefg", the Authorization header should contain "Bearer abcdefg".

Hosting Providers

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: Amazon Web Services (AWS), Azure, Google Cloud Platform (GCP), Linode, and self-managed servers.

For instructions on locating the required credentials for each hosting provider, please see the reference page for finding hosting provider credentials.

Create a Hosting Provider

POST a json to

"https://api.kubegrid.com/v1/hosting-providers"

For AWS, the paylod must contain the following fields (values provided are examples):

{
    "provider_name": "aws",
    "region": "us-west-1",
    "api_key": "foo",
    "api_secret": "bar"
}

For Azure, the payload must contain the following fields (values provided are examples):

{
    "provider_name": "azure",
    "api_key": "my-key-value",
    "credential_json": "{
        arm_client_id: "client_id",
        arm_client_secret: "client_secret",
        arm_subscription_id: "sub_id",
        arm_tenant_id: "tenant_id",
    }",
    "region": "EastUS2"
}

For GCP, the payload must contain the following fields (values provided are examples):

{
    "provider_name": "gcp",
    "region": "asia-east2",
    "api_key": "foo",
    "credential_json": <the credential json you got from GCP>
}

For Linode, the payload must contain the following fields (values provided are examples):

{
    "provider_name": "linode",
    "region": "us-central",
    "api_secret": "foo",
}

For self-managed servers, see the "Server Pools" section of this page.

This endpoint will create a hosting provider record. Upon success, a response will be generated with status code 201 with a JSON payload which contains an id field. This is the hosting provider id to be used when creating a cluster.

HTTP Request

POST https://api.kubegrid.com/v1/hosting-providers

Payload Parameters

Required parameters vary by hosting provider. Please see examples in the right pane.

The following table lists the valid values for the region parameter by hosting provider.

AWS Azure GCP Linode
us-east-1 EastUS asia-east1 ca-central
us-east-2 EastUS2 asia-east2 us-central
us-west-1 WestUS asia-northeast1 us-west
us-west-2 WestUS2 asia-south1 us-southeast
ca-central-1 CentralUS asia-southeast1 us-east
eu-west-1 NorthCentralUS australia-southeast1 eu-west
eu-west-2 SouthCentralUS europe-north1 eu-central
eu-central-1 NorthEurope europe-west1 ap-south
ap-northeast-1 WestEurope europe-west2 ap-northeast
ap-northeast-2 EastAsia europe-west3
ap-northeast-3 SoutheastAsia europe-west4
ap-southeast-1 JapanEast northamerica-northeast1
ap-southeast-2 JapanWest southamerica-east1
ap-south-1 AustraliaEast us-central1
sa-east-1 AustraliaSoutheast us-east1
BrazilSouth us-east4
SouthIndia us-west1
CentralIndia us-west2
WestIndia
CanadaCentral
CanadaEast
WestCentral US
UKSouth
UKWest
KoreaCentral
KoreaSouth

List All Hosting Providers

Send a GET request to:

"https://api.kubegrid.com/v1/hosting-providers"

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data": [
        {
            "id": 19,
            "name": null,
            "provider_id": 1,
            "provider_name": "AWS (Amazon Web Services)",
            "provider": {
                "id": 1,
                "name": "AWS (Amazon Web Services)",
                "api_url": "https://api.aws.com",
                "active": 1,
                "mixed_os": 1,
                "created_at": null,
                "updated_at": null,
                "slug": "aws"
            },
            "server_pool_id": null,
            "region": "us-west-1",
            "active": 1,
            "created_at": 1561093717,
            "api_key": "foo",
            "api_secret": "bar",
            "credential_json": []
        },
    ]
}

This endpoint return all of your configured hosting providers.

HTTP Request

GET https://api.kubegrid.com/v1/hosting-providers

Retrieve a Hosting Provider by ID

Send a GET request to:

"https://api.kubegrid.com/v1/hosting-providers/{id}"

Upon success, a response with status code 200 will be returned along with the hosting provider details in JSON format:

{
    "data": {
        "id": 19,
        "name": null,
        "provider_id": 1,
        "provider_name": "AWS (Amazon Web Services)",
        "provider": {
            "id": 1,
            "name": "AWS (Amazon Web Services)",
            "api_url": "https://api.aws.com",
            "active": 1,
            "mixed_os": 1,
            "created_at": null,
            "updated_at": null,
            "slug": "aws"
        },
        "server_pool_id": null,
        "region": "us-west-1",
        "active": 1,
        "created_at": 1561093717,
        "api_key": "foo",
        "api_secret": "bar",
        "credential_json": []
    },
}

This endpoint will retrieve details of a single hosting provider.

HTTP Request

GET https://api.kubegrid.com/v1/hosting-providers/{id}

Query Parameters

Parameter Description
id The ID of the hosting provider to be deleted (this value was returned in response to the POST call to create the hosting provider)

Delete a Hosting Provider

Send a DELETE request to:

"https://api.kubegrid.com/v1/hosting-providers/{id}"

Upon success, a response with status code 204 will be returned

This endpoint will delete a hosting provider.

HTTP Request

DELETE https://api.kubegrid.com/v1/hosting-providers/{id}

Query Parameters

Parameter Description
id The ID of the hosting provider to be deleted (this value was returned in response to the POST call to create the hosting provider)

Self-Managed Hosting

When using the "self-managed" hosting provider, your available servers are organized into server pools (e.g. prod, staging, dev, etc). When you create a cluster, you'll choose the server pool from which the cluster can reserve servers, so you must create a Server Pool before you can create a cluster.

Create a Server Pool

POST a json with the following fields to:

"https://api.kubegrid.com/v1/server-pools"

[
  {
    "name": "your-pool-name"
  }
]

The above request return a response with status code 201 and a JSON structured like this:

{
    "data":
    {
        "id":30,
        "hosting_provider_id":6,
        "name":"your-pool-name",
        "servers":[],
        "created_at":000000000
    }
}

This endpoint will create a new named pool to which you can add specific servers.

HTTP Request

POST https://api.kubegrid.com/v1/server-pools

Payload Parameters

Parameter Description
name The display name for the new server pool.

Delete a Server Pool

You cannot delete a server pool directly -- instead, delete the associated hosting provider.

Add Server to Server Pool

POST a json with the following fields to:

"https://api.kubegrid.com/v1/self-managed-servers"

{
    "public_ip":"200.0.0.1",
    "private_ip":"10.0.0.1",
    "os":"linux",
    "ssh_user":"core",
    "ssh_password":"password",
    "ssh_key":"-----BEGIN RSA PRIVATE KEY-----\nprivate-key\n-----END RSA PRIVATE KEY-----",
    "server_pool_id":30
}

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data":
    {
        "id":48,
        "in_use":false,
        "tf_index":null,
        "tf_type":null,
        "os":"linux",
        "private_ip":"10.0.0.1",
        "public_ip":"200.0.0.1",
        "ssh_user":"core"
    }
}

This endpoint will add a new server to the specified server pool.

HTTP Request

POST https://api.kubegrid.com/v1/self-managed-servers

Payload Parameters

Parameter Description
public_ip The public IPv4 address for the server.
private_ip The private IPv4 address for the server.
os Operating system on the server. Currently only "linux" is supported.
ssh_user Username for SSH access.
ssh_password Password for SSH access.
ssh_key Private key for SSH access.
server_pool_id ID of the server pool to which this server will be added, as returned from the call to /server-pools.

Add Server to Server Pool with Copied Credientials

POST a json with the following fields to

"https://api.kubegrid.com/v1/self-managed-servers"

{
    "server_pool_id":30,
    "public_ip":"200.0.0.2",
    "private_ip":"10.0.0.2",
    "os":"linux",
    "copy_from":
    {
        "id": 48
    }
}

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data":
    {
        "id":48,
        "in_use":false,
        "tf_index":null,
        "tf_type":null,
        "os":"linux",
        "private_ip":"10.0.0.2",
        "public_ip":"200.0.0.2",
        "ssh_user":"core"
    }
}

You can add a server to a server pool, but instead of supplying SSH credentials, you can specify that the credentials be copied from an already-existing server in that server pool.

HTTP Request

POST https://api.kubegrid.com/v1/self-managed-servers

Payload Parameters

Parameter Description
server_pool_id ID of the server pool to which this server will be added, as returned from the call to /server-pools.
public_ip The public IPv4 address for the server.
private_ip The private IPv4 address for the server.
os Operating system on the server. Currently only "linux" is supported.
ssh_user Any string.
ssh_key Any string.
copy_from.id The ID of the server from which to copy credentials.

List Servers in a Server Pool

Send a GET request to:

"https://api.kubegrid.com/v1/server-pools/{server-pool-id}"

Upon success, a response with status code 200 will be returned with a JSON structured like this (values are example):

{
    "data":
    {
        "id":30,
        "name":"your-pool-name",
        "servers":[
            {
                "id":48,
                "in_use":false,
                "tf_index":null,
                "tf_type":null,
                "os":"linux",
                "private_ip":"10.0.0.1",
                "public_ip":"200.0.0.1",
                "ssh_user":"core"
            },
            {
                "id":49,
                "in_use":false,
                "tf_index":null,
                "tf_type":null,
                "os":"linux",
                "private_ip":"10.0.0.2",
                "public_ip":"200.0.0.2",
                "ssh_user":"core"
            }
        ],
        "created_at":1560040105
    }
}

This endpoint will retrieve all the servers associated with the provided server pool ID.

HTTP Request

GET https://api.kubegrid.com/v1/server-pools/{server-pool-id}

Payload Parameters

Parameter Description
server-pool-id ID of the server pool.

Remove a Server from a Server Pool

Send a DELETE request to:

"https://api.kubegrid.com/v1/self-managed-servers/{id}"

Upon success, a response with status code 204 will be returned.

This endpoint removes a server from its server pool.

HTTP Request

DELETE https://api.kubegrid.com/v1/self-managed-servers/{id}

Query Parameters

Parameter Description
id The ID of the server to be removed

List All Servers for All Server Pools

Send a GET request to:

"https://api.kubegrid.com/v1/self-managed-servers"

Upon success, a response with status code 200 will be returned with a JSON structured like this (values are example):

{
    "data": [
        {
            "id":48,
            "server_pool_id":30,
            "in_use":false,
            "tf_index":null,
            "tf_type":null,
            "os":"linux",
            "private_ip":"10.0.0.1",
            "public_ip":"200.0.0.1",
            "ssh_user":"core"
        },
        {
            "id":50,
            "server_pool_id":31,
            "in_use":false,
            "tf_index":null,
            "tf_type":null,
            "os":"linux",
            "private_ip":"10.0.0.3",
            "public_ip":"200.0.0.3",
            "ssh_user":"core"
        }
    ]
}

This endpoint will retrieve all the servers associated with any server pool.

HTTP Request

GET https://api.kubegrid.com/v1/self-managed-servers

Clusters

Create a Cluster

POST a json with the following fields to:

"https://api.kubegrid.com/v1/clusters"

{
    "hosting_provider_id":14,
    "kubernetes":
    {
        "cluster_name":"my-cluster-name",
        "master_size":"small",
        "master_storage":30,
        "worker_size":"micro",
        "worker_storage":30,
        "worker_count":2,
        "worker_size_windows":"medium",
        "worker_storage_windows":50,
        "worker_count_windows":0,
        "use_web_ui":true
    }
}

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data":
    {
        "id":15,
        "uuid":"kgid4P-my-cluster-name",
        "name":"my-cluster-name",
        "vpc_cidr":"189.73.0.0\/16",
        "status":"building",
        "master_ips":null,
        "token":null,
        "dashboard":"client-kgid4p-my-cluster-name.pushtrain.net",
        "updated_at":1560041484,
        "created_at":1560041476,
        "build_info":
        {
            "id":62,
            "team_name":"main",
            "name":"1",
            "status":"pending",
            "job_name":"create-infrastructure",
            "api_url":"\/api\/v1\/builds\/62",
            "pipeline_name":"kgid4P-my-cluster-name"
        }
    }
}

This endpoint will create a Kubernetes cluster using the specified hosting provider. If this is a self-managed provider, it will reserve servers from the server pool so that they won't be used by other clusters created on the same server pool. If this is a cloud provider, it will create new compute instances using that hosting provider. For all providers, this call will set up Kubernetes.

HTTP Request

POST https://api.kubegrid.com/v1/clusters

Payload Parameters

Parameter Description
hosting_provider_id ID of the hosting provider associated with the server pool, as returned by the POST call to /hosting-providers.
vpc_cidr Ignored.
kubernetes.cluster_name Display name for your new cluster.
kubernetes.master_size Instance size for Kubernetes master node. See table below for options. Ignored for self-managed hosting provider.
kubernetes.master_storage Gigabytes of storage to allocate to the Kubernetes master node. Ignored for self-managed hosting provider.
kubernetes.worker_size Instance size for Kubernetes linux worker nodes. See table below for options. Ignored for self-managed hosting provider. Optional if worker_count is zero.
kubernetes.worker_storage Gigabytes of storage to allocate to each Kubernetes linux worker node. Ignored for self-managed hosting provider. Optional if worker_count is zero.
kubernetes.worker_count Number of worker servers to use in the cluster. Optional.
kubernetes.worker_size_windows Instance size for Kubernetes Windows worker nodes. See table below for options. Only available for AWS, Azure, and GCP.
kubernetes.worker_storage_windows Gigabytes of storage to allocate to each Kubernetes Windows worker node. Only available for AWS, Azure, and GCP.
kubernetes.worker_count_windows Number of Windows-based worker nodes to use in the cluster. Only available for AWS, Azure, and GCP.
kubernetes.use_web_ui If true, will deploy the Kubernetes Dashboard UI onto your cluster.
Size CPUs RAM (GB) AWS Azure GCP Linode
nano 1 0.5 t2.nano N/A N/A N/A
micro 1 1 t2.micro Standard_B1s custom-1-1024 g6-nanode-1
small 1 2 t2.small Standard_B1ms custom-1-2048-ext g6-standard-1
medium 2 4 t2.medium Standard_B2s custom-2-4096-ext g6-standard-2
large 2 8 t2.large Standard_B2ms n1-standard-2 g6-standard-4
xlarge 4 16 t2.xlarge Standard_B4ms n1-standard-4 g6-standard-6
2xlarge 8 32 t2.2xlarge Standard_B8ms n1-standard-8 g6-standard-8

List All Clusters

Send a GET request to:

"https://api.kubegrid.com/v1/clusters"

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data": [
        {
            "id":15,
            "uuid":"kgid4P-my-cluster-name",
            "name":"my-cluster-name",
            "vpc_cidr":"189.73.0.0\/16",
            "status":"running",
            "master_ips":["11.22.33.44"],
            "token":null,
            "dashboard":"client-kgid4p-my-cluster-name.pushtrain.net",
            "updated_at":1560041484,
            "created_at":1560041476,
            "build_info":
            {
                "id":62,
                "team_name":"main",
                "name":"1",
                "status":"completed",
                "job_name":"create-infrastructure",
                "api_url":"\/api\/v1\/builds\/62",
                "pipeline_name":"kgid4P-my-cluster-name"
            }
        },
        {
            "id":18,
            "uuid":"koae8J-my-cluster-name2",
            "name":"my-cluster-name2",
            "vpc_cidr":"189.75.0.0\/16",
            "status":"building",
            "master_ips":null,
            "token":null,
            "dashboard":"client-koae8J-my-cluster-name.pushtrain.net",
            "updated_at":1560051484,
            "created_at":1560051476,
            "build_info":
            {
                "id":65,
                "team_name":"main",
                "name":"1",
                "status":"pending",
                "job_name":"create-infrastructure",
                "api_url":"\/api\/v1\/builds\/62",
                "pipeline_name":"koae8J-my-cluster-name2"
            }
        },
    ]
}

This endpoint return details on all of your clusters.

HTTP Request

GET https://api.kubegrid.com/v1/clusters

Retrieve A Single Cluster By ID

Send a GET request to:

"https://api.kubegrid.com/v1/clusters/{id}"

Upon success, a response with status code 201 will be returned with a JSON structured like this (values are example):

{
    "data": {
        "id":15,
        "uuid":"kgid4P-my-cluster-name",
        "name":"my-cluster-name",
        "vpc_cidr":"189.73.0.0\/16",
        "status":"running",
        "master_ips":null,
        "token":null,
        "dashboard":"client-kgid4p-my-cluster-name.pushtrain.net",
        "updated_at":1560041484,
        "created_at":1560041476,
        "build_info":
        {
            "id":62,
            "team_name":"main",
            "name":"1",
            "status":"completed",
            "job_name":"create-infrastructure",
            "api_url":"\/api\/v1\/builds\/62",
            "pipeline_name":"kgid4P-my-cluster-name"
        }
    }
}

This endpoint returns details on the specified cluster

HTTP Request

GET https://api.kubegrid.com/v1/clusters/{id}

Query Parameters

Parameter Description
id The ID of the cluster for which to retrieve details

Delete a Cluster

Send a DELETE request to:

"https://api.kubegrid.com/v1/clusters/{id}"

Upon success, a response with status code 204 will be returned.

This endpoint deletes a specified cluster.

HTTP Request

DELETE https://api.kubegrid.com/v1/clusters/{id}

Query Parameters

Parameter Description
id The ID of the cluster to be deleted

Retrieve Cluster Access Information

kube.config File

Send a GET request to:

"https://api.kubegrid.com/v1/clusters/{cluster_id}/kubeconfig"

Upon success, a response with status code 200 will be returned with a plain text body containing the contents of the kubeconfig file.

You can retrieve the kube.config file for your cluster via the following endpoint.

HTTP Request

GET https://api.kubegrid.com/v1/clusters/{id}/kubeconfig

Query Parameters

Parameter Description
id The ID of the cluster for which to retrieve the kubeconfig file

SSH Key

Send a GET request to:

"https://api.kubegrid.com/v1/clusters/{id}/ssh"

Upon success, a response with status code 200 will be returned with plain text body containing the SSH key.

You can retrieve the SSH key for your cluster via the following endpoint.

HTTP Request

GET https://api.kubegrid.com/v1/clusters/{id}/ssh

Query Parameters

Parameter Description
id The ID of the cluster for which to retrieve the SSH key

Windows Password

Send a GET request to:

"https://api.kubegrid.com/v1/clusters/{id}/windows_pw"

Upon success, a response with status code 200 will be returned with plain text body containing the password.

You can retrieve the password for logging in to Windows nodes in your cluster via the following endpoint.

HTTP Request

GET https://api.kubegrid.com/v1/clusters/{id}/windows_pw

Query Parameters

Parameter Description
id The ID of the cluster for which to retrieve the Windows password

Add Nodes to a Cluster

POST a JSON with the following fields to:

"https://api.kubegrid.com/v1/clusters/{id}/nodes"

{
    "linux":2,
    "windows":0
}

Upon success, a response with status code of 200 will be returned.

This endpoint adds the specified number of linux and/or Windows nodes to the specified cluster. For Linux nodes, the specified number may be negative, which will remove nodes from a cluster.

HTTP Request

POST https://api.kubegrid.com/v1/clusters/{id}/nodes

Query Parameters

Parameter Description
id The ID of the cluster to which to add nodes

Payload Parameters

Parameter Description
linux The number of linux nodes to add. Optional. If included, may be either positive or negative.
windows The number of Windows nodes to add. Optional. If included, must be positive.

List a Cluster's Nodes

Send a GET request to:

"https://api.kubegrid.com/v1/clusters/{id}/nodes"

Upon success, a response with status code 200 will be returned with a JSON containing details for each node in the cluster.

This endpoint retrieves details for all the nodes that are part of a specified cluster.

HTTP Request

GET https://api.kubegrid.com/v1/clusters/{id}/nodes

Query Parameters

Parameter Description
id The ID of the cluster for which to enumerate nodes