Repropose new location APIs spec for 2023.2 (Bobcat)
This commit re-proposes the new location APIs spec based on the discussion in the 2023.2 (Bobcat) PTG[1]. [1] https://wiki.openstack.org/wiki/CinderBobcatPTGSummary#Glance-Cinder-Nova_cross_project Change-Id: I7fbd73beebdf103e9e1f7d6501a756ba7da20949
This commit is contained in:
Rajat Dhasmana
parent
6beec09777
commit
b7f6ba60ce
@ -13,11 +13,3 @@
|
||||
:maxdepth: 1
|
||||
|
||||
glance_store/*
|
||||
|
||||
2023.1 approved specs for glance:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
glance/*
|
||||
|
||||
@ -51,7 +51,8 @@ There will be 3 phases in which the work will be done as follows:
|
||||
|
||||
3. Remove ``show_multiple_locations`` config option when it is no longer
|
||||
required by other services (cinder/nova) to perform operations on
|
||||
locations. This will mostly be done in B or C cycle.
|
||||
locations. This will mostly be done 1 or 2 cycles after the consumers
|
||||
have adapted the new location APIs to handle the upgrade cases.
|
||||
|
||||
The config option ``show_multiple_locations`` has been deprecated since Newton
|
||||
but we will keep the config option until the consumers of glance locations
|
||||
@ -137,7 +138,7 @@ Alternatives
|
||||
images with the ``admin_or_service`` role. This will require the consumers
|
||||
to provide admin credentials during add or get of an image to get the
|
||||
location.
|
||||
This was the original proposal but due to the disagreement here [4]_, we
|
||||
This was the original proposal but due to the disagreement here [3]_, we
|
||||
changed the design to the current proposal.
|
||||
|
||||
* Another alternative is to add this functionality in the import workflow.
|
||||
@ -171,12 +172,30 @@ We are going to add 2 new location APIs:
|
||||
This will add a new location to an existing image.
|
||||
The request body will contain the location URL and an optional parameter,
|
||||
``do_secure_hash``, which will tell the API if we want to do the checksum or
|
||||
not. The ``do_secure_hash`` flag is required by the HTTP Store to make it
|
||||
compatible with new location add API.
|
||||
We will allow ``validation data`` [3]_ to be passed in case of HTTP store
|
||||
else glance will calculate the image hash. If both ``do_secure_hash`` and
|
||||
``validation data`` are passed, then we will compare them and fail the
|
||||
location add operation if they don't match.
|
||||
not. The consumer APIs like nova, cinder, HTTP store etc, should pass the
|
||||
``do_secure_hash`` flag since glance does not calculate the checksum
|
||||
automatically in these cases.
|
||||
We will also allow passing ``validation data`` [4]_ which will behave in
|
||||
the following manner with the ``do_secure_hash`` parameter:
|
||||
|
||||
* do_secure_hash = True, validation_data = {}
|
||||
Calculate the checksum and hash by reading the image.
|
||||
* do_secure_hash = False, validation_data = <checksum, hash>
|
||||
Validate the checksum and hash data provided and add it to the image.
|
||||
We will not be calculating the image checksum and hash in this case
|
||||
so it is the responsibility of the consumer of location ADD API to
|
||||
provide the correct values in the validation_data parameter.
|
||||
* do_secure_hash = True, validation_data = <checksum, hash>
|
||||
Calculate the checksum and hash by reading the image and compare it
|
||||
with the validation_data provided. we will fail the location add operation
|
||||
if the values don't match.
|
||||
|
||||
Unlike old location API, we will not provide support of adding a location
|
||||
on a particular index. If we want to get the benefit of indexes, we can
|
||||
use the old location APIs or set location strategy as store_type [5]_.
|
||||
A new location strategy ``store_identifier`` is proposed [6]_ and should be
|
||||
useful to download image from a specific store in case multiple stores are
|
||||
configured.
|
||||
|
||||
POST /v2/images/{image_id}/locations
|
||||
|
||||
@ -185,8 +204,13 @@ We are going to add 2 new location APIs:
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"url": "cinder://lvmdriver-1/0f031ed1-5872-43d5-a638-4b0d07c10ab5",
|
||||
"url": "cinder://lvmdriver-1/1a304872-b0ca-4992-b2c2-6874c6d5d5f9",
|
||||
"do_secure_hash": false,
|
||||
"validation_data": {
|
||||
"checksum": "b874c39491a2377b8490f5f1e89761a4",
|
||||
"os_hash_algo": "sha512",
|
||||
"os_hash_value": "6b813aa46bb90b4da216a4d19376593fa3f4fc7e617f03a92b7fe11e9a3981cbe8f0959dbebe36225e5f53dc4492341a4863cac4ed1ee0909f3fc78ef9c3e869",
|
||||
}
|
||||
}
|
||||
|
||||
* JSON response body
|
||||
@ -196,13 +220,35 @@ We are going to add 2 new location APIs:
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"url": "cinder://lvmdriver-1/0f031ed1-5872-43d5-a638-4b0d07c10ab5",
|
||||
"metadata": "{'store': 'lvmdriver-1',
|
||||
'do_secure_hash': false}"
|
||||
"checksum": "b874c39491a2377b8490f5f1e89761a4",
|
||||
"container_format": "bare",
|
||||
"created_at": "2023-05-03T21:30:21Z",
|
||||
"disk_format": "qcow2",
|
||||
"file": "/v2/images/57124e08-3691-4713-82cc-213dc5c7e242/file",
|
||||
"id": "57124e08-3691-4713-82cc-213dc5c7e242",
|
||||
"min_disk": 0,
|
||||
"min_ram": 0,
|
||||
"name": "test-image",
|
||||
"owner": "d6634f35c00f409883ecb10361b556c3",
|
||||
"properties": {
|
||||
"os_hidden": false,
|
||||
"os_hash_algo": "sha512",
|
||||
"os_hash_value": "6b813aa46bb90b4da216a4d19376593fa3f4fc7e617f03a92b7fe11e9a3981cbe8f0959dbebe36225e5f53dc4492341a4863cac4ed1ee0909f3fc78ef9c3e869",
|
||||
"stores": "lvmdriver-1",
|
||||
},
|
||||
"protected": false,
|
||||
"schema": "/v2/schemas/image",
|
||||
"size": 16300544,
|
||||
"status": "active",
|
||||
"tags": [],
|
||||
"updated_at": "2023-05-03T21:32:35Z",
|
||||
"virtual_size": 117440512,
|
||||
"visibility": "shared"
|
||||
}
|
||||
|
||||
- Error - 409 (Location already exists), 403 (Forbidden for users that are
|
||||
not owner), 400 (BadRequest if image is not in QUEUED state)
|
||||
- Error - 409 (Location already exists or if image is not in QUEUED
|
||||
state), 403 (Forbidden for users that are not owner), 400 (BadRequest
|
||||
if hash validation fails)
|
||||
|
||||
* Get Location(s)
|
||||
|
||||
@ -230,12 +276,13 @@ We are going to add 2 new location APIs:
|
||||
|
||||
The transition of image state during the image create operation will be as
|
||||
follows.
|
||||
Image upload (PUT), image stage (PUT) and location add (PATCH), will transition
|
||||
Image upload (PUT), image stage (PUT) and location add (POST), will transition
|
||||
the image from queued to the next state that could be either of the following:
|
||||
|
||||
1. ``saving``
|
||||
2. ``uploading``
|
||||
3. ``active``
|
||||
3. ``importing``
|
||||
4. ``active``
|
||||
|
||||
Below are the valid transitions for image from queued state.
|
||||
|
||||
@ -274,11 +321,11 @@ None
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
Since the new APIs are for service to service interaction, there is not much
|
||||
value to expose them via glanceclient CLI. However, we will add methods to
|
||||
the glanceclient (that will call the new location APIs) that will be used by
|
||||
other consumer services like cinder and nova but those methods won't be
|
||||
exposed via the shell to end users.
|
||||
Since the new APIs are mainly for service to service interaction (except the
|
||||
HTTP store case), we will only expose the location add API via CLI. However,
|
||||
we will need to add methods for all APIs in openstacksdk (that will call
|
||||
the new location APIs) that will be used by other consumer services like
|
||||
cinder and nova.
|
||||
End users can still use the existing commands (that internally calls the
|
||||
image-update API) to perform operations on locations:
|
||||
|
||||
@ -287,16 +334,31 @@ image-update API) to perform operations on locations:
|
||||
image.
|
||||
* ``glance location-update:`` Update metadata of an image's location.
|
||||
|
||||
We will also add a new command that will allow end users to update the
|
||||
``location`` and ``metadata`` for HTTP store case.
|
||||
We will also add a new command to glanceclient and OSC that will allow end
|
||||
users to add the location ``url`` and ``metadata`` for HTTP store case.
|
||||
|
||||
* ``glance direct-location --location <location> --metadata
|
||||
* ``glance add-location-properties --url <location> --metadata
|
||||
<key1=value1, key2=value2 ...>``
|
||||
* ``openstack add-location-properties --url <location> --metadata
|
||||
<key1=value1, key2=value2 ...>``
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
None
|
||||
In the old location API, the consumers (nova, cinder) registered
|
||||
the location in glance and the checksum, hash etc values weren't
|
||||
calculated. After the consumers adapt to the new location API,
|
||||
providing the ``do_secure_hash`` parameter in the new location
|
||||
ADD API, glance will read the image and calculate the hash which
|
||||
will take significantly more time compared to the same operation
|
||||
being performed in the old location ADD API.
|
||||
The performance downside will result in creation of more secure
|
||||
images and the impact needs to be conveyed to the operators/end users
|
||||
with documentation and releasenotes. Also if we plan to make the
|
||||
value of ``do_secure_hash`` configurable on the consumer side,
|
||||
we will add suitable help text to convey the performance and security
|
||||
impact of enabling/disabling this option.
|
||||
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
@ -308,6 +370,18 @@ Developer impact
|
||||
|
||||
Consumers like Cinder, Nova and HTTP store need to modify code to call the
|
||||
new client functions to access the API.
|
||||
Some of the key things to consider while implementing consumer side changes
|
||||
are:
|
||||
|
||||
* We will use SDK to make the API calls. The changes to call new
|
||||
location APIs will be in SDK and also in OSC/glanceclient for location
|
||||
ADD in case of HTTP store.
|
||||
* Keep backward compatibility with old behavior. Glance should support
|
||||
the legacy behavior as well as the new way to add/get locations. This is
|
||||
useful in upgrade cases where one compute node is running 2023.1 (Antelope)
|
||||
code and the other compute node has been upgraded to 2024.1 (CC) release.
|
||||
* Testing should be done to see if the existing functionalities supported
|
||||
with the legacy location APIs works as expected with the new APIs.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
@ -316,7 +390,7 @@ Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
abhishekk
|
||||
pdeore
|
||||
|
||||
Other contributors:
|
||||
whoami-rajat
|
||||
@ -329,6 +403,8 @@ Work Items
|
||||
* Modify consumers like cinder and nova and http store to use the new location
|
||||
APIs.
|
||||
|
||||
* Add SDK support to call the new APIs.
|
||||
|
||||
* Add a releasenote mentioning that we will remove the config option
|
||||
``show_multiple_locations`` when the consumers (nova/cinder/http store)
|
||||
shift to using new location APIs.
|
||||
@ -360,9 +436,13 @@ References
|
||||
|
||||
.. [2] https://wiki.openstack.org/wiki/OSSN/OSSN-0090
|
||||
|
||||
.. [3] https://specs.openstack.org/openstack/glance-specs/specs/stein/implemented/glance/spec-lite-locations-with-validation-data.html
|
||||
.. [3] https://review.opendev.org/c/openstack/glance-specs/+/840882/2..15/specs/zed/approved/glance/new-location-info-apis.rst#b199
|
||||
|
||||
.. [4] https://review.opendev.org/c/openstack/glance-specs/+/840882/2..15/specs/zed/approved/glance/new-location-info-apis.rst#b199
|
||||
.. [4] https://specs.openstack.org/openstack/glance-specs/specs/stein/implemented/glance/spec-lite-locations-with-validation-data.html
|
||||
|
||||
.. [5] https://docs.openstack.org/glance/latest/contributor/api/glance.common.location_strategy.store_type.html
|
||||
|
||||
.. [6] https://review.opendev.org/c/openstack/glance-specs/+/881951
|
||||
|
||||
.. _Delete Image From Store: https://docs.openstack.org/api-ref/image/v2/index.html?expanded=delete-image-from-store-detail#delete-image-from-store
|
||||
|
||||
@ -6,8 +6,10 @@
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
TODO: fill this in once a new approved spec is added.
|
||||
|
||||
|
||||
2023.2 approved specs for glance:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
glance/*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user