---
title: Kubernetes Quickstart
description: This page shows you how to get started with Scaleway Kubernetes Kapsule and Kosmos.
tags: kubernetes cluster multi-cloud pool
dates:
  validation: 2025-10-07
  posted: 2021-05-26
---
import Requirements from '@macros/iam/requirements.mdx'


Scaleway Kubernetes [Kapsule](/kubernetes/concepts/#kubernetes-kapsule) and [Kosmos](/kubernetes/concepts/#kubernetes-kosmos) provide a managed environment to create, configure, and run a cluster of preconfigured machines for containerized applications. This allows you to create Kubernetes clusters without the complexity of managing the infrastructure. You can create a cluster to match your required specifications, edit it after creation, and delete it all when you no longer need it. You might also want to check out our how-to on [deploying an image on your cluster](/kubernetes/how-to/deploy-image-from-container-registry/).

## Console overview
Discover the Kubernetes interface on the Scaleway console.
<GuideFlow src="https://app.guideflow.com/embed/vkmgzdma2k"/>

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/glossary/#owner) status or [IAM permissions](/iam/concepts/glossary/#permission) allowing you to perform actions in the intended Organization

## How to create a Kubernetes Kapsule cluster

### Cluster configuration

1. Navigate to **Kubernetes** under the **Containers** section of the [Scaleway console](https://console.scaleway.com/) side menu. The Kubernetes dashboard displays.
2. From the drop-down menu, select the geographical region where you want to create your cluster.
3. Click **Create cluster** to launch the cluster creation wizard.
4. On the cluster configuration page, provide the following details:
    * Check the Organization and Project for the new cluster.
        <Message type="important">
          You cannot move a cluster from one Organization or Project to another once created.
        </Message>
    * Select **Kubernetes Kapsule** as the cluster type, which uses exclusively Scaleway Instances.
      <Message type="note">
        This section covers the creation of a **Kubernetes Kapsule** cluster. For Kubernetes Kosmos clusters, refer to the [Kubernetes Kosmos quickstart procedure](#how-to-create-a-kubernetes-kosmos-cluster) or the [Kubernetes Kosmos documentation](/kubernetes/how-to/create-kosmos-cluster/).
      </Message>
    * Confirm the geographical **region** for the cluster.
    * Select the control plane offer for your cluster. Options include shared or dedicated control planes.
        <Message type="tip">
          Need help deciding on a control plane offer? Learn more about our [Kubernetes control plane offers](/kubernetes/reference-content/kubernetes-control-plane-offers/).
        </Message>
    * Specify the **Kubernetes version** for your cluster.
5. Enter the **cluster's details**. Provide a name for the cluster. Optionally, you can add a description and tags for better organization.
6. Configure the **Private Network** for the cluster to ensure secure and isolated network communication. Each cluster is auto-configured with a /22 IP subnet. Click **Select a Private Network** to:
    * Attach an existing Private Network (VPC) within the same Availability Zone from the drop-down menu.
    * Attach a new Private Network to the cluster.
    <Message type="important">
      The Private Network cannot be detached, and the cluster cannot be moved to another Private Network post-creation.
    </Message>
7. Click **Configure pools** to proceed.

### Pool configuration

This section outlines the settings for your cluster pools. You can configure as many pools for your cluster as you require.

1. Configure the following for each pool:
    * Choose an **Availability Zone** for the pool's nodes.
    * Select the **node type** for the pool.
        <Message type="tip">
          Need advice on choosing a node type? [Learn more about Kubernetes nodes.](/kubernetes/concepts/#node)
        </Message>
    * Configure the **system volume**. This volume contains the operating system of the nodes in your pool.
    * Configure **pool options**:
      * **Operations** tab: Specify node count and choose whether to enable [autoscaling](/kubernetes/concepts/#autoscale) or [autoheal](/kubernetes/concepts/#autoheal).
      * **Network** tab: Choose whether to enable [full isolation](/kubernetes/reference-content/secure-cluster-with-private-network/#what-is-the-difference-between-controlled-isolation-and-full-isolation).
      * **Scheduling & Placement** tab: Configure [startup taints and taints](/kubernetes/how-to/create-cluster/#how-to-configure-startup-taints-or-taints), if required. You can also link the pool to a [placement group](/instances/concepts/#placement-groups).
      
      You can also choose to retain default settings.
    * Configure an optional [cloud-init](/kubernetes/how-to/create-cluster/#how-to-configure-a-cloud-init-script) script to customize your nodes.

        <Message type="important">
        Use cloud-init with caution, overriding some default configurations can break nodes. Scaleway does not offer support for troubleshooting custom cloud-init scripts.
        </Message>      
    * Enter the details of the pool.
    * If required, add one or more [node labels](/kubernetes/how-to/create-cluster/#how-to-configure-node-labels).    
2. To add more pools, click **Add pool** and repeat the steps above.
    <Message type="tip">
      You can add or remove pools as needed before finalizing your cluster configuration. To remove a pool, click the <Icon name="delete" /> **Delete** icon next to the respective pool.
    </Message>
3. Once all pools are configured, click **Review** to finalize your cluster setup.

### Review configuration

1. Review the configuration details of your Kubernetes cluster and its pools.
    <Message type="tip">
      To modify any element, click the <Icon name="edit" /> **Edit** icon next to the respective configuration component.
    </Message>
2. Click **Submit** to deploy your cluster. Once deployment is complete, the cluster appears in the clusters list.
    You can now download the `kubeconfig` file for your cluster and learn [how to connect to a Kubernetes Kapsule cluster with kubectl](/kubernetes/how-to/connect-cluster-kubectl/).
  

## How to create a Kubernetes Kosmos cluster

### Cluster configuration

1. Click **Kubernetes** in the **Containers** section of the [Scaleway console](https://console.scaleway.com) side menu. The Kubernetes dashboard displays.
2. From the drop-down menu, select the geographical region you want to manage.
3. Click **Create cluster** to launch the cluster creation wizard.
4. Complete the following steps of the wizard:
    * Choose a **cluster type**. Select **Kubernetes Kosmos** to create a cluster that allows you to attach a compute Instance or dedicated server from any Cloud provider to a Scaleway Kubernetes control plane.
      <Message type="note">
        This section concerns the creation and management of a **Kubernetes Kosmos** cluster. To create a Kubernetes Kapsule cluster, refer to the [Kubernetes Kapsule quickstart procedure](#how-to-create-a-kubernetes-kapsule-cluster) or the [Kubernetes Kapsule documentation](/kubernetes/how-to/create-cluster/).
      </Message>
    * Confirm the geographical **region** of the cluster.
    * Select the Kubernetes **version** for the cluster.
    * Add **name** for the cluster and, optionally, a description and tags.
5. If you want to add pools, click **Configure pools (optional)** to proceed. If you do not wish to add any pools, click **[Review](#kosmos-review-configuration)**.

### Pool configuration

In a Kosmos cluster, you can add either:
- **Scaleway** pools composed exclusively of Scaleway Instances, or 
- **Multi-cloud** pools built from external Instances and servers

This section explains how to add a Scaleway pool. 

For instructions on creating a Multi‑cloud pool and attaching external nodes to your Kosmos cluster, refer to our [dedicated documentation](/kubernetes/how-to/edit-kosmos-cluster/).

To add a Scaleway pool to your Kosmos cluster:

1. Choose the **Scaleway** pool type.
2. Configure your pool:
    * Select the **Availability Zone** of the pool.
    * Select a **node type** for the pool.
    * Configure the **system volume**.
    * If required, configure **pool options**:
      * **Operations** tab: Specify node count and choose whether to enable [autoscaling](/kubernetes/concepts/#autoscale) or [autoheal](/kubernetes/concepts/#autoheal).
      * **Scheduling & Placement** tab: Configure [startup taints and taints](/kubernetes/how-to/create-kosmos-cluster/#how-to-configure-startup-taints-or-taints), if required. You can also link the pool to a [placement group](/instances/concepts/#placement-groups).
     
      Alternatively, you can leave these options at default values.
    * Configure an optional [cloud-init](/kubernetes/how-to/create-kosmos-cluster/#how-to-configure-a-cloud-init-script) script to customize your nodes.

        <Message type="important">
        Use cloud-init with caution, overriding some default configurations can break nodes. Scaleway does not offer support for troubleshooting custom cloud-init scripts.
        </Message>      
    * Specify a **name** for the pool. Optionally, you can assign tags to it.
    * If required, add one or more [node labels](/kubernetes/how-to/create-kosmos-cluster/#how-to-configure-node-labels).
3. To add more pools, click **Add pool** and repeat the steps above.
    <Message type="tip">
      You can add or remove pools as needed before finalizing your cluster configuration. To remove a pool, click the <Icon name="delete" /> **Delete** icon next to the respective pool.
    </Message>
4. Once all pools are configured, click **Review** to finalize your cluster setup.

### Review configuration <a name="kosmos-review-configuration"></a>

1. Review the configuration details of your Kubernetes cluster and its pools (if any).
    <Message type="tip">
      To modify any element, click the <Icon name="edit" /> **Edit** icon next to the respective configuration component.
    </Message>
2. Click **Submit** to deploy your cluster. Once deployment is complete, the cluster appears in the clusters list.
  <Message type="important">
    The Kosmos agent/installer supports Ubuntu 24.04 and may work on Debian based distributions.     
    It is available for `arm64` or `amd64` server architectures.

    Bear in mind that we **do not provide support on external nodes**.
  </Message>

## How to edit a Kubernetes cluster

1. Click **Kubernetes** in the **Containers** section of the side menu. The Kubernetes dashboard displays.
2. From the drop-down menu, select the geographical region you want to manage.
3. Click <Icon name="more" /> next to the cluster you want to edit.
4. Choose the option you require:
    * **Add pool**: Add additional computing resources to the cluster.
    * **Generate kubeconfig**: Download the `.kubeconfig` file of the cluster.
    * **Delete**: Delete the cluster.

<Message type="tip">
  Click the name of the cluster you want to edit to display all available options.
</Message>

## How to delete a Kubernetes cluster

1. Click **Kubernetes** in the **Containers** section of the side menu. The Kubernetes dashboard displays.
2. From the drop-down menu, select the geographical region you want to manage.
3. Click <Icon name="more" /> to display the options menu, then click **Delete**. A cluster deletion pop-up displays.
4. Type **DELETE** to confirm the deletion of your cluster. Tick the checkbox to automatically delete all volumes (including those with volume type “retain”) and Load Balancers whose names start with the cluster ID. Validate your choice by clicking **Delete cluster**.
    <Message type="important">
      Deleting your cluster will permanently destroy your cluster and all its associated pools and Instances. External compute resources cannot be destroyed automatically and will remain active until destroyed at the concerned cloud service provider (CSP).
    </Message>