openstack/glance
Code Issues Proposed changes

Add warning and note on image schema customization docs

Browse Source 
An operator can modify /etc/schema-image.json to include arbitrary
properties (which was that file's original purpose) and assign them JSON
types other than 'string'. The type is enforced by image create/update
but an end-user making a call that sets a value on one of these gets a
500.

This patch add the following recommendations to the documentation:
- Value of `type` of each property in the JSON scheme must be `string`
- Do not delete items from the default schema-image.json file
- If operator's need is more complicated, suggest them using metadefs

Co-authored-by: Brian Rosmaita <rosmaita.fossdev@gmail.com>

Change-Id: I879f4440a14b1e8420e230de84bfba5e0419a4d4
Closes-bug: #1856578
This commit is contained in:
khashf 2020-04-06 17:59:13 -07:00
parent fa18f745df
commit bd16ab256e
1 changed files with 24 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/source/user/common-image-properties.rst
View File

@ -23,7 +23,7 @@ that may prove useful to consumers of your image.
This document explains the names of these properties and the expected values.
The common image properties are also described in a JSON schema, found in
/etc/glance/schema-image.json in the Glance source code.
``/etc/glance/schema-image.json`` in the Glance source code.
kernel_id
The ID of image stored in Glance that should be used as the kernel when
@ -61,3 +61,26 @@ cinder_encryption_key_deletion_policy
States the condition under which the Image Service will delete the object
associated with the 'cinder_encryption_key_id' image property. If this
property is missing, the Image Service will take no action.
This file is the default schema. An operator can modify
``/etc/schema-image.json`` to include arbitrary properties.
.. warning::
* Do not delete existing properties from this default schema because this
will affect interoperability
* The ``type`` of each property in this JSON schema, specified by the
``type`` key, must have value ``string`` even if the property you are
adding is not a string in common sense. For example, if you want to add a
property named ``is_removable`` and want its type to be ``boolean``.
However, you must give the ``type`` key the value ``string``. Otherwise,
when an end-user makes a call that sets a value on one of these, they
will gets a 500. This is because everything in the image_properties table
must be a string in the database. The API, however, won't accept a string
value when the schema says it is boolean or some other non-string JSON
data type
.. note::
If your need is more complicated, we recommend using metadefs_ instead of
modifying this image schema
.. _metadefs: https://docs.openstack.org/api-ref/image/v2/metadefs-index.html