How to use the STACKIT Kubernetes Engine API to manage your clusters

Apart from the STACKIT Cloud Portal, you can also use the STACKIT Kubernetes Engine (SKE) API directly to create and manage SKE projects and clusters. This guide introduces the API, describes how authentication is handled and shows example requests you can use to interact with your SKE resources.

If you are used to working with REST APIs by following OpenAPI specifications, you can look into our SKE OpenAPI specification to discover what endpoints are available and how to use them.

Authentication

To be able to use the SKE API, you need valid credentials. You can get credentials as follows:

User token

It is possible to use the token (short lifetime) of your user directly:

Copy the access\_token cookie value from a portal session and export it into $PORTAL\_TOKEN

export PORTAL_TOKEN="<access_token>"

Use the saved token in the Authorization header:

-H "Authorization: Bearer $PORTAL_TOKEN"

Service account

Additionally you can created a service account and assign it to the project.member group:

1. Navigate to Access > Service Accounts.
2. Create a new service account and copy it’s email address
3. Create a new access token by selecting the create service account and changing to the “Access tokens” sections.
4. Copy the token to a safe location.
5. Navigate to the Access > Permissions section and add the service account to the specific group by it’s email address

Getting started with the API using curl

An existing project is a required prerequisite for using the SKE API.

Currently, creating a new project is only possible via the STACKIT Cloud Portal. Note that the name of a project is not the same as its ID. The ID is a long alphanumeric sequence that has the following form: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX

You can get your project’s ID from the project dashboard page, in the Project Information panel.

Now you are ready to get started.

Listing clusters

Use the following command to list your existing SKE clusters:

curl -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/clusters

The expected response (when you have no preexisting clusters in the project) looks as follows:

HTTP/1.1 200 OK

{
 "items": []
}

If you already had SKE cluster in the project, they will be shown in their JSON representation.

Creating a cluster

Having validated that we can communicate with the API, we can now create a cluster. In order to do this, we need a cluster specification in the JSON format. Have a look at the following data and save it in a file called cluster.json:

This is an example for a minimal specification of a SKE cluster. Do not use this in production!

{
  "kubernetes": {
    "version": "1.25.12"
  },
  "nodepools": [{
    "name": "pool0",
    "machine": {
      "type": "c1.2",
      "image": {
        "name": "flatcar",
        "version": "3510.2.6"
      }
    },
    "minimum": 1,
    "maximum": 2,
    "maxSurge": 1,
    "maxUnavailable": 0,
    "volume": {
      "type": "storage_premium_perf1",
      "size": 20
    },
    "cri": {
      "name": "containerd"
    },
    "availabilityZones": [
      "eu01-1"
    ]
  }],
  "maintenance": {
    "autoUpdate": {
      "kubernetesVersion": true,
      "machineImageVersion": true
    },
    "timeWindow": {
      "start": "0000-01-01T02:00:00Z",
      "end": "0000-01-01T03:00:00Z"
    }
  }
}

This is an example for a minimal specification of a SKE cluster, containing needed data such as the Kubernetes version and one node pool object. We can also define maintenance characteristics such as the time window for updates (between 2am and 3am in our example) and if both the Kubernetes and the machine image versions should be updated in this window.

If you follow this guide the above specified versions (Kubernetes and operating system) could already be deprecated and removed. To ensure up to date versions you can get the current provider-options with:

curl -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/provider-options

Assuming you have saved the file as cluster.json in the current directory, you can now use the following command to create the cluster:

curl -X PUT --data "@cluster.json" -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/clusters/demo

The cluster will be named like the name specified in the path (in our case “demo”).

The expected response looks as follows:

HTTP/1.1 202 Accepted

{
  "name": "demo",
  "kubernetes": {}, // omitted for brevity
  "nodepools": [...], // omitted for brevity
  "maintenance": {...}, // omitted for brevity
  "hibernation": null,
  "extensions": {},
  "status": {
      "hibernated": false,
      "aggregated": "STATE_CREATING",
      "error": null
  }
}

As you can see, our cluster creation request got accepted, and the cluster is in the creation phase. You can also use this endpoint to update a cluster.

Getting a specific cluster

As the creation of a cluster can take some time, we can now check the cluster status.

curl -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/clusters/demo

The expected response, once the cluster creation is completed:

HTTP/1.1 200 OK

{
    "name": "demo",
    "kubernetes": {}, // omitted for brevity
    "nodepools": [...], // omitted for brevity
    "maintenance": {...}, // omitted for brevity
    "hibernation": null,
    "extensions": {},
    "status": {
    "hibernated": false,
    "aggregated": "STATE_HEALTHY",
    "error": null
  }
}

Getting a kubeconfig

To access the kubeconfig of your created clusters:

curl -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/clusters/demo/credentials

Deleting a cluster

To complete the cluster lifecycle, we will remove the demo cluster we just created using the DELETE method.

curl -X DELETE -H "Authorization: Bearer $PORTAL_TOKEN" https://ske.api.eu01.stackit.cloud/v1/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/clusters/demo

The expected response is the accepted deletion request with an empty cluster object:

HTTP/1.1 202 Accepted

{}

The cluster is now in deletion. You can track the progress of the deletion using the instructions above for “Getting a Specific Cluster”. If the request returns a Status 404, the cluster has been successfully removed.

Advanced API usage

You can also use the SKE API to accomplish the following tasks:

• Hibernating/waking up a cluster
• Reconciling a cluster
• Starting a maintenance window
• Rotating cluster credentials
• etc.

For the corresponding endpoint specifications, please have a look at our OpenAPI specification.