MAAS

Merge ~jsseidel/maas:jsseidel-volume_groups-api-annotations into maas:master

  1. Git
  2. lp:~jsseidel/maas
  3. jsseidel-volume_groups-api-annotations
  4. Merge into master
Proposed by Spencer Seidel
Status: Merged
Approved by: Spencer Seidel
Approved revision: 6a0da671e18bd3e899238eae22f0ba79ee8781d8
Merge reported by: MAAS Lander
Merged at revision: not available
Proposed branch: ~jsseidel/maas:jsseidel-volume_groups-api-annotations
Merge into: maas:master
Diff against target: 429 lines (+322/-39)
2 files modified
src/maasserver/api/examples/nodes.json (+156/-0)
src/maasserver/api/volume_groups.py (+166/-39)
Reviewer Review Type Date Requested Status
MAAS Lander Approve
Mike Pontillo (community) Approve
Review via email: mp+361215@code.launchpad.net

Commit message

Added API annotations and examples.

To post a comment you must log in.
Revision history for this message
Mike Pontillo (mpontillo) wrote :

Looks good!

review: Approve
Revision history for this message
MAAS Lander (maas-lander) wrote :

UNIT TESTS
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 46aec69dc9f633670b993ffbddaf31fa6ae52f9f

review: Approve
Revision history for this message
MAAS Lander (maas-lander) wrote :

LANDING
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-tester/4818/consoleText

Revision history for this message
MAAS Lander (maas-lander) wrote :

LANDING
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-tester/4821/consoleText

Revision history for this message
MAAS Lander (maas-lander) wrote :

UNIT TESTS
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-tester/4833/console
COMMIT: 70778b81f1ee45686fea5b12cd47d5d9235b0ac9

review: Needs Fixing
Revision history for this message
MAAS Lander (maas-lander) wrote :

LANDING
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-tester/4836/consoleText

Revision history for this message
MAAS Lander (maas-lander) wrote :

UNIT TESTS
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 6a0da671e18bd3e899238eae22f0ba79ee8781d8

review: Approve
Revision history for this message
MAAS Lander (maas-lander) wrote :

