Getting Instance Metadata

The metadata for an instance includes information such as the instance's OCID , display name, hostname, region, availability domain , fault domain , compartment , shape , image , creation date, state, tags, and any custom metadata that you provide, such as an SSH public key. The instance metadata also includes the region identifier for an instance, such as us-phoenix-1, in the canonicalRegionName field.

You can find some of this information in the Console on the Instance Details page, or you can get all of it by logging in to the instance and using the metadata service. The service runs on every instance and is an HTTP endpoint listening on 169.254.169.254.

Required IAM Policy

No IAM policy is required if you're logged in to the instance and using cURL to get the metadata.

For administrators: Users can also get instance metadata through the Compute API (for example, with GetInstance). The policy in Let users launch Compute instances covers that ability. If the specified group doesn't need to launch instances or attach volumes, you could simplify that policy to include only manage instance-family, and remove the statements involving volume-family and virtual-network-family.

If you're new to policies, see Getting Started with Policies and Common Policies. For reference material about writing policies for instances, cloud networks, or other Core Services API resources, see Details for the Core Services.

Accessing Instance Metadata on Oracle-Provided Images

You can get instance metadata for Oracle-provided images by using cURL on Linux instances or an internet browser on Windows instances.

Instance metadata is available at the following URLs:

  • All of the instance information:

    http://169.254.169.254/opc/v1/instance/
  • Only the custom metadata:

    http://169.254.169.254/opc/v1/instance/metadata/
  • The custom metadata only for a specified key name:

    http://169.254.169.254/opc/v1/instance/metadata/<key-name>

    <key-name> is ssh_authorized_keys, user_data, or any custom key name that you provided when you launched the instance. (For information about using the Core Services API to provide user_data to cloud-init, see LaunchInstanceDetails.)

  • Information about the virtual network interface cards (VNICs) that are attached to the instance:

    http://169.254.169.254/opc/v1/vnics/

Here's an example response that shows of all of the information for an instance:

{
  "availabilityDomain": "cumS:PHX-AD-1",
  "faultDomain": "FAULT-DOMAIN-2",
  "compartmentId": "ocid.compartment.oc1..exampleuniqueID",
  "displayName": "my-example-instance",
  "hostname": "my-hostname",
  "id": "ocid1.instance.oc1.phx.exampleuniqueID",
  "image": "ocid1.image.oc1.phx.exampleuniqueID",
  "metadata": {
    "ssh_authorized_keys": "example-ssh-key"
  },
  "region": "phx",
  "canonicalRegionName": "us-phoenix-1",
  "shape": "VM.Standard2.1",
  "state": "Running",
  "timeCreated": 1569358494495,
  "agentConfig": {
    "monitoringDisabled": false,
    "managementDisabled" : false
  },
  "definedTags": {
    "Operations": {
      "CostCenter": "42"
    }
  },
  "freeformTags": {
    "Department": "Finance"
  }
}

For more information about the data that is returned, see Instance.

Here's an example response that shows the VNICs that are attached to an instance:

[ {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.3.6",
  "vlanTag" : 11,
  "macAddr" : "00:00:00:00:00:01",
  "virtualRouterIp" : "10.0.3.1",
  "subnetCidrBlock" : "10.0.3.0/24",
  "nicIndex" : 0
}, {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.4.3",
  "vlanTag" : 12,
  "macAddr" : "00:00:00:00:00:02",
  "virtualRouterIp" : "10.0.4.1",
  "subnetCidrBlock" : "10.0.4.0/24",
  "nicIndex" : 0
} ]
To use cURL to get Linux instance metadata
  1. Connect to a Linux instance using SSH.
  2. Use cURL to issue a GET request to the instance metadata URL that you're interested in. For example:

    curl -L http://169.254.169.254/opc/v1/instance/
To use an internet browser to get Windows instance metadata
  1. Connect to a Windows instance by using a Remote Desktop connection.
  2. Open an internet browser and then navigate to the instance metadata URL that you're interested in.