22title : Add supported image formats in sm-list
33layout : default
44design_doc : true
5- revision : 2
5+ revision : 3
66status : proposed
77---
88
@@ -22,32 +22,16 @@ available formats.
2222# Design Proposal
2323
2424To expose the available image formats to clients (e.g., XenCenter, XenOrchestra, etc.),
25- we propose adding a new field called ` supported-image-formats ` to the Storage Manager (SM)
26- module. This field will be included in the output of the ` SM.get_all_records ` call.
25+ we propose adding a new field called ` supported_image_formats ` to the Storage Manager
26+ (SM) module. This field will be included in the output of the ` SM.get_all_records ` call.
2727
28- The ` supported-image-formats ` field will be populated by retrieving information
29- from the SMAPI drivers. Specifically, each driver will update its ` DRIVER_INFO `
30- dictionary with a new key, ` supported_image_formats ` , which will contain a list
31- of strings representing the supported image formats
32- (for example: ` ["vhd", "raw", "qcow2"] ` ).
33-
34- The list designates the driver's preferred VDI format as its first entry. That
35- means that when migrating a VDI, the destination storage repository will
36- attempt to create a VDI in this preferred format. If the default format cannot
37- be used (e.g., due to size limitations), an error will be generated.
38-
39- If a driver does not provide this information (as is currently the case with existing
40- drivers), the default value will be an empty array. This signifies that it is the
41- driver that decides which format it will use. This ensures that the modification
42- remains compatible with both current and future drivers.
43-
44- With this new information, listing all parameters of the SM object will return:
28+ - With this new information, listing all parameters of the SM object will return:
4529
4630``` bash
4731# xe sm-list params=all
4832```
4933
50- will output something like:
34+ Output of the command will look like (notice that CLI uses hyphens) :
5135
5236```
5337uuid ( RO) : c6ae9a43-fff6-e482-42a9-8c3f8c533e36
@@ -65,12 +49,118 @@ required-cluster-stack ( RO) :
6549supported-image-formats ( RO) : vhd, raw, qcow2
6650```
6751
68- This change impacts the SM data model, and as such, the XAPI database version will
69- be incremented.
52+ ## Implementation details
53+
54+ The ` supported_image_formats ` field will be populated by retrieving information
55+ from the SMAPI drivers. Specifically, each driver will update its ` DRIVER_INFO `
56+ dictionary with a new key, ` supported_image_formats ` , which will contain a list
57+ of strings representing the supported image formats
58+ (for example: ` ["vhd", "raw", "qcow2"] ` ). Although the formats are listed as a
59+ list of strings, they are treated as a set-specifying the same format multiple
60+ times has no effect.
61+
62+ ### Driver behavior without ` supported_image_formats `
63+
64+ If a driver does not provide this information (as is currently the case with
65+ existing drivers), the default value will be an empty list. This signifies
66+ that the driver determines which format to use when creating VDI. During a migration,
67+ the destination driver will choose the format of the VDI if none is explicitly
68+ specified. This ensures backward compatibility with both current and future drivers.
69+
70+ ### Specifying image formats for VDIs creation
71+
72+ If the supported image format is exposed to the client, then, when creating new VDI,
73+ user can specify the desired format via the ` sm_config ` parameter ` image-format=qcow2 ` (or
74+ any format that is supported). If no format is specified, the driver will use its
75+ preferred default format. If the specified format is not supported, an error will be
76+ generated indicating that the SR does not support it. Here is how it can be achieved
77+ using the XE CLI:
78+
79+ ``` bash
80+ # xe vdi-create \
81+ sr-uuid=cbe2851e-9f9b-f310-9bca-254c1cf3edd8 \
82+ name-label=" A new VDI"
83+ virtual-size=10240 \
84+ sm-config:image-format=vhd
85+ ```
86+
87+ ### Specifying image formats for VDIs migration
88+
89+ When migrating a VDI, an API client may need to specify the desired image format if
90+ the destination SR supports multiple storage formats.
91+
92+ #### VDI pool migrate
93+
94+ To support this, a new parameter, ` dest_img_format ` , is introduced to
95+ ` VDI.pool_migrate ` . This field accepts a string specifying the desired format (e.g., * qcow2* ),
96+ ensuring that the VDI is migrated in the correct format. The new signature of
97+ ` VDI.pool_migrate ` will be
98+ ` VDI ref pool_migrate (session ref, VDI ref, SR ref, string, (string -> string) map) ` .
99+
100+ If the specified format is not supported or cannot be used (e.g., due to size limitations),
101+ an error will be generated. Validation will be performed as early as possible to prevent
102+ disruptions during migration. These checks can be performed by examining the XAPI database
103+ to determine whether the SR provided as the destination has a corresponding SM object with
104+ the expected format. If this is not the case, a ` format not found ` error will be returned.
105+ If no format is specified by the client, the destination driver will determine the appropriate
106+ format.
107+
108+ ``` bash
109+ # xe vdi-pool-migrate \
110+ uuid=< VDI_UUID> \
111+ sr-uuid=< SR_UUID> \
112+ dest-img-format=qcow2
113+ ```
114+
115+ #### VM migration to remote host
116+
117+ A VDI migration can also occur during a VM migration. In this case, we need to
118+ be able to specify the expected destination format as well. Unlike ` VDI.pool_migrate ` ,
119+ which applies to a single VDI, VM migration may involve multiple VDIs.
120+ The current signature of ` VM.migrate_send ` is `(session ref, VM ref, (string -> string) map,
121+ bool, (VDI ref -> SR ref) map, (VIF ref -> network ref) map, (string -> string) map,
122+ (VGPU ref -> GPU_group ref) map)`. Thus there is already a parameter that maps each source
123+ VDI to its destination SR. We propose to add a new parameter that allows specifying the
124+ desired destination format for a given source VDI: ` (VDI ref -> string) ` . It is
125+ similar to the VDI-to-SR mapping. We will update the XE cli to support this new format.
126+ It would be ` image_format:<source-vdi-uuid>=<destination-image-format> ` :
127+
128+ ``` bash
129+ # xe vm-migrate \
130+ host-uuid=< HOST_UUID> \
131+ remote-master=< IP> \
132+ remote-password=< PASS> \
133+ remote-username=< USER> \
134+ vdi:< VDI1_UUID> =< SR1_DEST_UUID> \
135+ vdi:< VDI2_UUID> =< SR2_DEST_UUID> \
136+ image-format:< VDI1_UUID> =vhd \
137+ image-format:< VDI2_UUID> =qcow2 \
138+ uuid=< VM_UUID>
139+ ```
140+ The destination image format would be a string such as * vhd* , * qcow2* , or another
141+ supported format. It is optional to specify a format. If omitted, the driver
142+ managing the destination SR will determine the appropriate format.
143+ As with VDI pool migration, if this parameter is not supported by the SM driver,
144+ a ` format not found ` error will be returned. The validation must happen before
145+ sending a creation message to the SM driver, ideally at the same time as checking
146+ whether all VDIs can be migrated.
147+
148+ To be able to check the format, we will need to modify ` VM.assert_can_migrate ` and
149+ add the mapping from VDI references to their image formats, as is done in ` VM.migrate_send ` .
70150
71151# Impact
72152
73- - ** Data Model:** A new field (` supported-image-formats ` ) is added to the SM records.
153+ It should have no impact on existing storage repositories that do not provide any information
154+ about the supported image format.
155+
156+ This change impacts the SM data model, and as such, the XAPI database version will
157+ be incremented. It also impacts the API.
158+
159+ - ** Data Model:**
160+ - A new field (` supported_image_formats ` ) is added to the SM records.
161+ - A new parameter is added to ` VM.migrate_send ` : ` (VDI ref -> string) map `
162+ - A new parameter is added to ` VM.assert_can_migrate ` : ` (VDI ref -> string) map `
163+ - A new parameter is added to ` VDI.pool_migrate ` : ` string `
74164- ** Client Awareness:** Clients like the ` xe ` CLI will now be able to query and display the supported image formats for a given SR.
75165- ** Database Versioning:** The XAPI database version will be updated to reflect this change.
76166
0 commit comments