spec-lite: Embed validation data in locations

Change-Id: I61b478dbcd7383b267a910e7a95346fabee90c27
This commit is contained in:
imacdonn 2018-11-07 17:45:45 +00:00
parent b75826eeba
commit 49d3191cde
2 changed files with 110 additions and 0 deletions

View File

@ -0,0 +1,102 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================================
Spec Lite: Embed validation data with image locations
=====================================================
:project: glance
:problem: A new image using the HTTP store may have its ``locations``
initialised using the ``add`` or ``replace`` operation in an HTTP
PATCH request, but there is currently no way to provide values for
accompanying checksum and multihash values.
:solution: Allow embedding of values for ``checksum``, ``os_hash_algo``
and ``os_hash_value`` in a new write-only JSON object named
``validation_data``, along with the ``url`` and ``metadata`` for an
image location. These values will be used to populate the
corresponding image properties.
New values for any of these items will only be accepted if the image
status is ``queued`` and the corresponding image property is not
already populated. To allow idempotency, this object may be included
when adding or replacing locations for an image which is in
``active`` status or/and already has the corresponding properties
populated, but the supplied values must exactly match the existing
ones.
The object may be included in one or more of the items in
a ``locations`` list, but values must be consistent across all
instances.
Although the ``validation_data`` object will be optional,
if it is present, the ``os_hash_algo`` and ``os_hash_value`` items
will be required, to force adoption of multihash. Since multihash
will be the default mechanism for clients in the Stein release,
``checksum`` will be optional, but included to accommodate legacy
consumers that have not yet implemented multihash. The consumer
is expected know to to populate ``checksum`` only if their
deployment requires it.
``os_hash_algo`` must match the Glance server's
``DEFAULT.hashing_algorithm`` configuration option. Whilst it seems
redundant to require an input with only one acceptable value, this
is required to ensure that the user knows which algorithm is
required. The ``checksum`` and ``os_hash_value`` cannot be verified
(since the Glance server does not have a copy of the image data),
but they will be validated as hexadecimal values of the correct size
for the respective algorithms.
Any violations of the above rules will result in a ``HTTPConflict``
exception (HTTP status 409).
The following will be added to the properties for ``locations``
items in the ``images`` schema::
'validation_data': {
'description': _(
'Values to be used to populate the corresponding '
'image properties. If the image status is not '
'"queued" or/and the image properties are already '
'populated, any supplied values must exactly match '
'existing ones.'
),
'type': 'object',
'writeOnly': True,
'properties': {
'checksum': {
'type': 'string',
'minLength': 32,
'maxLength': 32,
},
'os_hash_algo': {
'type': 'string',
'maxLength': 64,
},
'os_hash_value': {
'type': 'string',
'maxLength': 128,
},
},
'required': [
'os_hash_algo',
'os_hash_value',
],
},
Support will also be added to the ``add_location()`` method and the
``location-add`` shell command in python-glanceclient.
:alternatives: Implement an import method to directly register images for use
with the HTTP store (without requiring use of HTTP PATCH).
:timeline: Include in Stein release. Need approval ASAP, so I can proceed with
a private backport for my Rocky upgrades (v1 API removed).
:link: https://review.openstack.org/597368
:assignee: imacdonn

View File

@ -6,6 +6,14 @@ Stein Approved Specifications
:glob:
:maxdepth: 1
Stein approved specs for Glance:
.. toctree::
:glob:
:maxdepth: 1
glance/*
Stein approved specs for python-glanceclient:
.. toctree::