docs(k8s): new image system (#5227)

Author: bene2k1

menu/navigation.json

@@ -1959,6 +1959,10 @@
                     "label": "Upgrade the Kubernetes version on a Kapsule cluster",
                     "slug": "upgrade-kubernetes-version"
                   },
+                  {
+                    "label": "Upgrade a Kapsule cluster to the new node image system",
+                    "slug": "upgrade-kapsule-new-node-image-system"
+                  },
                   {
                     "label": "Use the NVIDIA GPU operator on Kapsule and Kosmos with GPU Instances",
                     "slug": "use-nvidia-gpu-operator"

pages/kubernetes/how-to/upgrade-kapsule-new-node-image-system.mdx

@@ -0,0 +1,56 @@
+---
+title: How to upgrade a Kapsule cluster to the new node image system
+description: Learn how to upgrade a Kapsule cluster to the new node image system.
+tags: kubernetes kapsule node image
+dates:
+  validation: 2025-09-04
+  posted: 2025-09-04
+categories:
+  - containers
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+Scaleway is introducing a new image system for Kubernetes Kapsule clusters, bringing significant improvements, including reduced boot time, faster autoscaling, and an updated Ubuntu version.
+
+The advantages of the new image system include improved boot time, reduced from over five minutes to under one minute, and faster autoscaling. The new images are based on Ubuntu 24.04 LTS, replacing the previous 22.04 LTS version.
+Upgrades will also be faster, as nodes will be replaced instead of rebooted.
+
+## Technical specifications of the upgrade process
+
+* **Node replacement**: During upgrade, nodes will be replaced with new ones, which may have implications for data stored locally on nodes (e.g., `hostPath`). Data stored in persistent volumes (PV) will not be affected.
+* **New IP addresses**: The new replacement nodes will have new IP addresses (both public and private), which could impact IP filtering configurations.
+* **GPU pool upgrade**: The upgrade of GPU pools may result in a partial downtime due to a limitation in the GPU operator, which cannot handle mixed Ubuntu versions (22.04 vs 24.04). The operator will install incorrect drivers on new nodes until the upgrade is complete, after which it will recover automatically.
+
+<Requirements />
+
+- [Created](/kubernetes/how-to/create-cluster/) a Kubernetes Kapsule cluster
+- Installed the [Scaleway CLI](/scaleway-cli/quickstart/) on your local machine
+
+## Upgrade methods
+
+You can upgrade your Scaleway Kubernetes Kapsule cluster to the new image system using either the console or the CLI.
+
+### Console upgrade
+
+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 **Actions** in the top right corner of the cluster information page. A pop-up menu displays.
+4. Click **Upgrade cluster nodes image**. A pop-up displays.
+5. Click **Upgrade cluster node image** to confirm.
+
+### CLI upgrade:
+You can also upgrade the cluster to the new pool image system using the CLI.
+
+Example of commands:
+* Migrate all pools of a cluster to new images:
+    ```
+    scw k8s pool migrate-to-new-images cluster-id=11111111-1111-1111-1111-111111111111
+    ```
+* Migrate a specific pool of a cluster to new images:
+    ```
+    scw k8s pool migrate-to-new-images cluster-id=11111111-1111-1111-1111-111111111111 pools.0=22222222-2222-2222-2222-222222222222
+    ```
+* Create a new pool that uses the new images:
+    ```
+    scw k8s cluster create name=foo pools.0.name=bar pools.0.tags.0=scw-compute-image pools.0.size=1 pools.0.node-type=GP1-M
+    ```