---
title: "User data and instance metadata"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User data and instance metadata

Every image runs [cloud-init](https://cloudinit.readthedocs.io/) 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](/compute-api/CreateInstance/), base64-encoded.

It's at most 16 KiB before encoding, and is never recorded in [Trails](/trails).

```yaml
#cloud-config
package_update: true
packages: [nginx]
runcmd:
  - systemctl enable --now nginx
```

```sh
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](/secrets/instances) 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](/compute/consoles#logging-in). 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](/compute/images) |
| 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](/private-networks/vpcs#in-the-guest) 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`:

```sh
curl -s -H "EZGH-Metadata: true" http://169.254.169.254/ezgh/v1/instance
```

```json
{
  "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](#instance-bot-credentials)) |
| `GET /ezgh/v1/credentials` | The [bot](/compute/instance-bots)'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](/private-networks/vpcs#private-network-interfaces) 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](/private-networks/vpcs#delegated-prefixes). The [secondary-address hook](/private-networks/vpcs#configure-secondary-addresses-in-the-guest)
configures the guest from these.

```json
{
  "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](/private-networks/network-gateways): `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](/compute/instance-bots), 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:

```sh
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
```

```json
{
  "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](/compute/instance-bots).

Source: https://docs.ezghcloud.com/compute/user-data-and-metadata/index.mdx
