From df0d0aad86b54a3554c5bef602d1049660223065 Mon Sep 17 00:00:00 2001 From: Abhishek Kekane Date: Wed, 6 Aug 2025 12:09:51 +0530 Subject: [PATCH] Update API reference to mention x-openstack-image-size header Add API reference documentation for the x-openstack-image-size header in PUT /v2/images/{image_id}/file and PUT /v2/images/{image_id}/stage endpoints. Assisted-By: Cursor (claude-3.5-sonnet) Change-Id: Ie733373c093bed4866719f163a75abaff4abe6a2 Signed-off-by: Abhishek Kekane --- api-ref/source/v2/images-data.inc | 8 ++++++++ api-ref/source/v2/images-import.inc | 8 ++++++++ api-ref/source/v2/images-parameters.yaml | 10 ++++++++++ ...tack-image-size-header-9199a5544274002a.yaml | 17 +++++++++++++++++ 4 files changed, 43 insertions(+) create mode 100644 releasenotes/notes/add-x-openstack-image-size-header-9199a5544274002a.yaml diff --git a/api-ref/source/v2/images-data.inc b/api-ref/source/v2/images-data.inc index 9426cf2ceb..9b03fd648e 100644 --- a/api-ref/source/v2/images-data.inc +++ b/api-ref/source/v2/images-data.inc @@ -31,6 +31,12 @@ header. If the store identifier specified is not recognized, a 400 (Bad Request) response is returned. When the header is not present, the image data is placed into the default backing store. +An optional ``x-openstack-image-size`` header may be added to the request. +When present, the server will validate that the uploaded data size matches +this value. If the actual size does not match the expected size, a 400 +(Bad Request) response is returned. When not present, the server will +calculate the image size based on the actual request body size. + * Store identifiers are site-specific. Use the :ref:`Store Discovery ` call to determine what stores are available in a particular cloud. @@ -49,6 +55,7 @@ Example call: curl -i -X PUT -H "X-Auth-Token: $token" \ -H "X-Image-Meta-Store: {store_identifier}" \ -H "Content-Type: application/octet-stream" \ + -H "x-openstack-image-size: 5368709120" \ -d @/home/glance/ubuntu-12.10.qcow2 \ $image_url/v2/images/{image_id}/file @@ -98,6 +105,7 @@ Request - Content-type: Content-Type-data - X-Image-Meta-Store: store-header + - x-openstack-image-size: x-openstack-image-size - image_id: image_id-in-path diff --git a/api-ref/source/v2/images-import.inc b/api-ref/source/v2/images-import.inc index 4e4af87755..edeef7bc3a 100644 --- a/api-ref/source/v2/images-import.inc +++ b/api-ref/source/v2/images-import.inc @@ -118,12 +118,19 @@ the :ref:`Image Import ` call is made. Set the ``Content-Type`` request header to ``application/octet-stream``. +An optional ``x-openstack-image-size`` header may be added to the request. +When present, the server will validate that the uploaded data size matches +this value. If the actual size does not match the expected size, a 400 +(Bad Request) response is returned. When not present, the server will +calculate the image size based on the actual request body size. + Example call: :: curl -i -X PUT -H "X-Auth-Token: $token" \ -H "Content-Type: application/octet-stream" \ + -H "x-openstack-image-size: 5368709120" \ -d @/home/glance/my.to-import.qcow2 \ $image_url/v2/images/{image_id}/stage @@ -170,6 +177,7 @@ Request .. rest_parameters:: images-parameters.yaml - Content-type: Content-Type-data + - x-openstack-image-size: x-openstack-image-size - image_id: image_id-in-path diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml index 6d098a6e21..d212bc5620 100644 --- a/api-ref/source/v2/images-parameters.yaml +++ b/api-ref/source/v2/images-parameters.yaml @@ -97,6 +97,16 @@ stores-header: in: header required: false type: string +x-openstack-image-size: + description: | + The expected size of the image data in bytes. When present, the server + will validate that the uploaded data size matches this value. If the + actual size does not match the expected size, a 400 (Bad Request) + response is returned. When not present, the server will calculate the + image size based on the actual request body size. + in: header + required: false + type: string # variables in path image_id-in-path: diff --git a/releasenotes/notes/add-x-openstack-image-size-header-9199a5544274002a.yaml b/releasenotes/notes/add-x-openstack-image-size-header-9199a5544274002a.yaml new file mode 100644 index 0000000000..6fec69722e --- /dev/null +++ b/releasenotes/notes/add-x-openstack-image-size-header-9199a5544274002a.yaml @@ -0,0 +1,17 @@ +--- +features: + - | + Added support for the optional ``x-openstack-image-size`` header in image + upload endpoints. This header allows clients to specify the expected size + of image data in bytes when uploading images via the PUT + ``/v2/images/{image_id}/file`` and PUT ``/v2/images/{image_id}/stage`` + endpoints. + + When the header is present, the server validates that the uploaded data + size matches the specified value. If the actual size does not match the + expected size, a 400 (Bad Request) response is returned. When the header + is not present, the server calculates the image size based on the actual + request body size. + + This feature improves data integrity validation during image uploads and + helps prevent incomplete or corrupted uploads.