All pages
Locations and placement
A location is a bucket the app created in a connected cloud and region, or an S3 endpoint. Each carries a cloud and a region. A version lives in exactly one location, the one chosen when it was written; there are no replicas.
Fallback and defaults
- Exactly one location is the organization's fallback. An organization takes writes only once it has one; the first location added becomes it.
- The first location in a cloud is that cloud's default, which you can change. Placement uses it for regions of that cloud without a bucket.
- A location is retired, never deleted: no new writes go to it, its versions stay readable. Make another location the fallback before retiring the fallback. Only an unfinished location, whose setup failed before it took any write, can be removed.
Where a write goes
A writer reports its place as a cloud and a region. Every new version goes to the first location that matches:
- Region: an active location with the same cloud and region. Free.
- Cloud: the default location of the same cloud. Cross-region, inside the cloud.
- Fallback: the organization's fallback. The begin response carries a warning, the client logs it, and the usage page counts it.
A write whose uploads fail against its location begins again with that location
excluded, which moves it down the list: a broken bucket costs money, not the
run. A read always goes to the one location that holds the version; the response
says whether that is local, cross-region or cross-cloud.
Finding the place on a box
The client works its place out once at start-up, in this order, and sends the
source with every request as place.source so the app can show how a write was
placed.
| Source | How | Gives |
|---|---|---|
env |
O41_ARTIFACTS_CLOUD and O41_ARTIFACTS_REGION, both or neither |
Whatever the job says; the override |
skypilot |
SKYPILOT_CLUSTER_INFO, which SkyPilot sets for every task, managed jobs included, to the cloud and region of the cluster it runs on. A recovered job sees its new cluster |
Every job SkyPilot launches, on every cloud it supports |
metadata |
The VM's firmware, then its metadata service. The DMI strings in /sys/class/dmi/id name AWS, GCP or Azure without a network call; only that cloud's metadata service is asked for the region, with a 1 s timeout |
Jobs started some other way on the three big clouds, and Kubernetes pods on their managed Kubernetes |
none |
Nothing found: a laptop, an on-premises box | An unknown place: the fallback |
A SkyPilot cloud of kubernetes, ssh or slurm is not a usable answer, since
its region is a context or cluster name; the client goes on to the firmware.
Regions are the cloud's own names, and a location's tag uses the same strings,
so nebius / eu-north1 from SkyPilot matches an S3 endpoint tagged nebius /
eu-north1.
| Cloud | Region from the metadata service |
|---|---|
| AWS | PUT http://169.254.169.254/latest/api/token, then GET /latest/meta-data/placement/region with the token |
| GCP | GET http://metadata.google.internal/computeMetadata/v1/instance/zone with Metadata-Flavor: Google, cut from the zone |
| Azure | GET http://169.254.169.254/metadata/instance/compute/location?api-version=2021-02-01&format=text with Metadata: true |
Usage
The usage page answers two questions: which places write to the fallback or another region, which is where a new location pays, and how many bytes cross clouds on reads.