.. -*- 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