# Locations and placement

A **location** is a bucket the app created in a connected cloud and region, or
an [S3 endpoint](https://artifacts.041.io/docs/s3-endpoints.md). 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:

1. **Region**: an active location with the same cloud and region. Free.
2. **Cloud**: the default location of the same cloud. Cross-region, inside the
   cloud.
3. **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.

---

Artifacts by 041 documentation. Every page: https://artifacts.041.io/llms.txt