The Compute service uses a special metadata
service to enable virtual machine instances to
retrieve instance-specific data. Instances access
the metadata service at
http://169.254.169.254
. The
metadata service supports two sets of APIs: an
OpenStack metadata API and an EC2-compatible API.
Each of the APIs is versioned by date.
To retrieve a list of supported versions for the
OpenStack metadata API, make a GET request to
http://169.254.169.254/openstack
For example:
$ curl http://169.254.169.254/openstack 2012-08-10 latest
To list supported versions for the
EC2-compatible metadata API, make a GET request to
http://169.254.169.254
.
For example:
$ curl http://169.254.169.254 1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01 2009-04-04 latest
If you write a consumer for one of these APIs, always attempt to access the most recent API version supported by your consumer first, then fall back to an earlier version if the most recent one is not available.
Metadata from the OpenStack API is distributed
in JSON format. To retrieve the metadata, make a
GET request to
http://169.254.169.254/openstack/2012-08-10/meta_data.json
.
For example:
$ curl http://169.254.169.254/openstack/2012-08-10/meta_data.json
{ "uuid":"d8e02d56-2648-49a3-bf97-6be8f1204f38", "availability_zone":"nova", "hostname":"test.novalocal", "launch_index":0, "meta":{ "priority":"low", "role":"webserver" }, "public_keys":{ "mykey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n" }, "name":"test" }
Instances also retrieve user data (passed as the
user_data
parameter in the
API call or by the --user_data
flag in the nova boot command)
through the metadata service, by making a GET
request to
http://169.254.169.254/openstack/2012-08-10/user_data
.
For example:
$ curl http://169.254.169.254/openstack/2012-08-10/user_data #!/bin/bash echo 'Extra user data here'
The metadata service has an API that is compatible with version 2009-04-04 of the Amazon EC2 metadata service; virtual machine images that are designed for EC2 work properly with OpenStack.
The EC2 API exposes a separate URL for each
metadata. You can retrieve a listing of these
elements by making a GET query to
http://169.254.169.254/2009-04-04/meta-data/
For example:
$ curl http://169.254.169.254/2009-04-04/meta-data/ ami-id ami-launch-index ami-manifest-path block-device-mapping/ hostname instance-action instance-id instance-type kernel-id local-hostname local-ipv4 placement/ public-hostname public-ipv4 public-keys/ ramdisk-id reservation-id security-groups
$ curl http://169.254.169.254/2009-04-04/meta-data/block-device-mapping/ ami
$ curl http://169.254.169.254/2009-04-04/meta-data/placement/ availability-zone
$ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/ 0=mykey
Instances can retrieve the public SSH key
(identified by keypair name when a user requests a
new instance) by making a GET request to
http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key
.
For example:
$ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova
Instances can retrieve user data by making a GET
request to
http://169.254.169.254/2009-04-04/user-data
.
For example:
$ curl http://169.254.169.254/2009-04-04/user-data #!/bin/bash echo 'Extra user data here'
The metadata service is implemented by either the nova-api
service or the nova-api-metadata
service. (The nova-api-metadata
service is generally only used when running in
multi-host mode, it retrieves instance-specific metadata). If you are running the
nova-api
service, you must have
metadata
as one of the elements of the list of the
enabled_apis
configuration option in
/etc/nova/nova.conf
. The default
enabled_apis
configuration setting includes the metadata
service, so you should not need to modify it.
Hosts access the service at 169.254.169.254:80
, and this is
translated to metadata_host:metadata_port
by an iptables rule
established by the nova-network
servce. In
multi-host mode, you can set metadata_host
to
127.0.0.1
.
To enable instances to reach the metadata
service, the nova-network
service configures
iptables to NAT port 80
of the
169.254.169.254
address to
the IP address specified in
metadata_host
(default
$my_ip
, which is the IP
address of the nova-network
service) and port
specified in metadata_port
(default 8775
) in
/etc/nova/nova.conf
.
Warning | |
---|---|
The |
Note | |
---|---|
The default Compute service settings assume
that the Set the |
Configuration option = Default value | Description |
---|---|
[DEFAULT] | |
metadata_host = $my_ip | (StrOpt) The IP address for the metadata API server |
metadata_listen = 0.0.0.0 | (StrOpt) The IP address on which the metadata API will listen. |
metadata_listen_port = 8775 | (IntOpt) The port on which the metadata API will listen. |
metadata_manager = nova.api.manager.MetadataManager | (StrOpt) OpenStack metadata service manager |
metadata_port = 8775 | (IntOpt) The port for the metadata API port |
metadata_workers = None | (IntOpt) Number of workers for metadata service. The default will be the number of CPUs available. |
vendordata_driver = nova.api.metadata.vendordata_json.JsonFileVendorData | (StrOpt) Driver to use for vendor data |
vendordata_jsonfile_path = None | (StrOpt) File to load json formatted vendor data from |