fbdd3381ca
Add documentation for the changes introduced by "Implement and Enable Community Images", I94bc7708b291ce37319539e27b3e88c9a17e1a9f. Also added some text to clarify the implications of the owner_is_tenant configuration option when identifying an image producer or consumer. Added an introductory section about the kinds of sharing available. Change-Id: I58f39d4729e783a86999b1fe18debd97a3ebe544
9.1 KiB
Image Metadata API calls
The following calls allow you to create, modify, and delete image metadata records.
Create image
POST /v2/images
Request body must be JSON-encoded and conform to the
image JSON schema. For example:
{
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
"name": "Ubuntu 12.10",
"tags": ["ubuntu", "quantal"]
}Successful HTTP response is 201 Created with a Location header
containing the newly-created URI for the image. The response body shows
the created image entity. For example:
{
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
"name": "Ubuntu 12.10",
"status": "queued",
"visibility": "public",
"tags": ["ubuntu", "quantal"],
"created_at": "2012-08-11T17:15:52Z",
"updated_at": "2012-08-11T17:15:52Z",
"self": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
"file": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/file",
"schema": "/v2/schemas/image"
}Update an image
PATCH /v2/images/{image_id}
Request body must conform to the 'application/openstack-images-v2.1-json-patch' media type, documented in Appendix B. Using PATCH /v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd as an example:
[
{"op": "replace", "path": "/name", "value": "Fedora 17"},
{"op": "replace", "path": "/tags", "value": ["fedora", "beefy"]}
]The response body shows the updated image entity. For
example:
{
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
"name": "Fedora 17",
"status": "queued",
"visibility": "public",
"tags": ["fedora", "beefy"],
"created_at": "2012-08-11T17:15:52Z",
"updated_at": "2012-08-11T17:15:52Z",
"self": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
"file": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/file",
"schema": "/v2/schemas/image"
}The PATCH method can also be used to add or remove image properties. To add a custom user-defined property such as "login-user" to an image, use the following example request.
[
{"op": "add", "path": "/login-user", "value": "kvothe"}
]Similarly, to remove a property such as "login-user" from an image, use the following example request.
[
{"op": "remove", "path": "/login-user"}
]See Appendix B for more details about the 'application/openstack-images-v2.1-json-patch' media type.
Property protections
Version 2.2 of the Images API acknowledges the ability of a cloud provider to employ property protections. Thus, there may be image properties that may not be updated or deleted by non-admin users.
Add an image tag
PUT /v2/images/{image_id}/tags/{tag}
The tag you want to add should be encoded into the request URI. For example, to tag image e7db3b45-8db7-47ad-8109-3fb55c2c24fd with 'miracle', you would PUT /v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/tags/miracle. The request body is ignored.
An image tag can be up to 255 characters in length. See the 'image' json-schema to determine which characters are allowed.
An image can only be tagged once with a specific string. Multiple attempts to tag an image with the same string will result in a single instance of that string being added to the image's tags list.
An HTTP status of 204 is returned.
Delete an image tag
DELETE /v2/images/{image_id}/tags/{tag}
The tag you want to delete should be encoded into the request URI. For example, to remove the tag 'miracle' from image e7db3b45-8db7-47ad-8109-3fb55c2c24fd, you would DELETE /v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/tags/miracle. The request body is ignored.
An HTTP status of 204 is returned. Subsequent attempts to delete the tag will result in a 404.
List images
GET /v2/images
Request body ignored.
Response body will be a list of images available to the client. For example:
{
"images": [
{
"id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
"name": "cirros-0.3.0-x86_64-uec-ramdisk",
"status": "active",
"visibility": "public",
"size": 2254249,
"checksum": "2cec138d7dae2aa59038ef8c9aec2390",
"tags": ["ping", "pong"],
"created_at": "2012-08-10T19:23:50Z",
"updated_at": "2012-08-10T19:23:50Z",
"self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
"file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
"schema": "/v2/schemas/image"
},
{
"id": "0d5bcbc7-b066-4217-83f4-7111a60a399a",
"name": "cirros-0.3.0-x86_64-uec",
"status": "active",
"visibility": "public",
"size": 25165824,
"checksum": "2f81976cae15c16ef0010c51e3a6c163",
"tags": [],
"created_at": "2012-08-10T19:23:50Z",
"updated_at": "2012-08-10T19:23:50Z",
"self": "/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a",
"file": "/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a/file",
"schema": "/v2/schemas/image"
},
{
"id": "e6421c88-b1ed-4407-8824-b57298249091",
"name": "cirros-0.3.0-x86_64-uec-kernel",
"status": "active",
"visibility": "public",
"size": 4731440,
"checksum": "cfb203e7267a28e435dbcb05af5910a9",
"tags": [],
"created_at": "2012-08-10T19:23:49Z",
"updated_at": "2012-08-10T19:23:49Z",
"self": "/v2/images/e6421c88-b1ed-4407-8824-b57298249091",
"file": "/v2/images/e6421c88-b1ed-4407-8824-b57298249091/file",
"schema": "/v2/schemas/image"
}
],
"first": "/v2/images?limit=3",
"next": "/v2/images?limit=3&marker=e6421c88-b1ed-4407-8824-b57298249091",
"schema": "/v2/schemas/images"
}Get images schema
GET /v2/schemas/images
Request body ignored.
The response body contains a json-schema document that shows an
images entity (a container of image entities).
For example:
{
"name": "images",
"properties": {
"images": {
"items": {
"type": "array",
"name": "image",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"visibility": {"enum": ["public", "private"]},
"status": {"type": "string"},
"protected": {"type": "boolean"},
"tags": {
"type": "array",
"items": {"type": "string"}
},
"checksum": {"type": "string"},
"size": {"type": "integer"},
"created_at": {"type": "string"},
"updated_at": {"type": "string"},
"file": {"type": "string"},
"self": {"type": "string"},
"schema": {"type": "string"}
},
"additionalProperties": {"type": "string"},
"links": [
{"href": "{self}", "rel": "self"},
{"href": "{file}", "rel": "enclosure"},
{"href": "{schema}", "rel": "describedby"}
]
}
},
"schema": {"type": "string"},
"next": {"type": "string"},
"first": {"type": "string"}
},
"links": [
{"href": "{first}", "rel": "first"},
{"href": "{next}", "rel": "next"},
{"href": "{schema}", "rel": "describedby"}
]
}Get image schema
GET /v2/schemas/image
Request body ignored.
The response body contains a json-schema document that shows an
image. For example:
{
"name": "image",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"visibility": {"enum": ["public", "private"]},
"status": {"type": "string"},
"protected": {"type": "boolean"},
"tags": {
"type": "array",
"items": {"type": "string"}
},
"checksum": {"type": "string"},
"size": {"type": "integer"},
"created_at": {"type": "string"},
"updated_at": {"type": "string"},
"file": {"type": "string"},
"self": {"type": "string"},
"schema": {"type": "string"}
},
"additionalProperties": {"type": "string"},
"links": [
{"href": "{self}", "rel": "self"},
{"href": "{file}", "rel": "enclosure"},
{"href": "{schema}", "rel": "describedby"}
]
}