feat(instance): add RPC for volume/snapshot migration to SBS (#853)

Author: scaleway-bot

packages/clients/src/api/instance/v1/api.gen.ts

@@ -8,6 +8,7 @@ import {
 } from '../../../bridge'
 import type { Zone } from '../../../bridge'
 import {
+  marshalApplyBlockMigrationRequest,
   marshalCreateImageRequest,
   marshalCreateIpRequest,
   marshalCreatePlacementGroupRequest,
@@ -18,6 +19,7 @@ import {
   marshalCreateSnapshotRequest,
   marshalCreateVolumeRequest,
   marshalExportSnapshotRequest,
+  marshalPlanBlockMigrationRequest,
   marshalServerActionRequest,
   marshalSetImageRequest,
   marshalSetPlacementGroupRequest,
@@ -70,6 +72,7 @@ import {
   unmarshalListSnapshotsResponse,
   unmarshalListVolumesResponse,
   unmarshalListVolumesTypesResponse,
+  unmarshalMigrationPlan,
   unmarshalPrivateNIC,
   unmarshalServerActionResponse,
   unmarshalSetImageResponse,
@@ -87,6 +90,7 @@ import {
   unmarshalUpdateVolumeResponse,
 } from './marshalling.gen'
 import type {
+  ApplyBlockMigrationRequest,
   CreateImageRequest,
   CreateImageResponse,
   CreateIpRequest,
@@ -171,6 +175,8 @@ import type {
   ListVolumesResponse,
   ListVolumesTypesRequest,
   ListVolumesTypesResponse,
+  MigrationPlan,
+  PlanBlockMigrationRequest,
   PrivateNIC,
   ServerActionRequest,
   ServerActionResponse,
@@ -1708,4 +1714,53 @@ export class API extends ParentAPI {
       },
       unmarshalGetDashboardResponse,
     )
+
+  /**
+   * Get a volume or snapshot's migration plan. Given a volume or snapshot,
+   * returns the migration plan for a call to the RPC ApplyBlockMigration. This
+   * plan will include zero or one volume, and zero or more snapshots, which
+   * will need to be migrated together. This RPC does not perform the actual
+   * migration itself, ApplyBlockMigration must be used. The validation_key
+   * value returned by this call must be provided to the ApplyBlockMigration
+   * call to confirm that all resources listed in the plan should be migrated.
+   *
+   * @param request - The request {@link PlanBlockMigrationRequest}
+   * @returns A Promise of MigrationPlan
+   */
+  planBlockMigration = (request: Readonly<PlanBlockMigrationRequest> = {}) =>
+    this.client.fetch<MigrationPlan>(
+      {
+        body: JSON.stringify(
+          marshalPlanBlockMigrationRequest(request, this.client.settings),
+        ),
+        headers: jsonContentHeaders,
+        method: 'POST',
+        path: `/instance/v1/zones/${validatePathParam(
+          'zone',
+          request.zone ?? this.client.settings.defaultZone,
+        )}/block-migration/plan`,
+      },
+      unmarshalMigrationPlan,
+    )
+
+  /**
+   * Migrate a volume and/or snapshots to SBS (Scaleway Block Storage). To be
+   * used, this RPC must be preceded by a call to PlanBlockMigration. To migrate
+   * all resources mentioned in the MigrationPlan, the validation_key returned
+   * in the MigrationPlan must be provided.
+   *
+   * @param request - The request {@link ApplyBlockMigrationRequest}
+   */
+  applyBlockMigration = (request: Readonly<ApplyBlockMigrationRequest>) =>
+    this.client.fetch<void>({
+      body: JSON.stringify(
+        marshalApplyBlockMigrationRequest(request, this.client.settings),
+      ),
+      headers: jsonContentHeaders,
+      method: 'POST',
+      path: `/instance/v1/zones/${validatePathParam(
+        'zone',
+        request.zone ?? this.client.settings.defaultZone,
+      )}/block-migration/apply`,
+    })
 }

packages/clients/src/api/instance/v1/index.gen.ts

@@ -3,6 +3,7 @@
 export { API } from './api.gen'
 export * from './content.gen'
 export type {
+  ApplyBlockMigrationRequest,
   Arch,
   BootType,
   Bootscript,
@@ -98,10 +99,12 @@ export type {
   ListVolumesResponse,
   ListVolumesTypesRequest,
   ListVolumesTypesResponse,
+  MigrationPlan,
   PlacementGroup,
   PlacementGroupPolicyMode,
   PlacementGroupPolicyType,
   PlacementGroupServer,
+  PlanBlockMigrationRequest,
   PrivateNIC,
   PrivateNICState,
   SecurityGroup,

packages/clients/src/api/instance/v1/marshalling.gen.ts

@@ -10,6 +10,7 @@ import {
 } from '../../../bridge'
 import type { DefaultValues } from '../../../bridge'
 import type {
+  ApplyBlockMigrationRequest,
   Bootscript,
   CreateImageRequest,
   CreateImageResponse,
@@ -61,8 +62,10 @@ import type {
   ListSnapshotsResponse,
   ListVolumesResponse,
   ListVolumesTypesResponse,
+  MigrationPlan,
   PlacementGroup,
   PlacementGroupServer,
+  PlanBlockMigrationRequest,
   PrivateNIC,
   SecurityGroup,
   SecurityGroupRule,
@@ -1210,6 +1213,20 @@ export const unmarshalListVolumesTypesResponse = (data: unknown) => {
   } as ListVolumesTypesResponse
 }
 
+export const unmarshalMigrationPlan = (data: unknown) => {
+  if (!isJSONObject(data)) {
+    throw new TypeError(
+      `Unmarshalling the type 'MigrationPlan' failed as data isn't a dictionary.`,
+    )
+  }
+
+  return {
+    snapshots: unmarshalArrayOfObject(data.snapshots, unmarshalSnapshot),
+    validationKey: data.validation_key,
+    volume: data.volume ? unmarshalVolume(data.volume) : undefined,
+  } as MigrationPlan
+}
+
 export const unmarshalServerActionResponse = (data: unknown) => {
   if (!isJSONObject(data)) {
     throw new TypeError(
@@ -1624,6 +1641,23 @@ const marshalVolumeTemplate = (
   ]),
 })
 
+export const marshalApplyBlockMigrationRequest = (
+  request: ApplyBlockMigrationRequest,
+  defaults: DefaultValues,
+): Record<string, unknown> => ({
+  validation_key: request.validationKey,
+  ...resolveOneOf([
+    {
+      param: 'volume_id',
+      value: request.volumeId,
+    },
+    {
+      param: 'snapshot_id',
+      value: request.snapshotId,
+    },
+  ]),
+})
+
 export const marshalCreateImageRequest = (
   request: CreateImageRequest,
   defaults: DefaultValues,
@@ -1866,6 +1900,22 @@ export const marshalExportSnapshotRequest = (
   key: request.key,
 })
 
+export const marshalPlanBlockMigrationRequest = (
+  request: PlanBlockMigrationRequest,
+  defaults: DefaultValues,
+): Record<string, unknown> => ({
+  ...resolveOneOf([
+    {
+      param: 'volume_id',
+      value: request.volumeId,
+    },
+    {
+      param: 'snapshot_id',
+      value: request.snapshotId,
+    },
+  ]),
+})
+
 export const marshalServerActionRequest = (
   request: ServerActionRequest,
   defaults: DefaultValues,

packages/clients/src/api/instance/v1/types.gen.ts

@@ -388,6 +388,25 @@ export interface ListVolumesTypesResponse {
   volumes: Record<string, VolumeType>
 }
 
+/** Migration plan. */
+export interface MigrationPlan {
+  /**
+   * A volume which will be migrated to SBS together with the snapshots, if
+   * present.
+   */
+  volume?: Volume
+  /**
+   * A list of snapshots which will be migrated to SBS together and with the
+   * volume, if present.
+   */
+  snapshots: Snapshot[]
+  /**
+   * A value to be passed to ApplyBlockMigrationRequest, to confirm that the
+   * execution of the plan is being requested.
+   */
+  validationKey: string
+}
+
 /** Placement group. */
 export interface PlacementGroup {
   /** Placement group unique ID. */
@@ -1742,3 +1761,44 @@ export type GetDashboardRequest = {
   organization?: string
   project?: string
 }
+
+export type PlanBlockMigrationRequest = {
+  /** Zone to target. If none is passed will use default zone from the config. */
+  zone?: Zone
+  /**
+   * The volume for which the migration plan will be generated.
+   *
+   * One-of ('resource'): at most one of 'volumeId', 'snapshotId' could be set.
+   */
+  volumeId?: string
+  /**
+   * The snapshot for which the migration plan will be generated.
+   *
+   * One-of ('resource'): at most one of 'volumeId', 'snapshotId' could be set.
+   */
+  snapshotId?: string
+}
+
+export type ApplyBlockMigrationRequest = {
+  /** Zone to target. If none is passed will use default zone from the config. */
+  zone?: Zone
+  /**
+   * The volume to migrate, along with potentially other resources, according to
+   * the migration plan generated with a call to PlanBlockMigration.
+   *
+   * One-of ('resource'): at most one of 'volumeId', 'snapshotId' could be set.
+   */
+  volumeId?: string
+  /**
+   * The snapshot to migrate, along with potentially other resources, according
+   * to the migration plan generated with a call to PlanBlockMigration.
+   *
+   * One-of ('resource'): at most one of 'volumeId', 'snapshotId' could be set.
+   */
+  snapshotId?: string
+  /**
+   * A value to be retrieved from a call to PlanBlockMigration, to confirm that
+   * the volume and/or snapshots specified in said plan should be migrated.
+   */
+  validationKey: string
+}