Retrieving Instance Metadata

Topics

About Instance Metadata

Two types of metadata are stored within your instances: user-defined instance attributes that you can define explicitly while creating instances, and predefined instance metadata fields that are stored by default for all instances. Scripts and applications running on the instances can use the available metadata to perform certain tasks. For example, SSH public keys that are specified while creating an instance are stored as metadata on the instance. A script running on the instance can retrieve these keys and append them to the authorized_keys file of specified users to allow key-based login to the instance using ssh.

Predefined Instance Metadata

The following predefined metadata fields are stored on every instance that you create:

Metadata	Description	Example
`local-ipv4`	Private IP address of the instance.	`10.196.47.210`
`local-hostname`	DNS name of the instance.	`bd6032.acme.oraclecloud.example.com`
`instance-id`	Name of the instance.	`/Compute-acme/joe.jonathan@example.com/debc974c-852e-4bd2-acd6-45a2de2109fd`
`instance-type`	Memory and CPU resources available for the instance.	`7680 ram, 2.0 cpus`
`public-keys/{index}/openssh-key`	SSH public key specified while creating the instance, where `{index}` is a number starting with `0`.	`ssh-rsa AAAAB3NzaC1yc2EAAAABI... == admin@acme`

Note:

You may see certain additional metadata fields, such as reservation-id, product-codes, kernel-id, public-hostname, and security-groups, that aren’t documented. Don’t retrieve and use the values in the undocumented fields.

The predefined instance metadata fields are stored at http://192.0.0.192/{version}/metadata.

The following metadata versions are currently available:

latest
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2009-04-04

Tip:

New metadata versions may be released in the future. Metadata versions may not be backward compatible. So use metadata from a specific version (for example, from http://192.0.0.192/2008-02-01/) and not from http://192.0.0.192/latest/.

For the steps to retrieve the predefined instance metadata, see Retrieving Predefined Instance Metadata.

User-Defined Instance Attributes

User-defined attributes are key-value pairs that you can specify in the attributes parameter of machine images, image-list entries, and instance launch plans.

When you create instances, all the attributes that are specified in the attributes parameter in the orchestration or launch plan, machine image, and image list entry that are used to create your instances are stored on those instances. If an attribute in an image-list entry has the same name as an attribute in the machine image corresponding to that image-list entry, then the attribute in the image-list entry overrides the attribute in the machine image. Similarly, if an attribute in a launch plan has the same name as an attribute in an image-list entry or a machine image, then the attribute in the launch plan takes precedence.

User-defined instance attributes are stored within the instance at http://192.0.0.192/latest/user-data. For the steps to retrieve these attributes, see Retrieving User-Defined Instance Attributes.

The following are a few sample use cases for user-defined instance attributes:

If you want identical user data to be available on a set of instances, then specify the required user data in the machine image or image list entry that you'll use to create the instances. For example, you might require a certain pre-bootstrap script to be executed or specific applications to be installed on all instances that use a particular image. By specifying this script as user data in the machine image or the image list entry, you ensure that every instance that’s created with that image has the specified user data.
If each instance should have unique user data, use an orchestration to provide specific user data for each instance. This is useful if, for example, you want to specify a unique user name and password, or inject a unique SSH public key into each instance.
You can automate instance configuration by providing scripts or other instructions to perform prebootstrapping tasks or install applications when you create an instance. These instance configuration instructions are provided as user-defined data using the userdata field under the attributes parameter. For example, you can use this field to specify the location of a database server and login details.

Retrieving Predefined Instance Metadata

Log in to the instance.
See Logging In to an Instance.
Get a list of the available metadata versions by running the following command:
```
curl http://192.0.0.192
```
Note:

The cURL commands provided in this document are for Linux and Oracle Solaris instances. On Windows instances, go to the PowerShell, and use the Invoke-RestMethod command instead of cURL.
From the list of versions displayed, select the version that you want to use.
Get a list of the top-level metadata fields:
```
curl http://192.0.0.192/{version}/meta-data
```
In this command, replace {version} with the version that you identified in the previous step.

Example:
```
curl http://192.0.0.192/2007-08-29/meta-data
```
Retrieve the specific metadata that you want, by running one of the following command examples:
Note:

When you run these commands, replace 2007-08-29 with the metadata version that you want to use.
- To retrieve the private IP address of the instance:
```
curl http://192.0.0.192/2007-08-29/meta-data/local-ipv4
10.106.15.70
```
- To retrieve the host name of the instance:
```
curl http://192.0.0.192/2007-08-29/meta-data/local-hostname
bd6032.acme.oraclecloud.com
```
- To retrieve information about the memory and CPU resources of the instance:
```
curl http://192.0.0.192/2007-08-29/meta-data/instance-type
7680 ram, 2.0 cpus
```
- To retrieve the instance name:
```
curl http://192.0.0.192/2007-08-29/meta-data/instance-id
/Compute-acme/joe.jonathan@example.com/4c318760-444b-4b48-83e1-e1b112c201f2
```
- To find out how many SSH public keys are stored on the instance:
```
curl http://192.0.0.192/2007-08-29/meta-data/public-keys
0
1
2
```
  In this example, three SSH public keys are stored as metadata, with index numbers 0, 1, and 2.
- To retrieve the value of a specific SSH public key:
```
curl http://192.0.0.192/2007-08-29/meta-data/public-keys/0/openssh-key
ssh-rsa AAAAB3NzaC1yc2EAAAABI... == joe.jonathan@acme.com
```

Retrieving User-Defined Instance Attributes

Log in to the instance using SSH.
See Logging In to an Instance.
Get a list of all the top-level attributes that are specified for the instance, by running the following command:
```
curl http://192.0.0.192/latest/user-data
```
Note:

The cURL commands provided in this document are for Linux and Oracle Solaris instances. On Windows instances, go to the PowerShell, and use the Invoke-RestMethod command instead of cURL.
The following is an example of the output:
```
pre-bootstrap
packages
```
In this example, the output shows that the instance has two top-level user-defined attributes: pre-bootstrap and packages.
To retrieve the attributes defined under the top-level pre-bootstrap attribute, run the following command:
```
curl http://192.0.0.192/latest/user-data/{topLevelAttribute}
```
Example:
```
curl http://192.0.0.192/latest/user-data/pre-bootstrap
```
The following sample output indicates that two attributes are specified under the pre-bootstrap attribute:
```
failonerror
scriptURL
```
Run the same command for successive levels of attributes until you get the required attribute value, as shown in the following example:
```
curl http://192.0.0.192/latest/user-data/pre-bootstrap/failonerror
true
```

Sample Scenario for Specifying and Using Instance Attributes

Consider a distributed system where a manager instance must handle requests from a set of worker instances. The instances in this sample scenario are identical in all other respects. So they’re based on the same machine image.

Create an image list containing two entries, both for the same machine image, but one entry with the attribute {"role":"manager"} and the other with the attribute {"role":"worker"} in the attributes field. To create an image list entry using the API, use the POST /imagelist/name/entry method. See REST API for Oracle Cloud Infrastructure Compute Classic .

In the launch plan that you use to provision the instances in the distributed system, define a number of worker instances that use the image list entry with the {"role":"worker"} attribute, and define a manager instance that uses the image list entry with the {"role":"manager"} attribute.

After the instances are created, the software running on each instance can determine the role that the instance should play based on the value of the role attribute stored at http://192.0.0.192/version/user-data.