76aeab31f0
Add text to the api-ref to document the changes introduced by "Implement and Enable Community Images", whose change identifier is I94bc7708b291ce37319539e27b3e88c9a17e1a9f. Change-Id: Ib18c6ac226267ec15b399b71dbfefed33a1dbffd
382 lines
9.7 KiB
ReStructuredText
382 lines
9.7 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
.. _image-sharing:
|
|
|
|
Sharing
|
|
*******
|
|
|
|
Images may be shared among projects by creating *members* on the image. Image
|
|
members have read-only privileges on the image. The following calls allow you
|
|
to create, list, update, and delete image members.
|
|
|
|
.. note::
|
|
|
|
An image member is an identifier for a consumer with whom the image is
|
|
shared. In most OpenStack clouds, where the value of the ``owner`` property
|
|
of an image is a project ID, the appropriate identifier to use for the
|
|
``member_id`` is the consumer's project ID (also known as the "tenant ID").
|
|
In these clouds, image sharing is project-to-project, and all the individual
|
|
users in the consuming project have access to the image.
|
|
|
|
* Some deployments may choose instead to have the identifier of the user who
|
|
created the image as the value of the ``owner`` property. In such clouds,
|
|
the appropriate identifier to use for the ``member_id`` is the user ID of
|
|
the person with whom you want to share the image. In these clouds, image
|
|
sharing is user-to-user.
|
|
|
|
* Note that you, as an image owner, do not have a choice about what value to
|
|
use for the ``member_id``. If, like most OpenStack clouds, your cloud
|
|
uses the tenant ID for the image ``owner``, sharing will not work if you
|
|
use a user ID as the ``member_id`` of an image (and vice-versa).
|
|
|
|
* Please consult your cloud's local documentation for details.
|
|
|
|
When an image is shared, the member is given immediate access to the image.
|
|
In order to prevent spamming other users' image lists, a shared image does not
|
|
appear in a member's image list until the member "accepts" the image.
|
|
|
|
Only the image owner may create members. Only an image member may modify his
|
|
or her member status.
|
|
|
|
.. TODO(rosmaita): update the following reference when the "narrative" API
|
|
docs have a final resting place
|
|
|
|
For a conceptual overview of image sharing, including a suggested workflow,
|
|
please consult `Image API v2 Sharing`_.
|
|
|
|
.. _Image API v2 Sharing:
|
|
http://specs.openstack.org/openstack/glance-specs/specs/api/v2/sharing-image-api-v2.html
|
|
|
|
.. note::
|
|
|
|
If you don't want to maintain a sharing relationship with particular
|
|
image consumers, but instead want to make an image available to *all*
|
|
users, you may update your image's ``visibility`` property to
|
|
``community``.
|
|
|
|
* In some clouds, the ability to "communitize" an image may be prohibited
|
|
or restricted to trusted users. Please consult your cloud's local
|
|
documentation for details.
|
|
|
|
Create image member
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/images/{image_id}/members
|
|
|
|
Adds a tenant ID as an image member.
|
|
*(Since Image API v2.1)*
|
|
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
- The image must have a ``visibility`` value of ``shared``.
|
|
|
|
- You must be the owner of the image.
|
|
|
|
Synchronous Postconditions
|
|
|
|
- With correct permissions, you can see the member status of the
|
|
image member as ``pending`` through API calls.
|
|
|
|
Troubleshooting
|
|
|
|
- Even if you have correct permissions, if the ``visibility``
|
|
attribute is not set to ``shared``, the request returns the HTTP
|
|
``403`` response code. Ensure that you meet the preconditions and
|
|
run the request again. If the request fails again, review your
|
|
API request.
|
|
|
|
- If the member is already a member for the image, the service
|
|
returns the ``Conflict (409)`` response code. If you meant to
|
|
specify a different member, run the request again.
|
|
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 403, 404, 409, 413
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
- member: member_id
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/image-member-create-request.json
|
|
:language: json
|
|
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- created_at: created_at
|
|
- image_id: image_id-in-body
|
|
- member_id: member_id
|
|
- schema: schema-member
|
|
- status: member_status
|
|
- updated_at: updated_at
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-member-create-response.json
|
|
:language: json
|
|
|
|
|
|
Show image member details
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/images/{image_id}/members/{member_id}
|
|
|
|
Shows image member details.
|
|
*(Since Image API v2.1)*
|
|
|
|
Response body is a single image member entity.
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
- The image must have a ``visibility`` value of ``shared``.
|
|
|
|
- You must be the owner or the member of the image who's referenced in the
|
|
call.
|
|
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
- member_id: member_id-in-path
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- created_at: created_at
|
|
- image_id: image_id-in-body
|
|
- member_id: member_id
|
|
- schema: schema-member
|
|
- status: member_status
|
|
- updated_at: updated_at
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-member-details-response.json
|
|
:language: json
|
|
|
|
|
|
List image members
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/images/{image_id}/members
|
|
|
|
Lists the tenants that share this image.
|
|
*(Since Image API v2.1)*
|
|
|
|
If the image owner makes this call, the complete member list is
|
|
returned.
|
|
|
|
If a user who is an image member makes this call, the member list
|
|
contains only information for that user.
|
|
|
|
If a user who is not an image member makes this call, the call
|
|
returns the HTTP ``404`` response code.
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
- The image must have a ``visibility`` value of ``shared``.
|
|
|
|
- You must be the owner or a member of the image.
|
|
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 403, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- members: members
|
|
- schema: schema-members
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-members-list-response.json
|
|
:language: json
|
|
|
|
|
|
Update image member
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: PUT /v2/images/{image_id}/members/{member_id}
|
|
|
|
Sets the status for an image member.
|
|
*(Since Image API v2.1)*
|
|
|
|
This call allows an image member to change his or her *member status*.
|
|
|
|
When an image is shared with you, you have immediate access to the image. What
|
|
updating your member status on the image does for you is that it affects
|
|
whether the image will appear in your image list response.
|
|
|
|
- When an image is shared with you, your member_status is ``pending``. You
|
|
won't see the image unless you go looking for it, either by making a show
|
|
image detail request using the image's ID, or by making an image list call
|
|
specifically looking for a shared image in member status ``pending``. This
|
|
way, other users cannot "spam" your image list with images you may not want
|
|
to see.
|
|
|
|
- If you want to see a particular shared image in your image list, then you
|
|
must use this call to change your member status on the image to ``accepted``.
|
|
|
|
- The image owner can see what your member status is on an image, but the owner
|
|
*cannot* change the status. Only you (or an administrator) can do that.
|
|
|
|
- There are three member status values: ``pending``, ``accepted``, and
|
|
``rejected``. The ``pending`` and ``rejected`` statuses are functionally
|
|
identical. The difference is that ``pending`` indicates to the owner that
|
|
you haven't updated the image, so perhaps you aren't aware that it's been
|
|
shared with you. The ``rejected`` status indicates that you are aware that
|
|
the image exists and you specifically decided that you don't want to see it
|
|
in your image list response.
|
|
|
|
For a more detailed discussion of image sharing, please consult `Image API v2
|
|
Sharing`_.
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
- The image must have a ``visibility`` value of ``shared``.
|
|
|
|
- You must be the member of the image referenced in the call.
|
|
|
|
Synchronous Postconditions
|
|
|
|
- If you update the member status to ``accepted`` and have the
|
|
correct permissions, you see the image in list images responses.
|
|
|
|
- With correct permissions, you can make API calls to see the
|
|
updated member status of the image.
|
|
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 404, 403
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
- member_id: member_id-in-path
|
|
- status: member_status
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/image-member-update-request.json
|
|
:language: json
|
|
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- created_at: created_at
|
|
- image_id: image_id-in-body
|
|
- member_id: member_id
|
|
- schema: schema-member
|
|
- status: member_status
|
|
- updated_at: updated_at
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-member-update-response.json
|
|
:language: json
|
|
|
|
|
|
Delete image member
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: DELETE /v2/images/{image_id}/members/{member_id}
|
|
|
|
Deletes a tenant ID from the member list of an image.
|
|
*(Since Image API v2.1)*
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
- The image must have a ``visibility`` value of ``shared``.
|
|
|
|
- You must be the owner of the image.
|
|
|
|
Synchronous Postconditions
|
|
|
|
- The API removes the member from the image members.
|
|
|
|
Troubleshooting
|
|
|
|
- Even if you have correct permissions, if you are not the owner of
|
|
the image or you specify an incorrect image ID or member ID, the
|
|
call returns the HTTP ``403`` or ``404`` response code. Ensure
|
|
that you meet the preconditions and run the request again. If the
|
|
request fails again, review your API request URI.
|
|
|
|
Normal response codes: 204
|
|
|
|
Error response codes: 400, 401, 403, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
- member_id: member_id-in-path
|