0037. Each workspace's provider tenant has a Region, chosen from a configured allowlist
- Status: Accepted (decided by the maintainer)
- Date: 2026-11-15
- Amends: ADR 0034 (one
SES_REGIONbecomes the default of an allowlist; the send context gains a Region; configuration set names may vary by Region), ADR 0035 (the provider tenant write takes a Region; theSenderSetupStoreport and the replica carry it)
Context
Section titled “Context”ADR 0034 sends through one SES Region, SES_REGION. The managed service starts in one Region, but should be able to give a workspace another Region later by configuration alone, without changing code or the data model.
Facts that shape this (SES documentation, checked 2026-11-15):
- SES is regional. Identities (sending domains), configuration sets, tenants, suppression lists, and sending quotas exist per Region. A tenant name or a verified domain in one Region means nothing in another.
- SES publishes events to the EventBridge bus of the Region that sent the message, and each EventBridge event carries a
regionfield.
Decision
Section titled “Decision”Configuration
Section titled “Configuration”SES_REGIONstays: it is the default Region.SES_REGIONS, optional, is the comma-separated allowlist; unset, it isSES_REGIONalone. It must includeSES_REGION, and every entry must be an AWS Region name. A bad value fails every request with a configuration error that names the variable, never its value.SES_CONFIGURATION_SET_TRANSACTIONALandSES_CONFIGURATION_SET_MARKETINGmay contain{region}, which stands for the Region of the send, for examplecl-{region}-marketing. With one allowed Region, a name without it keeps working as before. With more than one, a name without{region}is a configuration error that names the variable, because one fixed name would point every other Region at a set that may not exist there.- Adding a Region is configuration only: create its SES resources, add it to
SES_REGIONS, and assign it to workspaces. - With neither variable set (the fake provider alone), the installation configures no Regions: the operator endpoints refuse a Region, and none is recorded. Self-hosted installations use the same variables.
Control plane and replica
Section titled “Control plane and replica”- The Region belongs to the workspace’s provider tenant record:
workspaces.provider_region(control-plane migration 0003). A tenant name means something only in its Region, so the two are written together. The workspace’s sending domains are domains verified in that Region; they carry no Region of their own. PUT /operator/workspaces/:workspaceId/provider-tenanttakes an optionalproviderRegion, and the store writes the tenant, the Region, and the version increment in one statement:- With
providerRegion, that Region is recorded: this is the only way a workspace moves. A Region outside the allowlist is refused withvalidation_error(400), with an issue onproviderRegion, and nothing is written. - Without it, the workspace keeps its recorded Region, or gets the default Region if it has none. If the Region it keeps is no longer in the allowlist, the write is refused with
conflict(409) and nothing is written, so the operator names a Region rather than keep one the installation no longer sends through.
- With
- To move a workspace, the operator verifies its domains and creates its tenant in the new Region first, then writes the tenant with the new Region. The replica switches in one write, with no gap in which its messages are skipped.
- Every versioned write of a workspace (a tenant, or a sending domain added, changed, or removed) records the default Region in the same statement if the workspace has none. So a workspace gets its Region with its first write, including a self-hosted workspace that has domains and no tenant, and a later change of
SES_REGIONdoes not move it. - Rows that no write has touched since this change (workspaces from before it, and workspaces inserted by SQL) have no Region. Replication first records the default Region for such a workspace, as a write at a new version, and then replicates it. A replica therefore never carries a Region the control plane lacks, and two replicas of the same version carry the same Region (ADR 0035’s ordering holds). The resync, of every workspace or of one, is the backfill; it already runs right after each deploy.
- The replica carries
providerRegion(project-store migration 8).
Sending
Section titled “Sending”- The send context is
{ stream, providerTenant, providerRegion };claimSendfills it from the replica. Core never interprets the Region. - The SES adapter keeps one SigV4 signer and endpoint per allowed Region, made on the Region’s first send. It sends through the context’s Region, with that Region’s configuration set, or through the default Region when the context has none (a replica written before this change, until the resync).
- A Region outside the allowlist sends nothing: the outcome is
unavailablewithproviderReasonprovider_configuration, the existing outcome for a provider configuration problem, so the store retries it for 24 hours and then fails it, and the operator alert of ADR 0034 applies.
Events
Section titled “Events”- Message events (Send, Delivery, Bounce, Complaint, and the others) are matched to their message by the send-time tags and, once bound, the provider message ID, as ADR 0034 decides, whatever their
region. A Region check would add no isolation, and it would drop late bounces, complaints, and the Send events that resolveunknownmessages after a workspace moves. - SES tenant status events (
Sending Status Enabled,Sending Status Disabled) name a tenant, and a tenant name is per Region: their match key is the tenant and the event’sregion, compared with the workspace’s provider tenant and Region.
Consequences
Section titled “Consequences”- One Region is configured by default: the managed service sets
SES_REGIONto its Region and leavesSES_REGIONSunset. No infrastructure or UI for more Regions is built. - Sending quotas, suppression, and the event destination exist per Region. Each added Region needs its own EventBridge rule and API destination, which may share the endpoint and
SES_EVENTS_SECRET. - The
SenderSetupStoreport changes: every write takes the default Region, the tenant write takes the requested Region and the allowlist and reportsnot_foundorregion_not_allowed, andassignProviderRegionrecords the default for an untouched workspace. Its contract suite covers them. - When the SES adapter is wired (B4), the operator endpoints’ Regions come from the same parsed
SesSendConfig.regions, so the allowlist the operator writes against and the one the adapter sends through cannot differ. - Open:
- Whether different Regions get different sending credentials. Today one IAM key signs for every allowed Region, so its policy must allow
ses:SendEmailin each. - Moving a workspace’s suppression list and tenant between Regions is a manual operator procedure.
- Before removing a Region from
SES_REGIONS, the operator moves every workspace out of it. A workspace left there sends nothing (unavailable), and a tenant write without a Region is refused until it names an allowed one. The resync replicates such workspaces like any other but does not report them.
- Whether different Regions get different sending credentials. Today one IAM key signs for every allowed Region, so its policy must allow