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:
userDatain 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 nginxUSER_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:
publicIpv4is the IPv4 address mapped to the interface (never configured in the guest), andipv6Prefixits public/64.ipv4is alwaysnullon a private interface. - An instance whose primary interface is private reaches the metadata service on that interface, from its private IPv4 or IPv6 address.
delegatedPrefixeslists the interface’s prefixes as{ prefix, generation }. A pod’s own source address can’t reach the metadata service.nullmeans not known yet, for example just after the instance starts: the secondary arrays,delegatedPrefixes,ownerships,vpc,subnetandprivateIpv4can benull, and so candeviceIndexon an instance launched before it was reported.[]means none. Don’t treatnullas 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.