Skip to content

Commit 2d1cb36

Browse files
SamyOubouazizSamyOubouaziz
authored
docs(blk): duplicate migration procedure to Block Storage doc (#5102)
1 parent b21980b commit 2d1cb36

File tree

4 files changed

+320
-295
lines changed

4 files changed

+320
-295
lines changed

‎macros/compute/how-to-migrate-to-sbs.mdx

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
---
2+
macro: how-to-migrate-to-sbs
3+
---
4+
5+
To enhance performance and reliability, Scaleway is transitioning the management of Block Storage volumes and snapshots from Compute to Storage.
6+
7+
To facilitate the transition to Scaleway's new Block Storage management, two main approaches for migrating your volumes exist, each with its unique benefits and drawbacks:
8+
9+
- [Using the Instance API/CLI migration endpoint (Plan and Apply)](#migrating-using-the-instance-apicli-migration-endpoint-plan-and-apply):
10+
- **Advantage:** Migration can occur without service interruption, as the volume remains attached to the running Instance and fully accessible.
11+
- **Drawback:** Only the volume's representation is migrated to the SBS API; the data itself does not move. This means the migrated volume will not benefit from low latency or higher IOPS, as it **retains the original `b_ssd` characteristics**.
12+
13+
- [Using the snapshot export/import features](#migrating-using-the-snapshot-exportimport-features):
14+
- **Advantage:** The migrated volume will fully support low latency, and it is possible to modify the IOPS up to 15k. All existing data of the old volume will be copied to the new Block Storage Low Latency volume.
15+
- **Drawback:** A snapshot must be manually created, exported, and imported. After importing, the snapshot must be converted into a volume, which must then be attached to the Instance. This process may require downtime.
16+
17+
Each method caters to different needs, balancing uninterrupted service against achieving maximum performance benefits. After migration, these resources will be managed under [Storage](/block-storage/quickstart/) instead of Compute.<br />
18+
Learn more about the [advantages of migrating from the Instance API to the Block Storage API for managing block volumes and snapshots](/block-storage/reference-content/advantages-migrating-to-sbs/).
19+
20+
## Comparison of migration methods
21+
22+
| Migration Method | Advantage | Drawback |
23+
|--------------------------------|-----------------------------------------------|---------------------------------------------|
24+
| Instance API/CLI migration | No service interruption, volume remains accessible | Data characteristics remain the same; no performance boost |
25+
| Snapshot export/import | Full support for low latency and customizable IOPS | Requires downtime; manual snapshot handling |
26+
27+
This guide offers step-by-step instructions to migrate your volumes and snapshots using either the [Scaleway Command Line Interface (CLI)](/scaleway-cli/quickstart/) tool (recommended) or the [Instances API](https://www.scaleway.com/en/developers/api/instance/#path-volumes-migrate-a-volume-andor-snapshots-to-sbs-scaleway-block-storage).
28+
Alternatively, you can use the [snapshot export/import feature](/instances/api-cli/snapshot-import-export-feature/) to migrate your unified volumes and snapshots to Block Storage Low Latency volumes.
29+
30+
<Message type="important">
31+
Volumes **created and managed through Kubernetes** do not fall within the scope of the migration described on this page. Find specific instructions for migrating Kubernetes volumes behind the Scaleway Block Storage API in the [managing storage for Kubernetes documentation](/kubernetes/api-cli/managing-storage/#upgrading-to-csi-version-03).
32+
</Message>
33+
34+
## Comparison of Block Storage volume types
35+
36+
| Volume type | IOPS | Underlying hardware | Latency | Max volume size | Recommended use cases | Availability & resilience |
37+
|-----------------------------------|----------|--------------------------------|---------------------|----------------------|-------------------------|----------------------------|
38+
| `b_ssd` (Block Storage 5K legacy) | 5,000 | Legacy SSDs | Higher | Up to 10 TB | General-purpose workloads that do not demand high IOPS or low latency | Data is replicated three times across multiple disks for high availability and integrity |
39+
| `sbs_5k` (Block Low Latency 5K) | 5,000 | Modern NVMe disks | Low | 5 GB to 10 TB | Development environments, web servers, and applications needing consistent performance | 99.99% SLA, triple-replicated data to safeguard against hardware failures |
40+
| `sbs_15k` (Block Low Latency 15K) | 15,000 | Modern NVMe disks | Very low | 5 GB to 10 TB | High-performance databases, transactional applications, and I/O-intensive workloads | 99.99% SLA, triple-replicated data to safeguard against hardware failures |
41+
42+
You can attach a maximum of 16 volumes (including the mandatory boot volume) to a single Instance.
43+
44+
<Message type="tip">
45+
Refer to [Understand the difference between Block Storage volumes and Block Storage Low Latency volumes](/block-storage/reference-content/differences-between-5kiops-volumes/) for more information on the differences between Block Storage 5K legacy volumes and Block Storage Low Latency 5K volumes.
46+
</Message>
47+
48+
### Additional details:
49+
50+
- `b_ssd`: These volumes are based on older SSD technology, providing reliable performance but with limitations in terms of speed and latency.
51+
- `sbs_5k`: These volumes use NVMe technology, offering better performance and lower latency. They allow flexibility to adjust storage based on your needs.
52+
- `sbs_15k`: These volumes offer even higher performance, with up to 15,000 IOPS, making them ideal for workloads requiring fast and reliable data access.
53+
<Message type="note">
54+
To maximize compatibility with Block Storage Low Latency 15K, select an Instance with at least [3 GiB/s of Block bandwidth](/instances/reference-content/instances-bandwidth-overview/).
55+
</Message>
56+
57+
<Macro id="requirements" />
58+
59+
- A Scaleway account logged into the [console](https://console.scaleway.com)
60+
- An [Instance](/instances/how-to/create-an-instance/) using [Block Storage volumes](/block-storage/how-to/create-a-volume/)
61+
62+
<Message type="tip">
63+
- The easiest way to migrate your Block Storage volumes and snapshots is by using the [Scaleway Command Line Interface (CLI)](/scaleway-cli/quickstart/) tool.
64+
- If you encounter an error about quota limitations during the migration process, [contact our support team](https://console.scaleway.com/support/tickets/create) for assistance.
65+
</Message>
66+
67+
<Message type="important">
68+
To ensure continued access to managing your volumes, you must convert your **unified volumes and snapshots** into either **local** or **Block volumes** before the **end-of-life date of June 2nd, 2025**. After this date, unified volumes and snapshots will no longer be supported by any API.
69+
70+
#### Key migration deadlines:
71+
- April 30th, 2025:
72+
- Creation of new unified volumes via the Instance API will be disabled.
73+
- Unified volumes will no longer be supported by the Instance API.
74+
- June 2nd, 2025:
75+
- Unified volumes and snapshots can no longer be managed via any API. Existing unified resources must be converted by this date to avoid loss of manageability.
76+
</Message>
77+
78+
## Migrating using the Instance API/CLI migration endpoint (Plan and Apply):
79+
80+
<Message type="note">
81+
During migration, unified snapshots will be converted into [Block Storage](/block-storage/) snapshots and removed from Compute. If a unified snapshot is part of an image, it will be replaced by the corresponding Block Storage snapshot.
82+
</Message>
83+
84+
### Migrating an existing Block Storage volume to Scaleway Block Storage management
85+
86+
<Message type="important">
87+
This process applies only to Block SSD (`b_ssd`) volumes.
88+
</Message>
89+
90+
<Tabs>
91+
<TabsTab label="CLI">
92+
<Message type="note">
93+
When you migrate a volume, the volume and any snapshots created from it will be migrated as well.
94+
</Message>
95+
1. Use the following command to list your Block Storage volumes and retrieve the ID of the volume you wish to migrate:
96+
```
97+
$ scw instance volume list
98+
ID STATE SERVER ID SERVER NAME
99+
369feb53-165f-437d-875e-188725df462b available
100+
```
101+
2. Plan the volume migration using the `scw instance volume plan-migration <VOLUME_ID>` command. This command returns the volume and its snapshots that will be migrated, along with a unique `ValidationKey` required to start the migration.
102+
```
103+
$ scw instance volume plan-migration 369feb53-165f-437d-875e-188725df462b
104+
Volume.ID 369feb53-165f-437d-875e-188725df462b
105+
Volume.Name vol-peaceful-davinci
106+
Volume.Size 25 GB
107+
Volume.VolumeType b_ssd
108+
Volume.CreationDate 2 weeks ago
109+
Volume.ModificationDate 2 weeks ago
110+
Volume.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
111+
Volume.Project 4a2e00bf-5126-43ce-9b09-be943c619139
112+
Volume.Server.ID 177c6ed5-e999-4cc7-b152-8ce56217579c
113+
Volume.Server.Name scw-naughty-robinson
114+
Volume.State available
115+
Volume.Zone fr-par-1
116+
Snapshots.0.ID a377afe5-a9a3-4706-b8c2-8d1c247a620f
117+
Snapshots.0.Name image-scw-quirky-torvalds_snap_0
118+
Snapshots.0.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
119+
Snapshots.0.Project 4a2e00bf-5126-43ce-9b09-be943c619139
120+
Snapshots.0.VolumeType b_ssd
121+
Snapshots.0.Size 10 GB
122+
Snapshots.0.State available
123+
Snapshots.0.CreationDate 2 weeks ago
124+
Snapshots.0.ModificationDate 5 days ago
125+
Snapshots.0.Zone fr-par-1
126+
Snapshots.1.ID 384799c2-c4dd-40ab-bd65-ed95cd7b4d5c
127+
Snapshots.1.Name snap-eloquent-edison
128+
Snapshots.1.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
129+
Snapshots.1.Project 4a2e00bf-5126-43ce-9b09-be943c619139
130+
Snapshots.1.VolumeType b_ssd
131+
Snapshots.1.Size 10 GB
132+
Snapshots.1.State available
133+
Snapshots.1.CreationDate 2 weeks ago
134+
Snapshots.1.ModificationDate 5 days ago
135+
Snapshots.1.Zone fr-par-1
136+
ValidationKey 30d129ca895c4cd59f4c429e12dab300
137+
```
138+
3. Execute the migration using the `scw instance volume apply-migration <VOLUME_ID> validation-key=<VALIDATION_KEY> zone=<VOLUME_ZONE>` command.
139+
```
140+
$ scw instance volume apply-migration 369feb53-165f-437d-875e-188725df462b validation-key=30d129ca895c4cd59f4c429e12dab300 zone=fr-par-1
141+
✅ Success
142+
```
143+
The volume migration is complete. You can now manage the migrated volume from the [Block Storage volumes section](https://console.scaleway.com/block-storage/volumes) in the Scaleway console.
144+
</TabsTab>
145+
<TabsTab label="API">
146+
<Message type="note">
147+
When you migrate a volume using the API, the volume and any snapshots created from the volume will be migrated.
148+
</Message>
149+
150+
1. Plan the migration by sending a `POST` request to the Scaleway API:
151+
152+
```bash
153+
curl --location "https://api.scaleway.com/instance/v1/zones/$SCW_AVAILABILITY_ZONE/block-migration/plan" \
154+
--header "Content-Type: application/json" \
155+
--header "X-Auth-Token: $SCW_SECRET_KEY" \
156+
--data "{
157+
\"volume_id\": \"$SCW_VOLUME_ID\"
158+
}"
159+
```
160+
161+
This request returns the volume and its snapshots that will be migrated, along with a unique `ValidationKey` required to start the migration.
162+
163+
2. Confirm and execute the migration by sending another `POST` request:
164+
165+
```bash
166+
curl --location "https://api.scaleway.com/instance/v1/zones/$SCW_AVAILABILITY_ZONE/block-migration/apply" \
167+
--header "Content-Type: application/json" \
168+
--header "X-Auth-Token: $SCW_SECRET_KEY" \
169+
--data "{
170+
\"volume_id\": \"$SCW_VOLUME_ID\",
171+
\"validation_key\": \"$SCW_VALIDATION_KEY\"
172+
}"
173+
```
174+
</TabsTab>
175+
</Tabs>
176+
177+
<Message type="important">
178+
After the migration, your volume's type will still be `b_ssd` (displayed as **Block SSD 5K legacy** in the Scaleway console).
179+
To benefit from the new features and performance of Scaleway Block Storage, you must create a new volume (`sbs_5k` or `sbs_15k` displayed as **Block Low Latency 5K** or **Block Low Latency 15K** in the Scaleway console) using the snapshot export/import feature. For more information, see [Migrating using the snapshot export/import features](#migrating-using-the-snapshot-exportimport-features).
180+
</Message>
181+
182+
### Migrating an existing Block Storage snapshot to Scaleway Block Storage management
183+
184+
<Message type="important">
185+
This process applies to Block SSD (`b_ssd`) or Unified (`unified`) snapshots.
186+
</Message>
187+
188+
<Tabs>
189+
<TabsTab label="CLI">
190+
<Message type="note">
191+
When you migrate a snapshot, the source volume of the snapshot and any snapshots created from this volume will also be migrated.
192+
</Message>
193+
1. Use the following command to list your snapshots and retrieve the ID of the snapshot you wish to migrate:
194+
```
195+
$ scw instance snapshot list
196+
ID NAME
197+
a377afe5-a9a3-4706-b8c2-8d1c247a620f snap-eloquent-edison
198+
```
199+
2. Plan the snapshot migration using the `scw instance snapshot plan-migration <SNAPSHOT_ID>` command. This command returns the source volume of the snapshot and any related snapshots that will be migrated, along with a unique `ValidationKey`.
200+
```
201+
$ scw instance snapshot plan-migration a377afe5-a9a3-4706-b8c2-8d1c247a620f
202+
Volume.ID 369feb53-165f-437d-875e-188725df462b
203+
Volume.Name vol-peaceful-davinci
204+
Volume.Size 25 GB
205+
Volume.VolumeType b_ssd
206+
Volume.CreationDate 2 weeks ago
207+
Volume.ModificationDate 2 weeks ago
208+
Volume.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
209+
Volume.Project 4a2e00bf-5126-43ce-9b09-be943c619139
210+
Volume.Server.ID 177c6ed5-e999-4cc7-b152-8ce56217579c
211+
Volume.Server.Name scw-naughty-robinson
212+
Volume.State available
213+
Volume.Zone fr-par-1
214+
Snapshots.0.ID a377afe5-a9a3-4706-b8c2-8d1c247a620f
215+
Snapshots.0.Name image-scw-quirky-torvalds_snap_0
216+
Snapshots.0.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
217+
Snapshots.0.Project 4a2e00bf-5126-43ce-9b09-be943c619139
218+
Snapshots.0.VolumeType b_ssd
219+
Snapshots.0.Size 10 GB
220+
Snapshots.0.State available
221+
Snapshots.0.CreationDate 2 weeks ago
222+
Snapshots.0.ModificationDate 5 days ago
223+
Snapshots.0.Zone fr-par-1
224+
Snapshots.1.ID 384799c2-c4dd-40ab-bd65-ed95cd7b4d5c
225+
Snapshots.1.Name snap-eloquent-edison
226+
Snapshots.1.Organization 4a2e00bf-5126-43ce-9b09-be943c619139
227+
Snapshots.1.Project 4a2e00bf-5126-43ce-9b09-be943c619139
228+
Snapshots.1.VolumeType b_ssd
229+
Snapshots.1.Size 10 GB
230+
Snapshots.1.State available
231+
Snapshots.1.CreationDate 2 weeks ago
232+
Snapshots.1.ModificationDate 5 days ago
233+
Snapshots.1.Zone fr-par-1
234+
ValidationKey 30d129ca895c4cd59f4c429e12dab300
235+
```
236+
3. Execute the migration using the `scw instance snapshot apply-migration <SNAPSHOT_ID> validation-key=<VALIDATION_KEY> zone=<SNAPSHOT_ZONE>` command.
237+
```
238+
$ scw instance snapshot apply-migration a377afe5-a9a3-4706-b8c2-8d1c247a620f validation-key=30d129ca895c4cd59f4c429e12dab300 zone=fr-par-1
239+
✅ Success.
240+
```
241+
The snapshot migration is complete. You can now manage the migrated snapshot from the [Block Storage Snapshot section](https://console.scaleway.com/block-storage/volumes) in the Scaleway console.
242+
</TabsTab>
243+
<TabsTab label="API">
244+
<Message type="note">
245+
When you migrate a snapshot using the API, the source volume of the snapshot and any snapshots created from this volume will also be migrated.
246+
</Message>
247+
248+
1. Plan the migration by sending a `POST` request to the Scaleway API:
249+
250+
```bash
251+
curl --location "https://api.scaleway.com/instance/v1/zones/$SCW_AVAILABILITY_ZONE/block-migration/plan" \
252+
--header "Content-Type: application/json" \
253+
--header "X-Auth-Token: $SCW_SECRET_KEY" \
254+
--data "{
255+
\"snapshot_id\": \"$SCW_SNAPSHOT_ID\"
256+
}"
257+
```
258+
259+
This request returns the source volume and any related snapshots that will be migrated, along with a unique `ValidationKey`.
260+
261+
2. Confirm and execute the migration by sending another `POST` request:
262+
263+
```bash
264+
curl --location "https://api.scaleway.com/instance/v1/zones/$SCW_AVAILABILITY_ZONE/block-migration/apply" \
265+
--header "Content-Type: application/json" \
266+
--header "X-Auth-Token: $SCW_SECRET_KEY" \
267+
--data "{
268+
\"snapshot_id\": \"$SCW_SNAPSHOT_ID\",
269+
\"validation_key\": \"$SCW_VALIDATION_KEY\"
270+
}"
271+
```
272+
</TabsTab>
273+
</Tabs>
274+
275+
<Message type="important">
276+
After the migration, your volume's type will still be `b_ssd` (displayed as **Block SSD 5K legacy** in the Scaleway console).
277+
To benefit from the new features and performance of Scaleway Block Storage, you must create a new volume (`sbs_5k` or `sbs_15k` displayed as **Block Low Latency 5K** or **Block Low Latency 15K** in the Scaleway console) using the snapshot export/import feature. For more information, see [Migrating using the snapshot export/import features](#migrating-using-the-snapshot-exportimport-features).
278+
</Message>
279+
280+
## Migrating using the snapshot export/import features
281+
282+
To convert your unified volumes and snapshots, you can use the snapshot export/import features as an alternative solution for transitioning a Block Storage legacy volume into a Block Storage Low Latency volume.
283+
284+
<Message type="important">
285+
The process below requires manual intervention and **does not preserve the original volume’s ID**. While this approach allows you to transition to a Block Storage Low Latency volume, it is only a workaround.
286+
</Message>
287+
288+
Follow the procedure below:
289+
290+
1. [Create a snapshot of your Block Storage legacy volume](/block-storage/how-to/create-a-snapshot/).
291+
2. [Export the snapshot](/instances/api-cli/snapshot-import-export-feature/#exporting-snapshots).
292+
3. [Import the snapshot into a new Low Latency volume](https://www.scaleway.com/en/developers/api/block/#path-snapshot-import-a-snapshot-from-a-scaleway-object-storage-bucket).
293+
294+
295+
## Going further
296+
297+
To learn more about managing your migrated Block Storage volumes and snapshots from the Scaleway console, refer to the [Block Storage Quickstart Guide](/block-storage/quickstart/). Additionally, you can explore advanced features using the [Scaleway Block Storage API](https://www.scaleway.com/en/developers/api/block/).
298+
299+
If you encounter any issues during migration, contact [Scaleway's support team](https://console.scaleway.com/support/tickets) for assistance.

‎menu/navigation.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4776,6 +4776,10 @@
47764776
"label": "Identify which API is managing your volumes",
47774777
"slug": "identify-api-managing-volumes"
47784778
},
4779+
{
4780+
"label": "Migrate volumes and snapshots to Scaleway SBS",
4781+
"slug": "migrate-volumes-snapshots-to-sbs"
4782+
},
47794783
{
47804784
"label": "Detach a volume",
47814785
"slug": "detach-a-volume"

0 commit comments

Comments
 (0)