How to create a Kubernetes Kapsule cluster

Reviewed on June 11, 2026

Scaleway Kubernetes Kapsule provides a managed environment for creating, configuring, and operating a cluster of preconfigured nodes for containerized applications. This service allows you to deploy Kubernetes (External link) clusters without the complexity of managing the underlying infrastructure.

Key benefits include:

Dynamic scaling of Pods based on workload demands
Simplified cluster management via kubectl (External link), the Kubernetes command-line tool

To facilitate cluster administration, Scaleway provides a .kubeconfig file, enabling you to manage your cluster locally using kubectl. This tool is essential for executing commands against Kubernetes clusters.

Before you start

To complete the actions presented below, you must have:

A Scaleway account with access to the console (External link)
Owner status or IAM permissions allowing you to perform actions in the intended Organization

Cluster configuration

Note

This guide covers the creation of a Kubernetes Kapsule cluster. For Kubernetes Kosmos clusters, refer to the Kubernetes Kosmos documentation.

Navigate to Kubernetes under the Containers section of the Scaleway console (External link) side menu. The Kubernetes dashboard displays.
From the drop-down menu, select the geographical region where you want to create your cluster.
Click Create cluster to launch the cluster creation wizard.
On the cluster configuration page, provide the following details:
- Check the Organization and Project for the new cluster.
  Important
  You cannot move a cluster from one Organization or Project to another once created.
- Select Kubernetes Kapsule as the cluster type, which uses exclusively Scaleway Instances.
- Confirm the geographical region for the cluster.
- Select the control plane offer for your cluster. Options include shared or dedicated control planes.
  Tip
  Need help deciding on a control plane offer? Learn more about our Kubernetes control plane offers.
- Specify the Kubernetes version for your cluster.
Enter the cluster's details. Provide a name for the cluster. Optionally, you can add a description and tags for better organization.
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.
Important
The Private Network cannot be detached, and the cluster cannot be moved to another Private Network post-creation.
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.

Configure the following for each pool:
- Choose an Availability Zone for the pool's nodes.
- Select the node type for the pool.
- Configure the system volume. This volume contains the operating system of the nodes in your pool.
- Configure pool options or retain default settings. Configuration options include:
  - Operations tab: Configure node count and choose whether to enable autoscaling and autoheal.
  - Network tab: Enable full isolation, if required.
  - Scheduling & Placement tab: Configure startup taints or taints, if required. You can also link the pool to a placement group.
  - Advanced options tab: Configure an optional cloud-init script to customize your nodes.
- Enter the name of the pool and optional tags.
- If required, add one or more node labels.
To add more pools, click Add pool and repeat the steps above.
Tip
You can add or remove pools as needed before finalizing your cluster configuration. To remove a pool, click the delete icon Delete icon next to the respective pool.
Once all pools are configured, click Review.

How to configure startup taints or taints

The startup taints and taints you configure for your pool are automatically applied to any new node created within the pool.

On the page of the pool that you are configuring, go to the Scheduling & Placement tab.
Select the Startup taints or the Taints checkbox, depending on what you wish to configure. The Key, Value, and Effect fields display.
Specify a key-value pair and an effect:
- Key: Acts as the identifier of the taint.
- (Optional) Value: An optional string that further qualifies the taint. It allows you to identify taints that share the same key but represent different situations.
- Effect: Specifies what happens to Pods that do not tolerate the taint:
  - NoSchedule: Pods that do not have a matching toleration are prevented from being scheduled on the node. Pods already running are left untouched.
  - PreferNoSchedule: The scheduler tries to avoid placing non‑tolerating Pods on the node, but it may still do so if no other suitable node exists.
  - NoExecute: Pods without a matching toleration are evicted from the node immediately, and new Pods that lack the toleration are blocked from being scheduled.
Click the Add startup taint or Add taint button to add further startup taints or taints, respectively.

Note

Managing tolerations in your Pod YAML manifests remains your responsibility. You must add the appropriate tolerations to any Pod that needs to run on a tainted node.

How to configure a cloud-init script

Cloud-init enables you to set custom configuration that will be applied at boot time to the Instances acting as the nodes in your pool.

Important

Use cloud-init with caution, overriding some default configurations can break nodes. Scaleway does not offer support for troubleshooting custom cloud-init scripts.

On the page of the pool that you are configuring, go to the Advanced options tab > Cloud-init section.
Click the Enable cloud-init button. The Enable cloud-init dialog box opens.

Enter your YAML-formatted cloud-init script, and click Enable cloud-init.

The following example shows a script that adds a custom Certificate Authority (CA):

#cloud-config
#
# This is an example file to configure an instance's trusted CA certificates
# system-wide for SSL/TLS trust establishment when the instance boots for the
# first time.
#
# Make sure that this file is valid yaml before starting instances.
# It should be passed as user-data when starting the instance.

ca_certs:
  # If present and set to True, the 'remove_defaults' parameter will either
  # disable all the trusted CA certifications normally shipped with
  # Alpine, Debian or Ubuntu. On RedHat, this action will delete those
  # certificates.
  # This is mainly for very security-sensitive use cases - most users will not
  # need this functionality.
  remove_defaults: true

  # If present, the 'trusted' parameter should contain a certificate (or list
  # of certificates) to add to the system as trusted CA certificates.
  # Pay close attention to the YAML multiline list syntax.  The example shown
  # here is for a list of multiline certificates.
  trusted: 
  - |
  -----BEGIN CERTIFICATE-----
  YOUR-ORGS-TRUSTED-CA-CERT-HERE
  -----END CERTIFICATE-----
  - |
  -----BEGIN CERTIFICATE-----
  YOUR-ORGS-TRUSTED-CA-CERT-HERE
  -----END CERTIFICATE-----

See cloud-config examples (External link) in the cloud-init documentation for further practical examples.

How to configure node labels

By attaching node labels to a pool, you can:

Require Pods to run only on nodes that match the label(s), or
Prefer Pods to run on nodes that match the label(s).

On the page of the pool that you are configuring, go to the Node labels section.
Specify a Key and a Value.
Click the Add node label button to add further node labels.

To implement the scheduling constraints related to the node labels you have just attached to your pool, remember to specify one or more corresponding node selection mechanisms in your Pod specification:

nodeSelector: The scheduler places the Pod only on nodes that contain all specified labels.
nodeAffinity: It lets you define how strict label‑based rules are:
- requiredDuringSchedulingIgnoredDuringExecution: The Pod cannot be scheduled unless the node satisfies the rule.
- preferredDuringSchedulingIgnoredDuringExecution: The scheduler tries to place the Pod on a matching node, but will fall back to any node if none match.

Review configuration

Review the configuration details of your Kubernetes cluster and its pools.
Tip
To modify any element, click the edit icon Edit icon next to the respective configuration component.
Click Submit to deploy your cluster. Once deployment is complete, the cluster appears in the clusters list.