---
title: How to manage a Kubernetes Kosmos cluster
description: Learn how to manage your Scaleway Kubernetes Kosmos cluster, including adding nodes and pools via the Scaleway console.
tags: kubernetes kosmos-cluster kosmos
dates:
  validation: 2025-10-14
  posted: 2021-05-31
---
import Requirements from '@macros/iam/requirements.mdx'

import image from './assets/scaleway-kubernetes-kubernetesexternalnoderegister.webp'
import image2 from './assets/scaleway-kosmos-add-application.webp'
import image3 from './assets/scaleway-kosmos-generate-api-key.webp'


You can add nodes and pools to your Kosmos cluster from the [Scaleway console](https://console.scaleway.com) or by using the [API](https://www.scaleway.com/en/developers/). Here, we show you how to edit from the console.

<Message type="note">
  This document concerns the management of a Kosmos cluster. For a Kapsule cluster, refer to the [corresponding documentation for Kapsule](/kubernetes/how-to/edit-cluster/)
</Message>

<Message type="important">
  Nodes from multi-cloud pools cannot benefit from the autohealing and autoscaling features of Scaleway Kapsule pool. Since Scaleway does not have access to your other providers’ accounts, it is not possible to carry out actions such as automatic deletion, creation, and reboot of external nodes.
</Message>

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- [Created](/kubernetes/how-to/create-cluster/) 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](#how-to-add-a-multi-cloud-pool-to-your-kosmos-cluster). 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](https://console.scaleway.com/iam/) displays.
2. [Create an IAM Policy](/iam/how-to/create-policy/) with the `KubernetesExternalNodeRegister` PermissionSet only.
    <Lightbox image={image} alt="" />
3. [Create an IAM Application](/iam/how-to/create-application/) linked with the policy created in the previous step.
    <Lightbox image={image2} alt="" />
4. [Create a new API key](/iam/how-to/create-api-keys/) linked to the IAM application created in the previous step.
    <Lightbox image={image3} alt="" />
    <Message type="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](/iam/quickstart/).
    </Message>
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:

    ```bash
    ssh <user>@<server_ip>
    ```

2. Download the `k8s-agent` program. The releases and source code are available on [GitHub](https://github.com/scaleway/k8s-agent).

    ```bash
    sudo wget -O /usr/local/bin/k8s-agent https://github.com/scaleway/k8s-agent/releases/latest/download/k8s-agent_linux_amd64 && sudo chmod +x /usr/local/bin/k8s-agent
    ```

3. Export the required environment variables:

    ```bash
    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:

    ```bash
    sudo --preserve-env=POOL_ID,POOL_REGION,SCW_SECRET_KEY /usr/local/bin/k8s-agent -kosmos
    ```
    <Message type="note">
      There is also an ARM binary (named `k8s-agent_linux_arm64`) available on the [releases page](https://github.com/scaleway/k8s-agent/releases/latest) for ARM-based nodes.
    </Message>

## 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 <Icon name="more" /> 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**.
    <Message type="note">
      This action will remove your node from the cluster. Your external node will not be deleted from your other cloud provider account(s).
    </Message>

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

<Message type="important">
  A node cannot be upgraded if it was managed by the old agent (`node-agent_linux_amd64`). If the node is managed by the old agent, a complete node re-install with the new agent (`k8s-agent`) is needed.
</Message>

The new `k8s-agent` upgrades the node in-place without adding a new "virtual" node in the pool (unlike the old agent).

<Message type="important">
  Note that the node will reappear with a different node ID. If your automation uses this ID (for instance when you use local PVCs), it will be broken.
</Message>

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. Download the latest version of the `k8s-agent` and relaunch it as you would do for a fresh node install. Refer to [How to configure external nodes to join the cluster](#how-to-configure-external-nodes-to-join-the-cluster) for the installation steps.
3. The node will upgrade in place and rejoin the cluster with the new Kubernetes version.