Endpoints and regions

Objective

The endpoint shape is embedded in every signature. It cannot be changed after the first customer signs a request.

Read this page before configuring a client, and before implementing a service.

[!primary]

This page states the intended convention. For the hostnames that are actually published today — eleven of them, all flat on shelfcs.com with no region label — see Service endpoints. Where the two disagree, that page describes reality and this one describes the intent.

Instructions

Endpoints

One host per service, per region:

<service>.<region>.<domain>

ec2.hel1.shelfcloud.com
billing.hel1.shelfcloud.com

Global services use a single host with no region label:

iam.shelfcloud.com
account.shelfcloud.com

OPEN (Michael): the public API domain.

There is no endpoint discovery service. Endpoints are constructed from the service name and the region by the rule above, and the rule is documented so that clients can construct them.

Why the shape is fixed

The service name and the region are part of the credential scope, and therefore part of every signature. A client that signed against one host cannot be redirected to a differently-shaped one without every signature failing.

This is also why a single global endpoint_url override in a client configuration is wrong: it would send every service’s calls to one host, and those calls are signed for the service they were meant for.

Regions

A region is a geographic location with its own endpoints, its own resources and its own capacity. Resources do not cross regions, and a request signed for one region is not valid in another.

hel1

PROPOSED: region names are a location code and a digit, where the code names the facility’s location and the digit distinguishes facilities in one location.

OPEN (Michael): whether to adopt AWS-shaped region names — eu-north-1 rather than hel1. SDKs accept arbitrary strings, so hel1 is not a hard break, but region-parsing helpers, partition inference in third-party tooling, and anything that regexes AWS region names will misbehave on a name outside that shape. This is worth a deliberate decision rather than an accident.

Zones

A zone is a subdivision of a region, named as the region followed by a letter:

hel1-a

Every region has at least one zone. A region with one zone says so plainly; it is never implied that there are more.

Resources that live in a zone report their zone from the first release, even while a region has only one, so that a caller storing the zone today keeps working when a second exists.

Which services are regional

Service	Scope	Signing region
EC2	Regional	The region in the host
Billing	Regional	The region in the host
IAM	Global	PROPOSED: `hel1`
Account	Global	PROPOSED: `hel1`

A global service still requires a region in the credential scope. If the server expects one string and the client signs with another, every call returns SignatureDoesNotMatch with no diagnosable cause — so the verifier additionally accepts a signature scoped to the caller’s own configured region for global services.

OPEN (Michael): confirmation of the global/regional split. Moving a service from regional to global later invalidates every stored credential-scope expectation in customer tooling, so it cannot be revisited quietly.

OPEN (Michael): whether an account with resources in several regions receives one invoice or several, which decides whether Billing stays regional.

the cloud platform version floor

The layer requires the compute service microversion 2.83 (Ussuri) on every deployment it fronts. The floor is platform-wide and stated once, here; action pages cite it rather than each declaring their own.

2.83 is set by DescribeInstances: its filter push-down uses vm_state, key_name and availability_zone as non-admin query parameters, which the compute service silently strips below 2.83 rather than rejecting. Every other v1 action needs 2.67 or lower.

At start-up the layer reads the compute service’s version document (GET /) and refuses to serve with ServiceUnavailable if the maximum reported is below the floor. An operator on Stein or Train learns this from the start-up log, not from a customer’s failing call.

OPEN (Michael): whether to hold the floor at 2.83, or drop the DescribeInstances push-down to keep 2.67 and reach older deployments.

Transport

HTTPS only. HTTP requests are refused, never redirected — a redirect would invite a client to send a signed request over an unencrypted connection first.

PROPOSED: TLS 1.2 minimum, TLS 1.3 preferred.