How to manage a Kubernetes Kosmos cluster

Reviewed on April 07, 2025

You can add nodes and pools to your Kosmos cluster from the Scaleway console or by using the API. Here, we show you how to edit from the console.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• Created a Kubernetes Kosmos cluster
• External machines (arm64 or amd64) you want to add to your cluster that are running on Ubuntu or Debian

How to add a multi-cloud pool to your Kosmos cluster

A multi-cloud pool allows you to attach external Instances and servers to your cluster. Instances added to the same pool do not need to share the same configuration, nor do they have to be managed by the same Cloud provider.

1. Click Kubernetes in the Containers section of the side menu. The Kubernetes creation page displays.
2. From the drop-down menu, select the geographical region you want to manage.
3. Click the cluster you want to add a pool to.
4. Click the Pools tab.
5. Click the + Add pool button. The pool creation wizard displays.
6. Complete the following steps of the wizard:
   • Choose a pool type. This can be a Scaleway Kubernetes Kapsule pool or a Kubernetes multi-cloud pool. This document concerns the addition of a multi-cloud pool.
   • A name for the pool and, optionally, a description and tags.
7. Click Add pool to finish.

How to add external nodes to your multi-cloud pool

In order to add external nodes to your multi-cloud cluster, you must first create a multi-cloud pool. For security reasons, it is recommended to configure an API key with the KubernetesExternalNodeRegister IAM permission set.

1. Click IAM & API keys on the top-right drop-down menu of the Scaleway console. The Identity and Access Management dashboard displays.
2. Create an IAM Policy with the KubernetesExternalNodeRegister PermissionSet only. Open Image over content
   Close current Lightbox
3. Create an IAM Application linked with the policy created in the previous step. Open Image over content
   Close current Lightbox
4. Create a new API key linked to the IAM application created in the previous step. Open Image over content
   Close current Lightbox
   Tip

   Identity and Access Management (IAM) allows you to share access to the management of your Scaleway resources and Organization settings, in a controlled and secure manner. For more information, refer to our dedicated IAM documentation.

5. Click Kubernetes in the Compute section of the side menu. The Kubernetes creation page displays.
6. Click the cluster you want to add external nodes to.
7. Click Nodes on the tab.
8. Click + Add external node. The instructions for adding an external node display.

How to configure external nodes to join the cluster

1. Get your server's public IP and SSH to the server:

   ssh <user>@<server_ip>

2. Download the node-agent program:

   wget https://scwcontainermulticloud.s3.fr-par.scw.cloud/node-agent_linux_amd64 && chmod +x node-agent_linux_amd64

3. Export the required environment variables:

   export POOL_ID=<pool_id>  POOL_REGION=<cluster_region>  SCW_SECRET_KEY=<secret_key>

4. Execute the program to attach the node to the multi-cloud pool:

   sudo -E ./node-agent_linux_amd64 -loglevel 0 -no-controller

   Note

   There is also an ARM binary (named node-agent_linux_arm64) for ARM-based nodes.

How to detach nodes from your multi-cloud pool

1. Click Kubernetes in the Compute section of the side menu. The Kubernetes creation page displays.
2. From the drop-down menu, select the geographical region you want to manage.
3. Click the cluster in question.
4. Click the Nodes tab.
5. Click more icon next to the node you want to edit, then click Delete on the menu. A pop-up asks you to confirm the action.
6. Click Delete node.
   Note

   This action will remove your node from the cluster. Your external node will not be deleted from your other cloud provider account(s).

How to upgrade nodes in a multi-cloud pool in your Kosmos cluster

The Kubernetes version of the existing nodes in your multi-cloud pool can be upgraded in place. Your workload will theoretically keep running during the upgrade, but it is best to drain the node before the upgrade.

1. In the Pools section of your Kosmos cluster, click Upgrade next to the node pool. This will not cause any of your existing nodes to upgrade, but will instead ensure that any new nodes added to the pool will start up with the newer version.
2. Run the installer program as you would do for a fresh node install, with the additional option -self-update. If the option is not available, download the program again from the Object Storage bucket.
3. Now the node will register itself with the Apiserver. Once it is ready, you will see the same node with two kubelet versions. The older node should end up NotReady after 5m, you can safely delete it with kubectl.
4. Detach the older node in Scaleway API.