Skip to content

Create a Cluster Using the KKP API

Introduction

This guide shows how to interact with the KKP API to create a cluster. You will use a KKP service account (SA) and its token to authenticate, verify the access, and then provision a new Kubernetes cluster using the KKP API.

Step 0: Prerequisites

This guide uses the following command-line tools:

  • curl: Used to send HTTP requests to the KKP API.
  • jq: Used to parse and pretty-print JSON responses from API calls.

Ensure they are installed locally.

Download the following templates and store them in a dedicated folder:

  • cluster-no-md.json: Used to provision a cluster with no initial MachineDeployment.
  • add-md.json: Used to add a MachineDeployment to a cluster using the KKP API.
  • cluster-with-md.json: Used to provision a cluster with an initial MachineDeployment.
  • add-md-k8s-api.yaml: Used to add a MachineDeployment to a cluster using the cluster's Kubernetes API.

You can use the below command to download all the templates at once:

curl --remote-name-all \
  https://cloud.switch.ch/-/documentation/kubernetes/guides/create-a-cluster-using-the-kkp-api/cluster-no-md.json \
  https://cloud.switch.ch/-/documentation/kubernetes/guides/create-a-cluster-using-the-kkp-api/add-md.json \
  https://cloud.switch.ch/-/documentation/kubernetes/guides/create-a-cluster-using-the-kkp-api/cluster-with-md.json \
  https://cloud.switch.ch/-/documentation/kubernetes/guides/create-a-cluster-using-the-kkp-api/add-md-k8s-api.yaml

Or copy and paste them from below:

cluster-no-md.json 
{
  "cluster": {
    "name": "cluster-no-md",
    "spec": {
      "cloud": {
        "openstack": {
          "floatingIPPool": "public"
        },
        "dc": "scc-zhw"
      },
      "version": "1.33.3",
      "kubernetesDashboard": {
        "enabled": true
      },
      "enableUserSSHKeyAgent": true,
      "exposeStrategy": "LoadBalancer",
      "clusterNetwork": {
        "ipFamily": "IPv4",
        "proxyMode": "ebpf"
      },
      "cniPlugin": {
        "type": "cilium",
        "version": "1.16.9"
      }
    },
    "credential": "<provider_preset>"
  }
}
add-md.json 
{
  "name": "initial-machinedeployment",
  "annotations": {
    "k8c.io/operating-system-profile": "osp-ubuntu"
  },
  "spec": {
    "template": {
      "cloud": {
        "openstack": {
          "flavor": "c002r002",
          "image": "Ubuntu 24.04 (Switch Cloud)",
          "diskSize": 20
        }
      },
      "versions": {
        "kubelet": "1.33.3"
      },
      "operatingSystem": {
        "ubuntu": {
          "distUpgradeOnBoot": true
        }
      }
    },
    "replicas": 1
  }
}
cluster-with-md.json 
{
  "cluster": {
    "name": "cluster-with-md",
    "spec": {
      "cloud": {
        "openstack": {
          "floatingIPPool": "public"
        },
        "dc": "scc-zhw"
      },
      "version": "1.33.3",
      "kubernetesDashboard": {
        "enabled": true
      },
      "enableUserSSHKeyAgent": true,
      "exposeStrategy": "LoadBalancer",
      "clusterNetwork": {
        "ipFamily": "IPv4",
        "proxyMode": "ebpf"
      },
      "cniPlugin": {
        "type": "cilium",
        "version": "1.16.9"
      }
    },
    "credential": "<provider_preset>"
  },
  "nodeDeployment": {
    "name": "initial-machinedeployment",
    "annotations": {
      "k8c.io/operating-system-profile": "osp-ubuntu"
    },
    "spec": {
      "template": {
        "cloud": {
          "openstack": {
            "flavor": "c002r002",
            "image": "Ubuntu 24.04 (Switch Cloud)",
            "diskSize": 20
          }
        },
        "versions": {
          "kubelet": "1.33.3"
        },
        "operatingSystem": {
          "ubuntu": {
            "distUpgradeOnBoot": true
          }
        }
      },
      "replicas": 1
    }
  }
}
add-md-k8s-api.yaml 
apiVersion: cluster.k8s.io/v1alpha1
kind: MachineDeployment
metadata:
  annotations:
    k8c.io/operating-system-profile: osp-ubuntu
  name: initial-machinedeployment
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      machine: initial-machinedeployment
  template:
    metadata:
      labels:
        machine: initial-machinedeployment
    spec:
      providerSpec:
        value:
          cloudProvider: openstack
          cloudProviderSpec:
            flavor: c002r002
            image: Ubuntu 24.04 (Switch Cloud)
            identityEndpoint: https://identity.api.zhw.cloud.switch.ch/v3
            region: zhw
            network: kubernetes-<cluster_id>
            rootDiskSizeGB: 20
          operatingSystem: ubuntu
          operatingSystemSpec:
            distUpgradeOnBoot: true
      versions:
        kubelet: 1.33.3

