Metadata¶
Metadata is a service offered on every Equinix Metal™ server instance that allows it to access and share various data about itself.
Metadata can be accessed only after the server has hit the "Active" state in the provisioning process. If you are using an Equinix Metal OS image, that is typically after the operating system is fully installed and your server is ready to go. If you are using Custom iPXE, your server will be "Active" once the Equinix Metal initial boot process has finished, and before the the OS is written to disk. This allows you to access the metadata endpoint during Custom iPXE provisioning.
Limitations:
- The metadata endpoint is only available when a server is in Layer 3 or Hybrid Bonded networking modes. Pure Layer 2 only networking modes do not support the metadata endpoint.
- Metadata is only accessible from the server itself. Scripts or utilities running on the server can access the metadata endpoint, and user access to the endpoint is available if you are SSHed into the server.
Retrieving Metadata¶
You can view the metadata of a server instance by querying the following endpoint with a tool such as cURL.If you want to grab specific information from the metadata, you can use jq to filter on specific fields.
curl https://metadata.platformequinix.com/metadata | jq
There are specific resources provided by the metadata service at their own endpoints, these are covered in the Metadata Resources section.
Full Metadata Contents¶
About¶
Metadata includes some top-level information like hostname, plan, and your server's UUID. It also contains some useful fields for setting up automation or configuring other features, such as your server's metro and facility. If you are setting up iSCSI volumes, the server's IQN is also included.
"id": "d4b783e9-89f3-4d35-bdcd-ff6753b11911",
"hostname": "bgp-testing-3",
"iqn": "iqn.2021-09.net.packet:device.d4b783e9",
"plan": "c3.small.x86",
"reserved": false,
"class": "c3.small.x86",
"facility": "sv15",
"metro": "sv",
"private_subnets": [
"10.0.0.0/8"
],
"switch_short_id": "3bbc11a0",
Operating System¶
The operating_system tells you which operating system and version is installed. If you provisioned with one of Equinix Metal's OS images, it will also contain the image tag.
"operating_system": {
"slug": "ubuntu_20_10",
"distro": "ubuntu",
"version": "20.10",
"license_activation": {
"state": "unlicensed"
},
"image_tag": "151bba731256fdfefb25bccbcf16575b999c1e6c"
},
SSH Keys¶
ssh_keys is an array of all the SSH keys that were added to the server at provision time.
"ssh_keys": [
"ssh-rsa AAAAB3..."
],
State¶
state tells you the current state of a device.
"state": "active",
Storage¶
The storage information contains the disk, partition, and filesystem information.
"storage": {
"disks": [
{
"device": "/dev/sda",
"wipeTable": true,
"partitions": [
{
"label": "BIOS",
"number": 1,
"size": 4096
},
{
"label": "SWAP",
"number": 2,
"size": "3993600"
},
{
"label": "ROOT",
"number": 3,
"size": 0
}
]
}
],
"filesystems": [
{
"mount": {
"device": "/dev/sda3",
"format": "ext4",
"point": "/",
"create": {
"options": [
"-L",
"ROOT"
]
}
}
},
{
"mount": {
"device": "/dev/sda2",
"format": "swap",
"point": "none",
"create": {
"options": [
"-L",
"SWAP"
]
}
}
}
]
},
Specs¶
The specs object contains the specific hardware components in your server.
"specs": {
"cpus": [
{
"count": 1,
"type": "Intel(R) Xeon(R) E-2278G CPU @ 3.40GHz"
}
],
"memory": {
"total": "32GB"
},
"drives": [
{
"count": 2,
"size": "480GB",
"type": "SSD",
"category": "boot"
}
],
"nics": [
{
"count": 2,
"type": "10Gbps"
}
],
"gpu": [
{
"count": 1,
"type": "Intel HD Graphics P630"
}
],
"features": {
"raid": false,
"txt": true,
"uefi": false
}
},
Network¶
The network object contains information on the bond (or bonds), the separate network interfaces in the bonds, and all the details on your server's management IP addresses. If the server is connected to a Metal Gateway, metal_gateways is populated with its information.
"network": {
"bonding": {
"mode": 4,
"link_aggregation": "mlag_ha",
"mac": "0c:42:a1:65:fd:ce"
},
"interfaces": [
{
"name": "eth0",
"mac": "0c:42:a1:65:fd:ce",
"bond": "bond0"
},
{
"name": "eth1",
"mac": "0c:42:a1:65:fd:cf",
"bond": "bond0"
}
],
"addresses": [
{
"id": "aee6e0ca-70d1-4af2-b9b6-744e115ca1c4",
"address_family": 4,
"netmask": "255.255.255.254",
"created_at": "2021-09-15T15:25:08Z",
"public": true,
"cidr": 31,
"management": true,
"enabled": true,
"network": "203.0.113.0",
"address": "203.0.113.1",
"gateway": "203.0.113.0",
"parent_block": {
"network": "203.0.113.0",
"netmask": "255.255.255.254",
"cidr": 31,
"href": "/ips/afc6f4cc-04f7-4c63-ac4d-a8e0aea541db"
}
},
{
"id": "97411ab0-922f-43b6-9b4f-e22b2b9a6c11",
"address_family": 6,
"netmask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:fffe",
"created_at": "2021-09-15T15:25:08Z",
"public": true,
"cidr": 127,
"management": true,
"enabled": true,
"network": "2001:DB8:45e1:5000::",
"address": "2001:DB8:45e1:5000::1",
"gateway": "2001:DB8:45e1:5000::",
"parent_block": {
"network": "2001:DB8:45e1:5000:0000:0000:0000:0000",
"netmask": "ffff:ffff:ffff:ff00:0000:0000:0000:0000",
"cidr": 56,
"href": "/ips/7281c066-f4c2-4700-88da-b90dc3b5da32"
}
},
{
"id": "b04b5c36-82aa-4f5e-a026-8bddee388134",
"address_family": 4,
"netmask": "255.255.255.254",
"created_at": "2021-09-15T15:25:08Z",
"public": false,
"cidr": 31,
"management": true,
"enabled": true,
"network": "10.67.50.0",
"address": "10.67.50.1",
"gateway": "10.67.50.0",
"parent_block": {
"network": "10.67.50.0",
"netmask": "255.255.255.128",
"cidr": 25,
"href": "/ips/b4b06d38-8730-47e3-8bbe-415b86aafea4"
}
}
],
"metal_gateways": []
},
Tags¶
"tags": [
"test",
"SV_01",
"Dev"
],
URLs¶
"api_url": "https://metadata.packet.net",
"phone_home_url": "http://tinkerbell.sv15.packet.net/phone-home",
"user_state_url": "http://tinkerbell.sv15.packet.net/events"
The phone_home_url and user_state_url are useful if you are using Custom iPXE or custom user data to provision and configure your servers.
BGP Neighbors¶
If you have BGP enabled on your Project and server, then the metadata contains the "bgp_neighbors" object. It will not be present if BGP is not enabled.
"bgp_neighbors": [
{
"address_family": 4,
"customer_as": 65000,
"customer_ip": "10.67.50.1",
"md5_enabled": false,
"md5_password": null,
"multihop": true,
"peer_as": 65530,
"peer_ips": [
"169.254.255.1",
"169.254.255.2"
],
"routes_in": [
...
],
"routes_out": []
},
{
"address_family": 6,
"customer_as": 65000,
"customer_ip": "2604:1380:45e1:5000::1",
"md5_enabled": false,
"md5_password": null,
"multihop": true,
"peer_as": 65530,
"peer_ips": [
"fc00:0000:0000:0000:0000:0000:0000:000e",
"fc00:0000:0000:0000:0000:0000:0000:000f"
],
"routes_in": [
...
],
"routes_out": []
}
],
User Data¶
If you are using Userdata when provisioning your server, it is stored on disk and available from the metadata endpoint after provision. You can cURL it from the metadata endpoint.
curl https://metadata.platformequinix.com/userdata
Metadata Resources¶
To get a list of all the available metadata resources, you can query https://metadata.platformequinix.com/2009-04-04/meta-data. Note: the path contains a specific metadata version. 2009-04-04 is the current version.
curl https://metadata.platformequinix.com/2009-04-04/meta-data
instance-id
hostname
iqn
plan
facility
tags
operating-system
public-keys
public-ipv4
public-ipv6
local-ipv4
To get the specific metadata resources, you can also query each of the options. For example, to retrieve the instance ID:
curl https://metadata.platformequinix.com/2009-04-04/meta-data/instance-id