MetaData API

This API is only accessible from IONOS Cloud Server. The MetaData API returns information about the server itself, such as IP address, MAC address or internal id.

The endpoint of the MetaData API is http://169.254.169.254. One the best and quickest ways to access to the information is by using the curl command for Linux servers or the Invoke-WebRequest command for Windows PowerShell.

Let’s see a simple example:

curl http://169.254.169.254
(Invoke-WebRequest 'http://169.254.169.254').Content

In both cases the response will be:

2017-04-23/
latest/

It is important to know that the response returned can include methods or not with with or without a trailing slash. When making a new request using one of the methods, be sure to include the trailing slash when one is present. This is necessary because:

  • When a request contains a trailing slash, the response will return a list of new methods that you can request.
  • When a request doesn’t contain a trailing slash, the response will be a single value.

Note the following example with a trailing slash:

curl http://169.254.169.254/latest/meta_data/

Returns the following list of methods:

server_id
hostname
public_hostname
datacenter
interfaces/
dns/

A request is made using a method without a trailing slash, a single value is returned:

curl http://169.254.169.254/latest/meta_data/server_id

A single value is returned:

95728AFEE767DE90C5653A17FC8A358E

If it's necessary to retrieve all information at once, the special method below will return all meta_data information as JSON.

curl http://169.254.169.254/latest/meta_data.json

Response:

{
  "server_id":"95728AFEE767DE90C5653A17FC8A358E ",
  "hostname":"localhost",
  "public_hostname":"",
  "datacenter":"Spain",
  "interfaces":{
      "public":[
        {
            "mac":"00:50:56:02:53:3F",
            "ipv4":[
              {
                  "ip_address":"82.223.28.62",
                  "netmask":"255.255.255.255",
                  "gateway":"10.255.255.1"
              }
            ]
        }
      ],
      "private":[

      ]
  },
  "dns":{
      "nameservers":"82.223.28.12,82.223.29.12"
  }
}

Methods

The complete information that you can obtain with the Metadata APi is the following.

http://169.254.169.254

2017-04-23/ All methods available in this first version of the API released on Apr 23rd 2017. When new methods are added/changed, new dates will appear.
latest/ All current methods available in the API.
meta_data/ All metadata information about the server you queried.
user_data Information set by the user when created the server. More information here.
vendor_data Internal information about the configuration of the Cloud Config modules.

http://169.254.169.254/latest/meta_data

server_id Id of the server where this request is executed. The id matches with the internal server’s id for the public Cloud Server API.
hostname Initial hostname of the server.
public_hostname Public hostname of the server. Not available for all servers. Empty in that case.
datacenter The datacenter where the server is located.
interfaces/ Information regarding the public and private interfaces.
dns/ intormation about the DNS configured for the server.

http://169.254.169.254/latest/meta_data/interfaces/

public/ Lists the public interfaces assigned to the server. Usually only one.
private/ Lists the private interfaces assigned to the server.

http://169.254.169.254/latest/meta_data/interfaces/public/

0/ Shows information about the first public interface.

http://169.254.169.254/latest/meta_data/interfaces/public/0/

mac MAC of the interface.
ipv4/ Lists the IPv4 IP assigned to the server.

http://169.254.169.254/latest/meta_data/interfaces/public/0/ipv4/

0/ First IP assigned to the server.

http://169.254.169.254/latest/meta_data/interfaces/public/0/ipv4/0/

ip_address IP address.
netmask/ Netmask configured for the IP.
gateway/ Gateway configured for the IP.

http://169.254.169.254/latest/meta_data/dns/nameservers

nameservers List of the nameservers configured for the server for IPv4.

http://169.254.169.254/latest/meta_data/dns/nameservers6

nameservers List of the nameservers configured for the server for IPv6.

UserData

http://169.254.169.254/latest/meta_data/interfaces/

When a new server is created from the CloudPanel, there is a special field in Advanced Options called UserData. Any text entered here will be saved as the UserData for the server. It will be accessible from the Metadata API.

The real use of the UserData, however, is the connection that it has with Cloud Init. Cloud Init is a special package preinstalled on certain Operating Systems (CentOS, Ubuntu, Debian, Windows) that allows scripts added to the UserData field to be executed on the server when called.

CloudInit has its own meta-language called CloudConfig. You can browse various examples on its website.

There are additional programming languages allowed as bash, such as bash, Powershell or Command-Line. These scripts can take advantage of the Metadata API because they will be executed after the server is deployed. So, it's possible to declare a variable IP based on the content of a request, like the following:

curl http://169.254.169.254/latest/meta_data/interfaces/public/0/ipv4/0/ip_address

These scripts are useful to configure the server as desired after its creation. It's possible to install packages, users, configure services, etc.