Step 1: Create a KKP Service Account

Log in to SCK, select your project, navigate to the Access > Service Accounts tab and click Create Service Account. Enter a Name for your service account, and select the Editor group. Click Create Service Account to finalize the SA creation. Your newly created SA should now be listed in the Service Accounts table.

Add a token for your SA by clicking the plus icon on the far right of your SA row. Enter a Name for your token and click Add Token. Your token is now displayed in a popup window. Download the token and store it securely on your device. The token will not be displayed again. By default, the token expires in 3 years. You can always regenerate the token or delete it if needed using the buttons on the far right of an SA row.

Step 2: Verify the Access and Get Project Credentials

All API requests to the KKP API require authentication using a bearer token. To use the API, you will need to include an Authorization header with each request.

First, set the environment variable to the contents of your service account token file:

export KKP_TOKEN=$(< <path_to_your_token_file>)

You can now verify the access by retrieving project_id and the Provider Preset (you will need both to create a cluster).

Retrieve project_id:

curl --silent --request GET \
     --header "Authorization: Bearer ${KKP_TOKEN}" \
     "https://sck.cloud.switch.ch/api/v1/projects" \
| jq --raw-output '.[].id'
Example output 
sck-gtxhx

Retrieve the Provider Preset:

curl --silent --request GET \
     --header "Authorization: Bearer ${KKP_TOKEN}" \
     "https://sck.cloud.switch.ch/api/v2/projects/<project_id>/presets" \
| jq --raw-output '.items[].name'
Example output 
sck-gtxhx-ztrxw

Step 3: Create a Cluster with no Initial MachineDeployment

You can provision a cluster with no initial MachineDeployment by sending a POST request to the API endpoint using curl. The request includes a JSON payload file from Step 0 that defines the cluster configuration. Before sending the request, replace the <provider_preset> placeholder in the payload file, and the <project_id> placeholder in the request itself with the relevant values retrieved in Step 2.

curl --silent --request POST \
     --header "Authorization: Bearer ${KKP_TOKEN}" \
     --data @cluster-no-md.json \
     "https://sck.cloud.switch.ch/api/v2/projects/<project_id>/clusters" \
| jq

As an output, you should see a JSON file with the configuration of your cluster. Please note the id of your cluster – it will be needed in the next step. To learn more about each parameter and possible values of the payload file revisit the Create a Cluster guide.

Step 4: Add a MachineDeployment to a Cluster

Add a MachineDeployment to a Cluster Using the KKP API

You can add a MachineDeployment to an already created cluster by sending the below request. Please replace <project_id> and <cluster_id> in the request with the relevant values.

curl --silent --request POST \
     --header "Authorization: Bearer ${KKP_TOKEN}" \
     --data @add-md.json \
     "https://sck.cloud.switch.ch/api/v2/projects/<project_id>/clusters/<cluster_id>/machinedeployments" \
| jq

As an output, you should see a JSON file with the configuration of your MachineDeployment. To learn more about each parameter and possible values of the payload file revisit the Initial Nodes chapter of the Create a Cluster guide.

Add a MachineDeployment to a Cluster Using the Cluster's Kubernetes API

You can also add a MachineDeployment to an already created cluster by interacting with the cluster's Kubernetes API instead of the KKP API. Remember that you will need to use a kubeconfig file and assign an appropriate role to your user to get authenticated and authorized. Then use the below command and the add-md-k8s-api.yaml template provided in Step 0 to add a MachineDeployment to your cluster. Be sure to replace the <cluster_id> placeholder in the payload file. 

kubectl apply --filename "add-md-k8s-api.yaml"
Example output 
machinedeployment.cluster.k8s.io/test-md created

Shortcut: Create a Cluster with an Initial MachineDeployment

You do not need to split the steps 3 and 4. You can provision a cluster with an initial MachineDeployment using the below request. Notice that the payload file in this case is add-md.json integrated into cluster-no-md.json. Remember to replace the <provider_preset> placeholder in the payload file, and the <project_id> placeholder in the request itself with the relevant values.

curl --silent --request POST \
     --header "Authorization: Bearer ${KKP_TOKEN}" \
     --data @cluster-with-md.json \
     "https://sck.cloud.switch.ch/api/v2/projects/<project_id>/clusters" \
| jq

Conclusion

Congratulations! You have successfully learned how to provision a cluster by interacting with the KKP API.