Availability zones

An availability zone is a full, independent deployment: its own hardware, its own control plane, its own database, its own API host. Zones are not shards of one system, and there is no global endpoint that fans out across them.

The practical rule: a resource lives in exactly one zone, and you talk to that zone's API to reach it. A VM created in one zone is not listed, not fetchable and not deletable through another. That is also why a 404 is worth checking against your base URL before you check against your id.

There is deliberately no api.interlaken.ai sitting in front of the zones. Nothing routes between them, so a request can only ever mean the zone it was addressed to.

Finding the zones

The catalogue is a static file, published at interlaken.ai/zones.json and read at boot by the console and by every orchestrator. It is the same file for everyone, so read it rather than keeping your own list:

{
  "regions": [
    { "id": "eu-par", "city": "Paris", "country": "France", "flag": "🇫🇷" }
  ],
  "zones": [
    { "id": "eu-par-1", "region": "eu-par", "api": "https://api.eu-par-1.interlaken.ai", "status": "active" }
  ]
}

A region is a metro, which is what a customer picks. A zone is a failure domain inside it and a wholly separate deployment: two zones in the same city share the city and nothing else. status is active, maintenance or offline; skip offline zones, and expect writes to be refused in a zone under maintenance.

Hosts follow https://api.<zone>.interlaken.ai, but take the api field rather than building the string yourself, so a zone that is ever hosted differently still works.

Asking which zone answered

curl -s https://api.eu-par-1.interlaken.ai/api/v1/zone \
  -H "Authorization: Bearer $TOKEN"

{
  "self": { "id": "eu-par-1", "api": "https://api.eu-par-1.interlaken.ai", "region": "eu-par", "status": "active" },
  "zones": [ … ],
  "maintenance": false,
  "standalone": false,
  "from_cache": false
}

self is the zone that answered, which is the useful half when a request has gone somewhere you did not expect. standalone marks a deployment with no catalogue to consult, the normal state of a development instance. from_cache says the zone is serving its last good copy of the catalogue rather than a fresh fetch.

Identity is shared, resources are not

Your account and your tenant exist across zones: IAM is replicated, so the same credentials sign in everywhere and a browser remembered in one zone is remembered in the others. Revoking a token ends it everywhere.

But a workspace has to be switched on in a zone before it can hold anything there, with POST /api/v1/tenants/{id}/zones. Until then, that zone's API will authenticate you and then find nothing.

API clients follow the same rule as everything else: the credential is valid in any zone, and the resources it can see differ per zone.

Writing against several zones

Keep the zone as configuration, not as a constant. The three things that vary are the base URL, the zone id you label your own records with, and nothing else: the routes, the permission keys and the token format are identical everywhere.

The interlaken CLI models this with profiles, one per zone, each holding its own API client. interlaken whoami says which profile and zone you are pointed at, which is worth checking before anything destructive. See The interlaken CLI.