LANDING
-b jsseidel-volume_groups-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-tester/4838/consoleText

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/src/maasserver/api/examples/nodes.json b/src/maasserver/api/examples/nodes.json
2index b862bb4..7d9b088 100644
3--- a/src/maasserver/api/examples/nodes.json
4+++ b/src/maasserver/api/examples/nodes.json
5@@ -5224,6 +5224,162 @@
6 "type": "physical",
7 "resource_uri": "/MAAS/api/2.0/nodes/thr3am/interfaces/37/"
8 },
9+ "vol-groups-read": [
10+ {
11+ "logical_volumes": [],
12+ "system_id": "ccrfnk",
13+ "human_size": "8.0 GB",
14+ "human_used_size": "0 bytes",
15+ "uuid": "36f9585d-3ae0-429c-abb7-9d584bc6f941",
16+ "human_available_size": "8.0 GB",
17+ "used_size": 0,
18+ "name": "my_volume_group",
19+ "size": 7990149120,
20+ "devices": [
21+ {
22+ "uuid": "ecfa7d5b-bb76-4443-83ab-ad600c23b4de",
23+ "size": 7994343424,
24+ "bootable": false,
25+ "tags": [],
26+ "system_id": "ccrfnk",
27+ "filesystem": {
28+ "fstype": "lvm-pv",
29+ "label": null,
30+ "uuid": "cad18fde-2fc7-4aa5-a15b-739f88c3b671",
31+ "mount_point": null,
32+ "mount_options": null
33+ },
34+ "used_for": "LVM volume for my_volume_group",
35+ "type": "partition",
36+ "path": "/dev/disk/by-dname/vda-part1",
37+ "id": 2,
38+ "device_id": 1,
39+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/blockdevices/1/partition/2"
40+ }
41+ ],
42+ "available_size": 7990149120,
43+ "id": 1,
44+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/volume-group/1/"
45+ }
46+ ],
47+ "vol-groups-create": {
48+ "available_size": 7990149120,
49+ "size": 7990149120,
50+ "human_used_size": "0 bytes",
51+ "devices": [
52+ {
53+ "uuid": "ecfa7d5b-bb76-4443-83ab-ad600c23b4de",
54+ "size": 7994343424,
55+ "bootable": false,
56+ "tags": [],
57+ "used_for": "LVM volume for my_volume_group",
58+ "device_id": 1,
59+ "path": "/dev/disk/by-dname/vda-part1",
60+ "id": 2,
61+ "filesystem": {
62+ "fstype": "lvm-pv",
63+ "label": null,
64+ "uuid": "cad18fde-2fc7-4aa5-a15b-739f88c3b671",
65+ "mount_point": null,
66+ "mount_options": null
67+ },
68+ "type": "partition",
69+ "system_id": "ccrfnk",
70+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/blockdevices/1/partition/2"
71+ }
72+ ],
73+ "logical_volumes": [],
74+ "id": 1,
75+ "used_size": 0,
76+ "human_size": "8.0 GB",
77+ "human_available_size": "8.0 GB",
78+ "system_id": "ccrfnk",
79+ "uuid": "36f9585d-3ae0-429c-abb7-9d584bc6f941",
80+ "name": "my_volume_group",
81+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/volume-group/1/"
82+ },
83+ "vol-groups-read-by-id": {
84+ "human_used_size": "0 bytes",
85+ "uuid": "36f9585d-3ae0-429c-abb7-9d584bc6f941",
86+ "human_available_size": "8.0 GB",
87+ "system_id": "ccrfnk",
88+ "id": 1,
89+ "logical_volumes": [],
90+ "size": 7990149120,
91+ "devices": [
92+ {
93+ "uuid": "ecfa7d5b-bb76-4443-83ab-ad600c23b4de",
94+ "size": 7994343424,
95+ "bootable": false,
96+ "tags": [],
97+ "system_id": "ccrfnk",
98+ "id": 2,
99+ "used_for": "LVM volume for my_volume_group",
100+ "type": "partition",
101+ "path": "/dev/disk/by-dname/vda-part1",
102+ "device_id": 1,
103+ "filesystem": {
104+ "fstype": "lvm-pv",
105+ "label": null,
106+ "uuid": "cad18fde-2fc7-4aa5-a15b-739f88c3b671",
107+ "mount_point": null,
108+ "mount_options": null
109+ },
110+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/blockdevices/1/partition/2"
111+ }
112+ ],
113+ "available_size": 7990149120,
114+ "used_size": 0,
115+ "human_size": "8.0 GB",
116+ "name": "my_volume_group",
117+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/volume-group/1/"
118+ },
119+ "vol-groups-update": {
120+ "human_used_size": "0 bytes",
121+ "uuid": "36f9585d-3ae0-429c-abb7-9d584bc6f941",
122+ "human_available_size": "8.0 GB",
123+ "system_id": "ccrfnk",
124+ "id": 1,
125+ "logical_volumes": [],
126+ "size": 7990149120,
127+ "devices": [
128+ {
129+ "uuid": "ecfa7d5b-bb76-4443-83ab-ad600c23b4de",
130+ "size": 7994343424,
131+ "bootable": false,
132+ "tags": [],
133+ "system_id": "ccrfnk",
134+ "id": 2,
135+ "used_for": "LVM volume for my_volume_group",
136+ "type": "partition",
137+ "path": "/dev/disk/by-dname/vda-part1",
138+ "device_id": 1,
139+ "filesystem": {
140+ "fstype": "lvm-pv",
141+ "label": null,
142+ "uuid": "cad18fde-2fc7-4aa5-a15b-739f88c3b671",
143+ "mount_point": null,
144+ "mount_options": null
145+ },
146+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/blockdevices/1/partition/2"
147+ }
148+ ],
149+ "available_size": 7990149120,
150+ "used_size": 0,
151+ "human_size": "8.0 GB",
152+ "name": "my_volume_group",
153+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/volume-group/1/"
154+ },
155+ "vol-groups-create-log-vol": {
156+ "system_id": "ccrfnk",
157+ "uuid": "5b805aa2-3614-4b70-b99c-9c3ff65df4c3",
158+ "used_size": 0,
159+ "name": "my_volume_group-my_logical_volume",
160+ "size": 4194304,
161+ "available_size": 4194304,
162+ "id": 2,
163+ "resource_uri": "/MAAS/api/2.0/nodes/ccrfnk/blockdevices/2/"
164+ },
165 "partitions-read": [
166 {
167 "id_path": "/dev/vda",
168diff --git a/src/maasserver/api/volume_groups.py b/src/maasserver/api/volume_groups.py
169index 01fb954..ec82e78 100644
170--- a/src/maasserver/api/volume_groups.py
171+++ b/src/maasserver/api/volume_groups.py
172@@ -56,24 +56,62 @@ class VolumeGroupsHandler(OperationsHandler):
173 return ('volume_groups_handler', ["system_id"])
174
175 def read(self, request, system_id):
176- """List all volume groups belonging to a machine.
177-
178- Returns 404 if the machine is not found.
179+ """@description-title List all volume groups
180+ @description List all volume groups belonging to a machine with the
181+ given system_id.
182+
183+ @param (string) "{system_id}" [required=true] The machine system_id
184+ containing the volume groups.
185+
186+ @success (http-status-code) "server-success" 200
187+ @success (json) "success-json" A JSON object containing a list of
188+ volume-group objects.
189+ @success-example "success-json" [exkey=vol-groups-read] placeholder
190+ text
191+
192+ @error (http-status-code) "404" 404
193+ @error (content) "not-found" The requested machine is not found.
194+ @error-example "not-found"
195+ Not Found
196 """
197 machine = Machine.objects.get_node_or_404(
198 system_id, request.user, NodePermission.view)
199 return VolumeGroup.objects.filter_by_node(machine)
200
201 def create(self, request, system_id):
202- """Create a volume group belonging to machine.
203+ """@description-title Create a volume group
204+ @description Create a volume group belonging to a machine with the
205+ given system_id.
206+
207+ Note that at least one valid block device or partition is required.
208+
209+ @param (string) "{system_id}" [required=true] The machine system_id on
210+ which to create the volume group.
211+
212+ @param (string) "name" [required=true] Name of the volume group.
213+
214+ @param (string) "uuid" [required=false] (optional) UUID of the volume
215+ group.
216+
217+ @param (string) "block_devices" [required=false] Block devices to add
218+ to the volume group.
219+
220+ @param (string) "partitions" [required=false] Partitions to add to the
221+ volume group.
222+
223+ @success (http-status-code) "server-success" 200
224+ @success (json) "success-json" A JSON object containing the new volume
225+ group.
226+ @success-example "success-json" [exkey=vol-groups-create] placeholder
227+ text
228
229- :param name: Name of the volume group.
230- :param uuid: (optional) UUID of the volume group.
231- :param block_devices: Block devices to add to the volume group.
232- :param partitions: Partitions to add to the volume group.
233+ @error (http-status-code) "404" 404
234+ @error (content) "not-found" The requested machine is not found.
235+ @error-example "not-found"
236+ Not Found
237
238- Returns 404 if the machine is not found.
239- Returns 409 if the machine is not Ready.
240+ @error (http-status-code) "409" 409
241+ @error (content) "not-ready" The requested machine is not ready.
242 """
243 machine = Machine.objects.get_node_or_404(
244 system_id, request.user, NodePermission.admin)
245@@ -150,26 +188,66 @@ class VolumeGroupHandler(OperationsHandler):
246 ]
247
248 def read(self, request, system_id, id):
249- """Read volume group on a machine.
250-
251- Returns 404 if the machine or volume group is not found.
252+ """@description-title Read a volume group
253+ @description Read a volume group with the given id on the machine with
254+ the given system_id.
255+
256+ @param (string) "{system_id}" [required=true] The machine system_id on
257+ which to create the volume group.
258+ @param (int) "{id}" [required=true] The id of the volume group.
259+
260+ @success (http-status-code) "server-success" 200
261+ @success (json) "success-json" A JSON object containing the requested
262+ volume group.
263+ @success-example "success-json" [exkey=vol-groups-read-by-id]
264+ placeholder text
265+
266+ @error (http-status-code) "404" 404
267+ @error (content) "not-found" The requested machine is not found.
268+ @error-example "not-found"
269+ Not Found
270 """
271 return VolumeGroup.objects.get_object_or_404(
272 system_id, id, request.user, NodePermission.view)
273
274 def update(self, request, system_id, id):
275- """Read volume group on a machine.
276-
277- :param name: Name of the volume group.
278- :param uuid: UUID of the volume group.
279- :param add_block_devices: Block devices to add to the volume group.
280- :param remove_block_devices: Block devices to remove from the
281- volume group.
282- :param add_partitions: Partitions to add to the volume group.
283- :param remove_partitions: Partitions to remove from the volume group.
284-
285- Returns 404 if the machine or volume group is not found.
286- Returns 409 if the machine is not Ready.
287+ """@description-title Update a volume group
288+ @description Update a volume group with the given id on the machine
289+ with the given system_id.
290+
291+ @param (string) "{system_id}" [required=true] The machine system_id
292+ containing the volume group.
293+ @param (int) "{id}" [required=true] The id of the volume group.
294+
295+ @param (string) "name" [required=false] Name of the volume group.
296+
297+ @param (string) "uuid" [required=false] UUID of the volume group.
298+
299+ @param (string) "add_block_devices" [required=false] Block devices to
300+ add to the volume group.
301+
302+ @param (string) "remove_block_devices" [required=false] Block devices
303+ to remove from the volume group.
304+
305+ @param (string) "add_partitions" [required=false] Partitions to add to
306+ the volume group.
307+
308+ @param (string) "remove_partitions" [required=false] Partitions to
309+ remove from the volume group.
310+
311+ @success (http-status-code) "server-success" 200
312+ @success (json) "success-json" A JSON object containing the requested
313+ volume group.
314+ @success-example "success-json" [exkey=vol-groups-update]
315+ placeholder text
316+
317+ @error (http-status-code) "404" 404
318+ @error (content) "not-found" The requested machine is not found.
319+ @error-example "not-found"
320+ Not Found
321+
322+ @error (http-status-code) "409" 409
323+ @error (content) "not-ready" The requested machine is not ready.
324 """
325 volume_group = VolumeGroup.objects.get_object_or_404(
326 system_id, id, request.user, NodePermission.admin)
327@@ -184,10 +262,23 @@ class VolumeGroupHandler(OperationsHandler):
328 return form.save()
329
330 def delete(self, request, system_id, id):
331- """Delete volume group on a machine.
332+ """@description-title Delete volume group
333+ @description Delete a volume group with the given id from the machine
334+ with the given system_id.
335+
336+ @param (string) "{system_id}" [required=true] The machine system_id
337+ containing the volume group.
338+ @param (int) "{id}" [required=true] The id of the volume group.
339
340- Returns 404 if the machine or volume group is not found.
341- Returns 409 if the machine is not Ready.
342+ @success (http-status-code) "server-success" 204
343+
344+ @error (http-status-code) "404" 404
345+ @error (content) "not-found" The requested machine is not found.
346+ @error-example "not-found"
347+ Not Found
348+
349+ @error (http-status-code) "409" 409
350+ @error (content) "not-ready" The requested machine is not ready.
351 """
352 volume_group = VolumeGroup.objects.get_object_or_404(
353 system_id, id, request.user, NodePermission.admin)
354@@ -200,14 +291,35 @@ class VolumeGroupHandler(OperationsHandler):
355
356 @operation(idempotent=False)
357 def create_logical_volume(self, request, system_id, id):
358- """Create a logical volume in the volume group.
359+ """@description-title Create a logical volume
360+ @description Create a logical volume in the volume group with the given
361+ id on the machine with the given system_id.
362+
363+ @param (string) "{system_id}" [required=true] The machine system_id
364+ containing the volume group.
365+ @param (int) "{id}" [required=true] The id of the volume group.
366+
367+ @param (string) "name" [required=true] Name of the logical volume.
368
369- :param name: Name of the logical volume.
370- :param uuid: (optional) UUID of the logical volume.
371- :param size: Size of the logical volume.
372+ @param (string) "uuid" [required=false] (optional) UUID of the logical
373+ volume.
374
375- Returns 404 if the machine or volume group is not found.
376- Returns 409 if the machine is not Ready.
377+ @param (string) "size" [required=true] Size of the logical volume. Must
378+ be larger than or equal to 4,194,304 bytes. E.g. ``4194304``.
379+
380+ @success (http-status-code) "server-success" 200
381+ @success (json) "success-json" A JSON object containing the requested
382+ volume group.
383+ @success-example "success-json" [exkey=vol-groups-create-log-vol]
384+ placeholder text
385+
386+ @error (http-status-code) "404" 404
387+ @error (content) "not-found" The requested machine is not found.
388+ @error-example "not-found"
389+ Not Found
390+
391+ @error (http-status-code) "409" 409
392+ @error (content) "not-ready" The requested machine is not ready.
393 """
394 volume_group = VolumeGroup.objects.get_object_or_404(
395 system_id, id, request.user, NodePermission.admin)
396@@ -224,13 +336,28 @@ class VolumeGroupHandler(OperationsHandler):
397
398 @operation(idempotent=False)
399 def delete_logical_volume(self, request, system_id, id):
400- """Delete a logical volume in the volume group.
401+ """@description-title Delete a logical volume
402+ @description Delete a logical volume in the volume group with the given
403+ id on the machine with the given system_id.
404+
405+ Note: this operation returns HTTP status code 204 even if the logical
406+ volume id does not exist.
407+
408+ @param (string) "{system_id}" [required=true] The machine system_id
409+ containing the volume group.
410+ @param (int) "{id}" [required=true] The id of the volume group.
411+
412+ @param (int) "id" [required=true] The logical volume id.
413+
414+ @success (http-status-code) "server-success" 204
415
416- :param id: ID of the logical volume.
417+ @error (http-status-code) "404" 404
418+ @error (content) "not-found" The requested machine is not found.
419+ @error-example "not-found"
420+ Not Found
421
422- Returns 403 if no logical volume with id.
423- Returns 404 if the machine or volume group is not found.
424- Returns 409 if the machine is not Ready.
425+ @error (http-status-code) "409" 409
426+ @error (content) "not-ready" The requested machine is not ready.
427 """
428 volume_group = VolumeGroup.objects.get_object_or_404(
429 system_id, id, request.user, NodePermission.admin)

Subscribers

People subscribed via source and target branches