Skip to content

User data and instance metadata

Configure an instance at its first boot with cloud-init user data, and read its ID, addresses, SSH keys, user data and bot credentials from the metadata service.

Updated View as Markdown

Every image runs cloud-init at boot. EZGH Cloud gives it the instance’s host name, SSH keys, network configuration and your user data, without the network. From inside the instance, the metadata service answers the same details over HTTP.

User data

User data is what cloud-init runs at the instance’s first boot: a #cloud-config document, a shell script starting with #!, or any other format cloud-init accepts. It’s set at launch and can’t be changed afterwards.

  • Console: Launch instance, then Advanced, then User data.
  • API: userData in CreateInstance, base64-encoded.

It’s at most 16 KiB before encoding, and is never recorded in Trails.

#cloud-config
package_update: true
packages: [nginx]
runcmd:
  - systemctl enable --now nginx
USER_DATA=$(base64 < cloud-config.yaml | tr -d '\n')

User data is readable from inside the instance (see below), so don’t put long-lived secrets in it: read a secret on the instance with its bot instead. Without SSH keys, user data is the only way to grant access, for example a user with a password for the serial console. EZGH Cloud never adds a password or any other login to an instance.

What cloud-init configures

Value
SSH keys The launch’s keys, for the image’s login user
Host name The instance’s name, with characters other than letters, digits, . and - replaced by -
Network Interfaces named eth0, eth1, … in device order, each with its IPv6 address (<prefix>::1/64) and, with one, its public IPv4 address (/32), MTU 1500, and the default routes on the primary interface. Private interfaces get their primary private addresses, MTU 8900 and their VPC’s routes, never secondary addresses
DNS resolvers 1.1.1.1 and 2606:4700:4700::1111

The network configuration is applied at every boot, not only the first, so an interface or IPv4 address added while the instance was stopped comes up configured. An IPv4 address associated while the instance runs is configured at its next stop and start (a reboot keeps the configuration it booted with). cloud-init rewrites its own network file at each boot: put your network changes in files of your own, or opt out with your own updates: setting in user data.

Instance metadata service

From inside the instance, the metadata service is at http://169.254.169.254 and http://[fd65:7a67:6800::254]. Firewalls always allow it. Every request needs the header EZGH-Metadata: true:

curl -s -H "EZGH-Metadata: true" http://169.254.169.254/ezgh/v1/instance
{
  "id": "ins_7k2m9x0a4qpe",
  "name": "web-1",
  "type": "t1.small",
  "project": "prj_g7h8i9j0k1l2",
  "region": "us-west-1",
  "interfaces": [
    {
      "id": "eni_5q2m9x0a7k1d",
      "kind": "public",
      "mac": "0a:e7:5c:3a:91:0d",
      "ipv4": "203.0.113.10",
      "publicIpv4": null,
      "ipv6Prefix": "2001:db8:10:1a2b::/64",
      "ipv6Address": "2001:db8:10:1a2b::1",
      "deviceIndex": 0,
      "mtu": 1500,
      "vpc": null,
      "subnet": null,
      "privateIpv4": null,
      "secondaryPrivateIpv4Addresses": [],
      "secondaryPrivateIpv6Addresses": [],
      "delegatedPrefixes": [],
      "ownerships": []
    }
  ]
}
Path Answer
GET /ezgh/v1/instance The instance’s ID, name, type, project, region and interfaces with their addresses
GET /ezgh/v1/ssh-keys { "publicKeys": [ … ] }: the launch’s SSH public keys
GET /ezgh/v1/user-data The user data as given, not base64-encoded; 404 without
PUT /ezgh/v1/token A session token, needed for credentials (below)
GET /ezgh/v1/credentials The bot’s temporary API key
Error When
400 metadata_header_required The EZGH-Metadata: true header is missing
403 forwarded_request The request has a header a proxy adds, such as X-Forwarded-For, Forwarded or Via
403 invalid_host The Host header isn’t 169.254.169.254 or [fd65:7a67:6800::254] (optionally with :80)
403 browser_request The request has an Origin header
429 rate_limited Over 100 requests per second from the instance; Retry-After: 1

The header requirement, the proxy-header check and the Host and Origin rules keep a web application on the instance, or a web page in a browser, from being tricked into fetching metadata for someone else. Requests must use one of the two addresses above as their host name, so a name that resolves to them is refused. The service sends no CORS headers, and OPTIONS answers 405.

