Kubernetes API

Introduction

Kubernetes is an open-source platform that enables developers to manage their containerized applications. Scaleway Kubernetes Kapsule and Kosmos are powerful tools to help you manage your containerized workloads and services.

They both provide a managed environment for creating, configuring, and running clusters of pre-configured machines.

The primary difference between Kapsule and Kosmos is that Kapsule clusters are composed solely of Scaleway Instances. In contrast, Kosmos is a managed Multi-Cloud Kubernetes Engine that allows you to connect Instances and virtual or dedicated servers from any cloud provider to a single managed Control-Plane.

Concepts

Refer to our dedicated concepts page to find definitions of all Kubetnetes-related terminology.

Quickstart

1. Configure your environment variables. Note: This is an optional step that seeks to simplify your usage of the Kapsule and Kosmos API.

   export SCW_ACCESS_KEY="<API access key>"
   export SCW_SECRET_KEY="<API secret key>"
   export SCW_REGION="<Scaleway service region>"
   export SCW_PROJECT_ID="<Scaleway Project ID>"
   

2. Edit the POST request payload you will use to create your Kubernetes cluster. Replace the parameters in the following example:

   {
   "project_id": "$SCW_PROJECT_ID",
   "type": "string",
   "name": "string",
   "description": "string",
   "tags": [
       "string"
   ],
   "version": "string",
   "cni": "unknown_cni",
   "pools": [
       {
       "name": "string",
       "node_type": "string",
       "size": "integer",
       "container_runtime": "unknown_runtime",
       "tags": [
           "string"
       ],
       "zone": "string",
       "root_volume_type": "default_volume_type",
       "root_volume_size": "integer"
       }
   ]
   }
   

   Parameter	Description
   project_id	The ID of the Project you want to create your Kubernetes cluster in. To find your Project ID you can list the projects or consult the Scaleway console.
   type	The type of the cluster (possible values are kapsule, multicloud).
   name	REQUIRED Name of the cmister.
   description	Description of the cluster.
   tags	Tags associated with the cluster.
   version	REQUIRED Kubernetes version of the cluster.
   cni	REQUIRED Container Network Interface (CNI) plugin that will run on the cluster. The default value is unknown_cni.
   pools	Pools to be created along with the cluster.
   name	REQUIRED Name of the pool.
   node-type	REQUIRED The node type of the Scaleway Instance wanted for the pool.
   size	REQUIRED The number of nodes in the pool.
   tags	Tags associated with the pool.
   zone	Availability zone in which the pools will be deployed in.
   root_volume_type	The root volume type. The default value is default_volume_type.
   root_volume_size	The system volume disk size in bytes.

3. Create a Kapsule cluster and node pool by running the following command. Make sure you include the payload you edited in the previous step.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "Content-Type: application/json" \
     "https://api.scaleway.com/k8s/v1/regions/$SCW_REGION/clusters" \
     -d "{
             \"project_id\": \"$SCW_PROJECT_ID\",
             \"type\": \"kapsule\",
             \"name\": \"MyFirstKapsuleCluster\",
             \"description\": \"My first Kapsule Cluster\",
             \"tags\": [
                 \"kapsule\",
                 \"kubernetes\"
             ],
             \"version\": \"1.27.0\",
             \"cni\": \"unknown_cni\",
             \"pools\": [
                 {
                 \"name\": \"MyFirstKapsulePool\",
                 \"node_type\": \"PLAY2-MICRO\",
                 \"size\": \"2\",
                 \"container_runtime\": \"unknown_runtime\",
                 \"tags\": [
                     \"pool\"
                 ],
                 \"zone\": \"fr-par-1\",
                 \"root_volume_type\": \"default_volume_type\",
                 \"root_volume_size\": \"20000000000\"
                 }
             ]
         }"
   

4. List your Kapsule clusters.

   curl -X GET -H "Content-Type: application/json" \
     -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/k8s/v1/regions/$SCW_REGION/clusters
   

   You will see detailed information about your clusters.

5. Download the kubeconfig file for your cluster.

   curl -X GET -H "Content-Type: application/json" \
     -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/k8s/v1/regions/$SCW_REGION/clusters/$SCW_CLUSTER_ID/kubeconfig
   

   Tip

   Add ?dl=1 at the end of the URL to directly get the base64-decoded kubeconfig. If not, the kubeconfig will be base64-encoded.

6. Connect to your cluster using kubectl.

7. Delete your cluster.

   curl -X GET -H "Content-Type: application/json" \
     -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/k8s/v1/regions/$SCW_REGION/clusters/$SCW_CLUSTER_ID
   

Technical information

Kubernetes Kapsule provides features such as:

• Persistent Volume Claims (PVC) are available through Scaleway Block Volumes.
• Pool autoscaling and autohealing is available.
• Kubernetes auto upgrades features is available.

Regions

Scaleway's infrastructure is spread across different regions and Availability Zones.

Kubernetes Kapsule and Kosmos are available in the Paris, Amsterdam and Warsaw regions, which are represented by the following path parameters:

• fr-par
• nl-ams
• pl-waw

Versions

Kubernetes Kosmos and Kapsule supports at least the latest version of the last 3 major Kubernetes releases.

Technical limitations

The following limitations should be taken into account when using the Kubernetes API

• The maximum number of pods per node is 110, as per the official k8s project recommendation.
• The maximum number of volumes (PVC) per node is 15.
• The maximum number of nodes per cluster/VPC is 500.
• Users cannot expose port 54 (DNS) to hostPort or in hostNetwork mode.
• Security groups set to drop all inbound must have stateful group enabled.

The following limitations should be acknowledged, while Scaleway is actively working on planned solutions to address them.

• Dual Stack IPv4/IPv6 is not (yet) available.
• Read Write Many / Read Only Many are not (yet) available.
• Kubernetes control plane network access is managed by a Load Balancer located on ZONE-1. In the event of a global failure for this AZ, the Control Plane will be unreachable.

Going further

For more help using Kubenetes Kapsule and Kosmos, check out the following resources:

• Our main documentation
• The #k8s channel on our Slack Community
• Our support ticketing system.

Clusters

Pools

Nodes

Versions

Cluster types