Difference between revisions of "API Special Interest Group/Current Design/Metadata"
(Added information about how Glance v1 and v2 API's image properties and tags work.) |
m (EdLeafe moved page API Working Group/Current Design/Metadata to API Special Interest Group/Current Design/Metadata: +The group changed its name and focus) |
(No difference)
|
Latest revision as of 15:40, 14 June 2018
Contents
Analysis
When a service has a metadata resource it typically takes the form of
{ "metadata": { "key1": "value1", "key2": "value2" } }
There doesn't seem to be a strong consensus about how the metadata is CRUDed.
The outliers are Orchestration's Software Configuration metadata which seems to describe a concept different from the other services notion of metadata and Object Storage's metadata which does everything with headers.
The Glance API (both v1 and v2) supports a rich metadata API, but it doesn't call these things "metadata", because it's not metadata technically. It's just data. Metadata is data *about* data -- e.g. the length of a string is metadata. The string is data. The length is data about the data. The Glance API calls these things "properties".
Current Design
Server
http://developer.openstack.org/api-ref-compute-v2.html#compute_server_metadata
{ "metadata": { "name": "test_server", "server_type": "test" } }
Method | Path | Description |
---|---|---|
GET | /v2/{tenant_id}/servers/{server_id}/metadata | Show server metadata |
PUT | /v2/{tenant_id}/servers/{server_id}/metadata | Create or replace server metadata items |
POST | /v2/{tenant_id}/servers/{server_id}/metadata | Update server metadata items |
GET | /v2/{tenant_id}/servers/{server_id}/metadata/{key} | Show server metadata item details |
PUT | /v2/{tenant_id}/servers/{server_id}/metadata/{key} | Create or update server metadata item |
DELETE | /v2/{tenant_id}/servers/{server_id}/metadata/{key} | Delete server metadata item |
Image Properties in Glance v1 API
- http://docs.openstack.org/api/openstack-image-service/1.0/content/requesting-detailed-metadata-on-a-specific-image.html
- http://docs.openstack.org/api/openstack-image-service/1.0/content/adding-image-metadata-in-http-headers.html
- http://docs.openstack.org/api/openstack-image-service/1.0/content/updating-an-image.html
HTTP/1.1 204 No Content x-image-meta-name Ubuntu 10.04 Plain 5GB x-image-meta-disk-format vhd x-image-meta-container-format ovf x-image-meta-size 5368709120 x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3 x-image-meta-created_at 2010-02-03 09:34:01 x-image-meta-updated_at 2010-02-03 09:34:01 x-image-meta-deleted_at x-image-meta-status available x-image-meta-is-public true x-image-meta-owner null x-image-meta-property-distro Ubuntu 10.04 LTS
You will note that all information about a disk image or snapshot is returned as HTTP headers. All header start with *x-image-meta*, because the data in the case of Glance is the disk image bytes. The term "metadata" that is used in other OpenStack APIs to refer to free-form key/value data about, say, a server, is called "properties" in Glance, and any HTTP header that begins with *x-image-meta-property* indicates one of these properties for the image. Above, the free-form property *distro* has a value of *Ubunut 10.04 LTS*.
Method | Path | Description |
---|---|---|
HEAD | /v1/images/{image_id} | Returns all image properties as HTTP headers |
PUT | /v1/images/{image_id} | Create or replace image properties as HTTP headers |
POST | /v1/images/{image_id} | Update image properties as HTTP headers |
Image Tags in Glance v2 API
- http://docs.openstack.org/api/openstack-image-service/2.0/content/get-an-image.html
- http://docs.openstack.org/api/openstack-image-service/2.0/content/create-image.html
- http://docs.openstack.org/api/openstack-image-service/2.0/content/update-an-image.html
- http://docs.openstack.org/api/openstack-image-service/2.0/content/add-an-image-tag.html
- http://docs.openstack.org/api/openstack-image-service/2.0/content/delete-an-image-tag.html
{ "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" }
The Glance v2 API has the concept of simple string tags, instead of key/value properties on an image. The tags are returned as a list of strings in the "tags" attribute of the top-most JSON document for an image in a call to the GET /v2/images/{image_id} API call.
Method | Path | Description |
---|---|---|
GET | /v2/images/{image_id} | Returns all image information and tags |
PATCH | /v2/images/{image_id} | Create or replace image tags |
PUT | /v2/images/{image_id}/tags/{tag} | Add tag to an image |
DELETE | /v2/images/{image_id}/tags/{tag} | Remove tag from an image |
Snapshot
http://developer.openstack.org/api-ref-blockstorage-v2.html#snapshots-v2
{ "metadata": { "key": "v2" } }
Method | Path | Description |
---|---|---|
GET | /v2/{tenant_id}/snapshots/{snapshot_id}/metadata | Show snapshot metadata |
PUT | /v2/{tenant_id}/snapshots/{snapshot_id}/metadata | Update snapshot metadata
One or more metadata key and value pairs to set or unset for the snapshot. |
Stack
http://developer.openstack.org/api-ref-orchestration-v1.html#stack-resources
{ "metadata": { "some_key": "some_value", "some_other_key": "some_other_value" } }
Method | Path | Description |
---|---|---|
GET | /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata | Show resource metadata |
Software Configuration
http://developer.openstack.org/api-ref-orchestration-v1.html#software-config
{ "metadata": [ { "inputs": [ { "default": null, "type": "String", "name": "foo", "value": "fooooo", "description": null }, { "default": null, "type": "String", "name": "bar", "value": "baaaaa", "description": null }, { "type": "String", "name": "deploy_server_id", "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", "description": "ID of the server being deployed to" }, { "type": "String", "name": "deploy_action", "value": "CREATE", "description": "Name of the current action being deployed" }, { "type": "String", "name": "deploy_stack_id", "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc", "description": "ID of the stack this deployment belongs to" }, { "type": "String", "name": "deploy_resource_name", "value": "deployment", "description": "Name of this deployment resource in the stack" }, { "type": "String", "name": "deploy_signal_id", "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fdeployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=ca3571413e4a49998d580215517b3685&SignatureVersion=2&Signature=w6Iu%2BNbg86mqwSOUf1GLuKPO7KaD82PiGpL4ig9Q1l4%3D", "description": "ID of signal to use for signalling output values" } ], "group": "script", "name": "a-config-we5zpvyu7b5o", "outputs": [ { "type": "String", "name": "result", "error_output": false, "description": null } ], "options": null, "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", "id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434" }, { "inputs": [ { "default": null, "type": "String", "name": "foo", "value": "fu", "description": null }, { "default": null, "type": "String", "name": "bar", "value": "barmy", "description": null }, { "type": "String", "name": "deploy_server_id", "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", "description": "ID of the server being deployed to" }, { "type": "String", "name": "deploy_action", "value": "CREATE", "description": "Name of the current action being deployed" }, { "type": "String", "name": "deploy_stack_id", "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc", "description": "ID of the stack this deployment belongs to" }, { "type": "String", "name": "deploy_resource_name", "value": "other_deployment", "description": "Name of this deployment resource in the stack" }, { "type": "String", "name": "deploy_signal_id", "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fother_deployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=7b761482f8254946bcd3d5ccb36fe939&SignatureVersion=2&Signature=giMfv%2BhrAw6y%2FCMKQIQz2IhO5PkAj5%2BfP5YsL6rul3o%3D", "description": "ID of signal to use for signalling output values" } ], "group": "script", "name": "a-config-we5zpvyu7b5o", "outputs": [ { "type": "String", "name": "result", "error_output": false, "description": null } ], "options": null, "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", "id": "8da95794-2ad9-4979-8ae5-739ce314c5cd" } ] }
Method | Path | Description |
---|---|---|
GET | /v1/{tenant_id}/software_deployments/metadata/{server_id} | Show server configuration metadata |
Container
http://developer.openstack.org/api-ref-objectstorage-v1.html#storage_container_services
HTTP/1.1 204 No Content X-Container-Meta-Author: SamuelClemens
Method | Path | Description |
---|---|---|
POST | /v1/{account}/{container} | Create, update, or delete container metadata |
HEAD | /v1/{account}/{container} | Show container metadata |