0024 - Operator-owned upstream environment identifiers

• Status: Accepted
• Date: 2026-08-18
• Deciders: nexus core team
• Tags: providers, bedrock, azure-foundry, connections, egress

Context and Problem Statement

Provider connections carried public-cloud assumptions that rejected custom and isolated environments before a request could be signed or sent. Bedrock region labels had to match a known partition shape, and Azure Foundry resource names had to match Azure’s public resource-name alphabet.

The catalog separately uses provider lanes as routing, pricing, credential, and import-history identities. Production catalogs contain overlapping bedrock/bedrock-gov models with different prices and credentials, so those lanes cannot be collapsed merely because they share an adapter.

Decision Drivers

• Region labels, DNS suffixes, and deployment names are operator data.
• Values interpolated into hosts, paths, or SigV4 scopes must remain injection-safe.
• Provider lanes remain distinct routing and billing identities.
• An imported artifact should describe a lane completely, including where it lives, because an air-gapped operator hand-editing artifacts has nothing else to describe it with.
• Existing HTTPS-only behavior is unchanged.
• A private certificate authority or a TLS-inspecting egress proxy is a property of the deployment, not of any one connection.

Decision Outcome

Keep bedrock, bedrock-gov, azure-foundry, and azure-foundry-gov as distinct provider lanes.

Bedrock metadata still requires region for SigV4, but Nexus no longer classifies the value into commercial, GovCloud, or isolated partitions. Both Bedrock lanes accept any non-empty region without URL delimiters or control characters. Without a connection base_url, the default origin remains https://bedrock-runtime.{region}.amazonaws.com.

Foundry metadata keeps resource and api_version. resource, deployment names, and an optional domain override are checked for URL delimiters and control characters rather than against a public-cloud naming allowlist. deployments may be absent and is then treated as empty.

A lane declares its own upstream

Bedrock and Foundry resolve their origin in three steps: the connection base_url override, then the lane default from the imported artifact’s catalog[].base_url, then their composed host. Foundry’s composed host is https://{resource}.{domain} when metadata supplies domain, and the provider lane’s standard suffix otherwise (openai.azure.com or openai.azure.us).

Wanting the same backend at a second host is a second lane, not an override: an artifact whose name mints the lane and whose provider selects the adapter. That is why no host-composition metadata (endpoint_prefix, domain for Bedrock, a fips flag) exists — a flag switching between two compiled-in hostnames is a value allowlist of size two, which is the class of restriction this decision removes.

Because every catalog row requires a non-empty base_url, “no lane default” needs a spelling: https://unused.invalid, the placeholder the generators write for a field a lane does not use. The adapters treat it, and any blank value, as unset, so a catalog full of the placeholder needs no migration.

The connection base_url column stays, because scoped connections express something lanes cannot — one org behind its own egress proxy, or a loopback origin for offline checks. It silently outranks the catalog, so the CLI reports the difference when it takes effect.

Egress trust is deployment configuration

Provider requests trust only the roots compiled into the binary and never read the operating system trust store, so a private certificate authority or a TLS-inspecting proxy cannot be satisfied by connection configuration. Trust comes from NEXUS_GATEWAY_UPSTREAM_CA_BUNDLE_PATH, a list of PEM files and directories loaded fail-closed: an unreadable, unparseable, or certificate-free entry aborts startup rather than falling back to the default roots. NEXUS_GATEWAY_UPSTREAM_INSECURE_TLS disables verification for bring-up only and warns on every start.

NEXUS_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_SECS bounds establishing a connection so a blackholed route fails instead of hanging. It is deliberately a connect timeout rather than a total request timeout, which would truncate long streaming responses. Unlike the CA bundle it parses leniently: an unusable value warns and leaves the timeout unset, because a malformed bound is not a reason to refuse to serve, while a trust store that cannot be read is.

Scheme policy is still not configurable: HTTPS remains required outside loopback, and the escape hatch for private PKI is trust configuration rather than plaintext.

Consequences

• Operators may use custom or isolated region labels, deployment names, DNS suffixes, and HTTPS origins.
• Attaching the correct credential to a region and origin is an operator responsibility.
• Catalog, pricing, credentials, and import histories remain independently updateable per provider lane.
• HTTPS remains required outside loopback; this decision adds no scheme-policy configuration.
• An imported artifact is a credential-egress destination. A lane’s catalog[].base_url names the host the connection’s decrypted key is sent to, so artifact import — already signature-verified and approval-gated — is the control that governs where credentials travel. The origin parser rejects embedded credentials, paths, queries, and fragments, but does not restrict which host an operator may name.
• Rotating a CA bundle takes effect on Console and gateway restart; the bundle is read once when the shared client is built rather than per request.

See Azure AI Foundry Connections and AWS Bedrock Connections for the operator-facing connection setup.