NavigationContentFooter

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"
    }
    ]
    }
    ParameterDescription
    project_idThe 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.
    typeThe type of the cluster (possible values are kapsule, multicloud).
    nameREQUIRED Name of the cmister.
    descriptionDescription of the cluster.
    tagsTags associated with the cluster.
    versionREQUIRED Kubernetes version of the cluster.
    cniREQUIRED Container Network Interface (CNI) plugin that will run on the cluster. The default value is unknown_cni.
    poolsPools to be created along with the cluster.
    nameREQUIRED Name of the pool.
    node-typeREQUIRED The node type of the Scaleway Instance wanted for the pool.
    sizeREQUIRED The number of nodes in the pool.
    tagsTags associated with the pool.
    zoneAvailability zone in which the pools will be deployed in.
    root_volume_typeThe root volume type. The default value is default_volume_type.
    root_volume_sizeThe 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
Requirements

To perform the following steps, you must first ensure that:

  • you have an account and are logged into the Scaleway console
  • you have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page.
  • you have installed curl

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.
  • Dual Stack IPv4/IPv6 is not (yet) available.
  • Read Write Many / Read Only Many are not (yet) available.
  • Users cannot expose port 54 (DNS) to hostPort or in hostNetwork mode.
  • Security groups set to drop all inbound must have stateful group enabled.

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

A cluster is a fully managed Kubernetes cluster It is composed of different pools, each pool containing the same kind of nodes.

GET
/k8s/v1/regions/{region}/clusters
POST
/k8s/v1/regions/{region}/clusters
GET
/k8s/v1/regions/{region}/clusters/{cluster_id}
PATCH
/k8s/v1/regions/{region}/clusters/{cluster_id}
DELETE
/k8s/v1/regions/{region}/clusters/{cluster_id}
GET
/k8s/v1/regions/{region}/clusters/{cluster_id}/available-types
GET
/k8s/v1/regions/{region}/clusters/{cluster_id}/available-versions
GET
/k8s/v1/regions/{region}/clusters/{cluster_id}/kubeconfig
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/migrate-to-private-network
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/migrate-to-routed-ips
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/reset-admin-token
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/set-type
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/upgrade

Pools

A pool is a set of identical nodes A pool has a name, a size (its desired number of nodes), node number limits (min, max), and a Scaleway Instance type. Changing those limits increases/decreases the size of a pool. As a result and depending on its load, the pool will grow or shrink within those limits when autoscaling is enabled. A "default pool" is automatically created with every cluster via the console.

GET
/k8s/v1/regions/{region}/clusters/{cluster_id}/pools
POST
/k8s/v1/regions/{region}/clusters/{cluster_id}/pools
GET
/k8s/v1/regions/{region}/pools/{pool_id}
PATCH
/k8s/v1/regions/{region}/pools/{pool_id}
DELETE
/k8s/v1/regions/{region}/pools/{pool_id}
POST
/k8s/v1/regions/{region}/pools/{pool_id}/upgrade

Nodes

A node (short for worker node) is an abstraction for a Scaleway Instance A node is always part of a pool. Each of them has the Kubernetes software automatically installed and configured by Scaleway.

GET
/k8s/v1/regions/{region}/clusters/{cluster_id}/nodes
GET
/k8s/v1/regions/{region}/nodes/{node_id}
DELETE
/k8s/v1/regions/{region}/nodes/{node_id}
POST
/k8s/v1/regions/{region}/nodes/{node_id}/reboot
POST
/k8s/v1/regions/{region}/pools/{pool_id}/external-nodes

Versions

A version is a vanilla Kubernetes version like x.y.z It comprises a major version x, a minor version y, and a patch version z. At the minimum, Kapsule (Scaleway's managed Kubernetes), will support the last patch version for the past three minor releases. Also, each version has a different set of CNIs, eventually container runtimes, feature gates, and admission plugins available. See our Version Support Policy.

GET
/k8s/v1/regions/{region}/versions
GET
/k8s/v1/regions/{region}/versions/{version_name}

Cluster types

All cluster types available in a specified region A cluster type represents the different commercial types of clusters offered by Scaleway.

GET
/k8s/v1/regions/{region}/cluster-types
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway