Use canonical locations for compute placement

[scotwells]

Summary

Compute placement now speaks the same language as the rest of Datum Cloud. A workload is placed at locations, the names you see in datumctl get locations, instead of airport-style city codes. There are two ways to say where a placement runs:

• Name the locations. The default. The placement is pinned to exactly the locations you list.
• Select them by topology. The advanced path. A label selector over each location's topology (city code, region, or any other key the platform projects) picks every Ready location that matches, and the placement follows the fleet as locations come and go.

The CLI, portal, API, samples, and docs all move together so a developer sees one concept from the first deploy to the instance detail page.

What a developer sees

Deploy by name. Tab completion offers the Ready locations projected into the project, and keeps working through a comma-separated list. --city completes the city codes those locations serve, and --location-selector completes the key=value topology pairs they carry, so the available topology keys can be discovered from the shell:

$ datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --location=us-east-1,eu-west-1 --min=2 --port=8080

Resolving workload "api" in project acme-prod...
  Workload does not exist — creating.
  Placement "default": locations=[us-east-1, eu-west-1], min=2

  PLACEMENT  LOCATION    DESIRED  READY  PHASE
  default    us-east-1         2      2   Running
  default    eu-west-1         2      2   Running

The interactive prompt asks for locations and "min replicas per location" instead of cities.

Deploy by topology. --location-selector takes ordinary label selector syntax. Every Ready location that matches gets a deployment. A location that later starts matching is picked up on its own, and one that stops matching is torn down:

$ datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --location-selector='topology.datum.net/city-code=DFW'
  Placement "default": selector=[topology.datum.net/city-code=DFW], min=1

$ datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --location-selector='topology.datum.net/region in (us-east-1,eu-west-1)'

In a manifest the same placement is a standard selector block, and the workload's status reports what it resolved to:

spec:
  placements:
  - name: dfw
    locationSelector:
      matchLabels:
        topology.datum.net/city-code: DFW
    scaleSettings:
      minReplicas: 1
status:
  placements:
  - name: dfw
    locations:
    - name: gcp-us-south1-a
    - name: gcp-us-south1-b

A placement sets either locations or locationSelector, never both. An empty selector is rejected rather than treated as "everywhere". A placement that resolves to nothing stays visible in status with a NoMatchingLocations condition instead of silently disappearing.

City codes are a shortcut for a selector. --city=DFW,IAD is shorthand for a location selector on topology.datum.net/city-code, so the placement runs at every Ready location in those cities and keeps tracking them as locations are added or removed. The saved workload config records the selector, and a city with no Ready location is rejected at admission with the list of locations that do exist. Pin a placement to specific locations with --location instead.

Inspect with --location. Every list and describe command filters by location and shows a LOCATION column, and workloads describe shows a placement's selector alongside the locations it resolved to:

$ datumctl compute workloads --location=us-east-1
$ datumctl compute instances --location=us-east-1
$ datumctl compute instances describe api-us-east-1-0
  Placement      default
  Location       us-east-1

rollout, scale, restart, and destroy follow the same pattern.

Mistakes are caught at admission. An unknown location, a location that is not Ready or where compute is not available, a duplicate in one placement, or a selector that is empty, malformed, or matches no such location is rejected with a field-level error listing the valid choices, rather than landing in a deployment that never schedules.

Portal (consumer and provider) labels workload and instance views as "Locations", shows the location on instance cards and page chrome, reports replicas per location, and for selector-based placements shows the selector and the locations it resolved to.

API changes

This changes the alpha API, with a shim so workloads stored before the rollout keep running:

• Workload.spec.placements[].cityCodes is replaced by placements[].locations (a list of {name} references) or placements[].locationSelector (a label selector over location topology). Exactly one must be set, enforced by CEL on the CRD and by the webhook.
• cityCodes stays as a deprecated field so existing objects survive the CRD change. Admission rewrites a placement that only names city codes into the equivalent city-code selector on every write, and the workload controller rewrites each stored workload the first time it reconciles it after the rollout, writing it back before deriving deployments. Until that write succeeds a workload keeps what it already runs. The federator finalizes pre-location deployments by reading the city off their hub copy and removing the city-keyed propagation policies once nothing routed by that city remains.
• Workload.status.placements[].locations lists the locations a placement currently resolves to.
• WorkloadDeployment.spec.cityCode becomes spec.locationRef. The status.location field is removed since the location is now declared in spec, and kubectl get workloaddeployments shows a LOCATION column.
• Instances carry a compute.datumapis.com/location label instead of city-code.
• Deployments and cells route with the topology.datum.net/location label.

Placements are validated and resolved through the location source abstraction, so both the NetworkServices and Locations sources work. A location is placeable when it is Ready and compute is available there. Readiness comes from the Location (every LocationBinding counts as Ready; a Location must carry a true Ready condition). Availability comes from the ServiceAvailability records the platform mirrors into the project: a record for the compute service naming the location with Available=True. A control plane that does not serve that kind enforces no availability gate. The workload controller watches both the project's locations and its availability records, so placements follow changes without polling.

Samples (including a new location-selector-sandbox.yaml), generated API docs, the compute DX enhancement doc, and e2e fixtures are updated to match.

Validation

• make test
• consumer UI tsc --noEmit
• provider UI tsc --noEmit

[kevwilliams]

Placement move from city codes to canonical locations is well handled end to end: the deprecated cityCodes field is rewritten into an equivalent locationSelector on admission (Default hook) and again by the workload controller on first reconcile after rollout, with writes gated through validation so a workload never loses its running deployments. The federator correctly recognizes deployments with no LocationRef as pre-migration, reads the city off the hub copy before deleting it, and cleans up the old city-keyed PropagationPolicies once nothing references them, while new policies use the location-keyed naming scheme. CLI, webhook, RBAC, CRDs, docs, and e2e fixtures were all updated consistently, and the new code is covered by solid table-driven tests. No missed call sites or migration gaps found.

[scotwells]

@ecv @kevwilliams had to resolve some merge conflicts with main. Diff is larger because I merged #289 into this branch by accident.