summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorimacdonn <iain.macdonnell@oracle.com>2018-11-07 17:45:45 +0000
committerimacdonn <iain.macdonnell@oracle.com>2018-11-07 17:46:32 +0000
commit49d3191cde5f6ebbd27042fc64858dd46816eb06 (patch)
treee1f5e3c632524d02eba5c26418d39509092e17e9
parentb75826eeba58bcf45954cc91640900185f1f7b33 (diff)
spec-lite: Embed validation data in locations
Notes
Notes (review): Code-Review+2: Erno Kuvaja <jokke@usr.fi> Workflow+1: Erno Kuvaja <jokke@usr.fi> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Thu, 08 Nov 2018 05:47:29 +0000 Reviewed-on: https://review.openstack.org/597648 Project: openstack/glance-specs Branch: refs/heads/master
-rw-r--r--specs/stein/approved/glance/spec-lite-locations-with-validation-data.rst102
-rw-r--r--specs/stein/approved/index.rst8
2 files changed, 110 insertions, 0 deletions
diff --git a/specs/stein/approved/glance/spec-lite-locations-with-validation-data.rst b/specs/stein/approved/glance/spec-lite-locations-with-validation-data.rst
new file mode 100644
index 0000000..05e4f10
--- /dev/null
+++ b/specs/stein/approved/glance/spec-lite-locations-with-validation-data.rst
@@ -0,0 +1,102 @@
1..
2 This work is licensed under a Creative Commons Attribution 3.0 Unported
3 License.
4
5 http://creativecommons.org/licenses/by/3.0/legalcode
6
7=====================================================
8Spec Lite: Embed validation data with image locations
9=====================================================
10
11:project: glance
12
13:problem: A new image using the HTTP store may have its ``locations``
14 initialised using the ``add`` or ``replace`` operation in an HTTP
15 PATCH request, but there is currently no way to provide values for
16 accompanying checksum and multihash values.
17
18:solution: Allow embedding of values for ``checksum``, ``os_hash_algo``
19 and ``os_hash_value`` in a new write-only JSON object named
20 ``validation_data``, along with the ``url`` and ``metadata`` for an
21 image location. These values will be used to populate the
22 corresponding image properties.
23
24 New values for any of these items will only be accepted if the image
25 status is ``queued`` and the corresponding image property is not
26 already populated. To allow idempotency, this object may be included
27 when adding or replacing locations for an image which is in
28 ``active`` status or/and already has the corresponding properties
29 populated, but the supplied values must exactly match the existing
30 ones.
31
32 The object may be included in one or more of the items in
33 a ``locations`` list, but values must be consistent across all
34 instances.
35
36 Although the ``validation_data`` object will be optional,
37 if it is present, the ``os_hash_algo`` and ``os_hash_value`` items
38 will be required, to force adoption of multihash. Since multihash
39 will be the default mechanism for clients in the Stein release,
40 ``checksum`` will be optional, but included to accommodate legacy
41 consumers that have not yet implemented multihash. The consumer
42 is expected know to to populate ``checksum`` only if their
43 deployment requires it.
44
45 ``os_hash_algo`` must match the Glance server's
46 ``DEFAULT.hashing_algorithm`` configuration option. Whilst it seems
47 redundant to require an input with only one acceptable value, this
48 is required to ensure that the user knows which algorithm is
49 required. The ``checksum`` and ``os_hash_value`` cannot be verified
50 (since the Glance server does not have a copy of the image data),
51 but they will be validated as hexadecimal values of the correct size
52 for the respective algorithms.
53
54 Any violations of the above rules will result in a ``HTTPConflict``
55 exception (HTTP status 409).
56
57 The following will be added to the properties for ``locations``
58 items in the ``images`` schema::
59
60 'validation_data': {
61 'description': _(
62 'Values to be used to populate the corresponding '
63 'image properties. If the image status is not '
64 '"queued" or/and the image properties are already '
65 'populated, any supplied values must exactly match '
66 'existing ones.'
67 ),
68 'type': 'object',
69 'writeOnly': True,
70 'properties': {
71 'checksum': {
72 'type': 'string',
73 'minLength': 32,
74 'maxLength': 32,
75 },
76 'os_hash_algo': {
77 'type': 'string',
78 'maxLength': 64,
79 },
80 'os_hash_value': {
81 'type': 'string',
82 'maxLength': 128,
83 },
84 },
85 'required': [
86 'os_hash_algo',
87 'os_hash_value',
88 ],
89 },
90
91 Support will also be added to the ``add_location()`` method and the
92 ``location-add`` shell command in python-glanceclient.
93
94:alternatives: Implement an import method to directly register images for use
95 with the HTTP store (without requiring use of HTTP PATCH).
96
97:timeline: Include in Stein release. Need approval ASAP, so I can proceed with
98 a private backport for my Rocky upgrades (v1 API removed).
99
100:link: https://review.openstack.org/597368
101
102:assignee: imacdonn
diff --git a/specs/stein/approved/index.rst b/specs/stein/approved/index.rst
index b746326..e55637a 100644
--- a/specs/stein/approved/index.rst
+++ b/specs/stein/approved/index.rst
@@ -6,6 +6,14 @@ Stein Approved Specifications
6 :glob: 6 :glob:
7 :maxdepth: 1 7 :maxdepth: 1
8 8
9Stein approved specs for Glance:
10
11.. toctree::
12 :glob:
13 :maxdepth: 1
14
15 glance/*
16
9Stein approved specs for python-glanceclient: 17Stein approved specs for python-glanceclient:
10 18
11.. toctree:: 19.. toctree::