docs(ins): add warning for kapsule nodes

menu/navigation.json

@@ -1875,6 +1875,10 @@
                     "label": "Connect to a cluster with kubectl",
                     "slug": "connect-cluster-kubectl"
                   },
+                  {
+                    "label": "Manage Kapsule node pools",
+                    "slug": "manage-node-pools"
+                  },
                   {
                     "label": "Deploy an image from Container Registry",
                     "slug": "deploy-image-from-container-registry"

pages/instances/api-cli/migrating-instances.mdx

@@ -26,6 +26,10 @@ To do so, you need the Instance’s ID and a valid API key.
   Network interface names may vary across commercial families (e.g. ENT1 vs. POP2). Ensure that any hardcoded interface names in your configurations or scripts are updated to avoid migration issues.
 </Message>
 
+<Message type="important">
+  Do **not** manually change the commercial type of **Kubernetes Kapsule nodes** using the API or CLI. Kubernetes Kapsule nodes **must be managed** through Kubernetes. Modifying node types outside of the recommended method can lead to instability or unexpected behavior.
+  To change the commercial type of your nodes, create a new node pool with the desired Instance type and [migrate your workloads](/kubernetes/how-to/manage-node-pools/#how-to-migrate-existing-workloads-to-a-new-kubernets-kapsule-node-pool) to the new pool.
+</Message>
 <Tabs id="updateinstance">
   <TabsTab label="CLI">
 

pages/kubernetes/how-to/manage-node-pools.mdx

@@ -0,0 +1,100 @@
+---
+meta:
+  title: How to manage Kubernetes Kapsule node pools
+  description: Learn how to manage Kubernetes Kapsule node pools from the Scaleway console.
+content:
+  h1: How to manage Kubernetes node pools
+  paragraph: Learn how to manage Kubernetes Kapsule node pools from the Scaleway console.
+tags: kubernetes kapsule kosmos
+dates:
+  validation: 2025-06-23
+  posted: 2025-06-23
+categories:
+  - containers
+---
+
+This documentation provides step-by-step instructions on how to manage Kubernetes Kapsule node pools using the Scaleway console.
+
+<Macro id="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 a [Kubernetes Kapsule cluster](/kubernetes/how-to/create-cluster/)
+
+## How to create a new Kubernetes Kapsule node pool
+
+<Message type="tip">
+  Kubernetes Kapsule supports using both **fully isolated** and **controlled isolation** node pools within the same cluster. [Learn more.](/kubernetes/reference-content/secure-cluster-with-private-network/#what-is-the-difference-between-controlled-isolation-and-full-isolation)
+</Message>
+
+1. Navigate to **Kubernetes** under the **Containers** section of the [Scaleway console](https://console.scaleway.com/) side menu. The Kubernetes dashboard displays.
+2. Click the Kapsule cluster name you want to manage. The cluster information page displays.
+3. Click the **Pools** tab to display the pool configuration of the cluster.
+4. Click **Add pool** to launch the pool creation wizard.
+5. Configure the pool:
+    - Choose the **Availability Zone** for the pool.
+    - Choose the commercial type of Instance for the pool.
+    - Configure the system volume.
+    - Configure pool options.
+    - Enter the pool's details.
+6. Click **Add pool**. The pool gets added to your basket. Repeat the steps above to configure additional pools.
+7. Click **Review** once you have configured the desired pools. A summary of your configuration displays.
+8. Verify your configuration and click **Submit** to add the pool(s) to your Kapsule cluster.
+
+<Message type="note">
+  Alternatively, you can use the Scaleway CLI to [create node pools](https://cli.scaleway.com/k8s/#create-a-new-pool-in-a-cluster).
+</Message>
+
+## How to edit an existing Kubernetes Kapsule node pool
+
+1. Navigate to **Kubernetes** under the **Containers** section of the [Scaleway console](https://console.scaleway.com/) side menu. The Kubernetes dashboard displays.
+2. Click the Kapsule cluster name you want to manage. The cluster information page displays.
+3. Click the **Pools** tab to display the pool configuration of the cluster.
+4. Click <Icon name="more" /> > **Edit** next to the node pool you want to edit.
+5. Configure the pool:
+    - Update pool tags
+    - Configure autoscaling
+    - Enable or disable the [autoheal feature](/kubernetes/reference-content/using-kapsule-autoheal-feature/)
+6. Click **Update pool** to update the pool configuration.
+
+<Message type="note">
+  Alternatively, you can use the Scaleway CLI to [update a node pool](https://cli.scaleway.com/k8s/#update-a-pool-in-a-cluster).
+</Message>
+
+## How to migrate existing workloads to a new Kubernets Kapsule node pool
+
+<Message type="important">
+  Always ensure that your **data is backed up** before performing any operations that could affect it.
+</Message>
+
+1. Create the new node pool with the desired configuration either [from the console](#how-to-create-a-new-kubernetes-kapsule-node-pool) or by using the Scaleway CLI tool `scw`.
+    <Message type="tip">
+      Ensure that the new node pool is properly labeled if necessary.
+    </Message>
+2. Run `kubectl get nodes` to check that the new nodes are in a `Ready` state.
+3. Cordon the nodes in the old node pool to prevent new pods from being scheduled there. For each node, run: `kubectl cordon <node-name>`
+    <Message type="tip">
+      You can use a selector on the pool name label to cordon or drain multiple nodes at the same time if your app allows it (ex. `kubectl cordon -l k8s.scaleway.com/pool-name=mypoolname`)
+    </Message>
+4. Drain the nodes to evict the pods gracefully.
+   - For each node, run: `kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data`
+   - The `--ignore-daemonsets` flag is used because daemon sets manage pods across all nodes and will automatically reschedule them.
+   - The `--delete-emptydir-data` flag is necessary if your pods use emptyDir volumes, but use this option carefully as it will delete the data stored in these volumes.
+   - Refer to the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) for further information.
+5. Run `kubectl get pods -o wide` after draining, to verify that the pods have been rescheduled to the new node pool.
+6. [Delete the old node pool](#how-to-delete-an-existing-kubernetes-kapsule-node-pool) once you confirm that all workloads are running smoothly on the new node pool.
+
+## How to delete an existing Kubernetes Kapsule node pool
+
+1. Navigate to **Kubernetes** under the **Containers** section of the [Scaleway console](https://console.scaleway.com/) side menu. The Kubernetes dashboard displays.
+2. Click the Kapsule cluster name you want to manage. The cluster information page displays.
+3. Click the **Pools** tab to display the pool configuration of the cluster.
+4. Click <Icon name="more" /> > **Delete** next to the node pool you want to delete.
+5. Click **Delete pool** in the pop-up to confirm deletion of the pool.
+    <Message type="important">
+      This action will permanently destroy your pool and all its data.
+    </Message>
+
+<Message type="note">
+  Alternatively, you can use the Scaleway CLI to [delete a node pool](https://cli.scaleway.com/k8s/#delete-a-pool-in-a-cluster).
+</Message>