Skip to content

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_REGION becomes 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; the SenderSetupStore port and the replica carry it)

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 region field.
  • SES_REGION stays: it is the default Region. SES_REGIONS, optional, is the comma-separated allowlist; unset, it is SES_REGION alone. It must include SES_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_TRANSACTIONAL and SES_CONFIGURATION_SET_MARKETING may contain {region}, which stands for the Region of the send, for example cl-{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.
  • 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-tenant takes an optional providerRegion, 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 with validation_error (400), with an issue on providerRegion, 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.
  • 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_REGION does 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).
  • The send context is { stream, providerTenant, providerRegion }; claimSend fills 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 unavailable with providerReason provider_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.
  • 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 resolve unknown messages 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’s region, compared with the workspace’s provider tenant and Region.
  • One Region is configured by default: the managed service sets SES_REGION to its Region and leaves SES_REGIONS unset. 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 SenderSetupStore port changes: every write takes the default Region, the tenant write takes the requested Region and the allowlist and reports not_found or region_not_allowed, and assignProviderRegion records 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:SendEmail in 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.