Private interfaces

A private interface has kind: "private", its VPC, its subnet’s ranges and its primary private IPv4 address, and the private addresses it owns now, each with its ownership generation, and its delegated prefixes. The secondary-address hook configures the guest from these.

{
  "id": "eni_8k2m4x7b1c3d",
  "kind": "private",
  "mac": "0a:e7:5c:3a:91:1e",
  "ipv4": null,
  "publicIpv4": null,
  "ipv6Prefix": "",
  "ipv6Address": "fd3c:91a2:7e04:1a01::a3f1",
  "deviceIndex": 1,
  "mtu": 8900,
  "vpc": "vpc_3n8k2m0x7q1a",
  "subnet": { "ipv4Cidr": "10.0.1.0/24", "ipv6Cidr": "fd3c:91a2:7e04:1a01::/64" },
  "privateIpv4": "10.0.1.20",
  "secondaryPrivateIpv4Addresses": ["10.0.1.50"],
  "secondaryPrivateIpv6Addresses": [],
  "delegatedPrefixes": [{ "prefix": "10.0.1.16/28", "generation": "2" }],
  "ownerships": [
    { "prefix": "10.0.1.20/32", "generation": "3" },
    { "prefix": "fd3c:91a2:7e04:1a01::a3f1/128", "generation": "3" },
    { "prefix": "10.0.1.50/32", "generation": "8" }
  ]
}
  • Only addresses the interface owns now are listed. An address being moved to it appears once the move has succeeded; one being moved away leaves the list once it’s withdrawn from the interface, before the move succeeds.
  • Public addresses through a Network Gateway: publicIpv4 is the IPv4 address mapped to the interface (never configured in the guest), and ipv6Prefix its public /64. ipv4 is always null on a private interface.
  • An instance whose primary interface is private reaches the metadata service on that interface, from its private IPv4 or IPv6 address.
  • delegatedPrefixes lists the interface’s prefixes as { prefix, generation }. A pod’s own source address can’t reach the metadata service.
  • null means not known yet, for example just after the instance starts: the secondary arrays, delegatedPrefixes, ownerships, vpc, subnet and privateIpv4 can be null, and so can deviceIndex on an instance launched before it was reported. [] means none. Don’t treat null as none.

Instance bot credentials

If a bot is attached, code on the instance can fetch short-lived API keys for it. First get a session token, with how long it should last in seconds (1 to 21600), then use it to fetch the credentials:

TOKEN=$(curl -s -X PUT -H "EZGH-Metadata: true" \
  -H "EZGH-Metadata-Token-TTL-Seconds: 21600" \
  http://169.254.169.254/ezgh/v1/token)

curl -s -H "EZGH-Metadata: true" -H "EZGH-Metadata-Token: $TOKEN" \
  http://169.254.169.254/ezgh/v1/credentials
{
  "apiKey": "ezgh_…",
  "expiresAt": "2026-10-23T18:30:00Z",
  "bot": "bot_a1b2c3d4e5f6"
}

Use apiKey as a bearer token (Authorization: Bearer ezgh_…) until expiresAt, which is 10 minutes after the request. Fetch a new key about 5 minutes before that, and once more if an API call answers 401. Every request to /ezgh/v1/credentials returns a new key; don’t call it per API request.

A session token is tied to the instance and kept only in memory by the metadata service. Keep yours in a variable rather than a file. An instance has at most 64 live tokens, and the oldest goes when you make another. Tokens don’t survive a restart of the host’s agent or a live migration: when credentials answer 401 invalid_token, get a new token.

Error When
400 invalid_ttl EZGH-Metadata-Token-TTL-Seconds is missing, isn’t a plain whole number, or is outside 1 to 21600
401 invalid_token The token is missing, expired, unknown, or belongs to another instance
404 no_bot The instance has no bot, or the bot no longer exists
404 not_found The instance isn’t running
429 rate_limited Too many requests; wait for Retry-After and keep using the current key
503 unavailable The key can’t be issued right now; retry after Retry-After, and keep using the current key until it expires

The ezgh CLI and the Workflows SDKs do all this for you; see Give an instance access to EZGH.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close