Configuration reference
Every setting of the gateway host, its transports and the services, with its default. The gateway reads ASP.NET Core configuration; the services take their options in code. The option classes are in the .NET API reference: GatewayOptionsfor the gateway and StellaMicroserviceOptionsfor a service.
Forms
The gateway (the .NET tool or a custom host) reads, in increasing priority: appsettings.json, appsettings.<Environment>.json, environment variables, and command-line arguments. One setting in each form:
| Form | Example |
|---|---|
| JSON | { "Gateway": { "Routing": { "GlobalTimeoutCap": "10m" } } } |
| Environment variable | Gateway__Routing__GlobalTimeoutCap=10m (__ separates sections) |
| Command line | --Gateway:Routing:GlobalTimeoutCap=10m |
| List entry | Authentication__Schemes__Bearer__ValidIssuers__0=https://login.contoso.example/ |
The same settings in YAML, for a deployment tool that renders YAML into one of these forms:
Gateway:
Routing:
GlobalTimeoutCap: 10m
The gateway host (the .NET tool, or a host built with AddRouterGatewayHost) does not read YAML files itself. microservice.yaml is a separate file of the services (Microservice SDK).
Value formats
| Kind | Format | Examples |
|---|---|---|
Gateway durations (Gateway:Routing:*, Gateway:Health:*) | A number and ms, s, m or h, or a .NET time span | 500ms, 30s, 10m, 00:00:30 |
Transport durations (Gateway:Transports:Tcp|Tls|Udp|RabbitMq:*) | A .NET time span only | 00:00:10 |
Messaging durations (Gateway:Transports:Messaging:*) | A number and s, m, h or d, or a .NET time span; an invalid value falls back to the default | 30s, 5m, 1d |
Sizes (Gateway:Routing:MaxRequestBodySize) | A number and b, kb, mb or gb (1024-based); M alone is refused | 100MB, 512kb |
A bare number in a time-span field is a number of days: "30" is 30 days. Always write a unit.
Authentication (Authentication:Schemes:Bearer)
| Key | Default | Meaning |
|---|---|---|
Authority or MetadataAddress | none | The OpenID Connect provider. One of these or SigningKeys is required. |
SigningKeys | none | Symmetric keys (Issuer, base64 Value), for development and tests. |
ValidIssuer, ValidIssuers | none | Required. Accepted issuers. |
ValidAudience, ValidAudiences | none | Required. Accepted audiences. |
RequireHttpsMetadata | true | false allows an http provider address; development only. |
MapInboundClaims | false | Keep the token’s claim names (scope, scp, roles). |
Gateway (Gateway)
| Key | Default | Meaning |
|---|---|---|
Node:Region | local | The gateway’s region; it prefers instances in this region. |
Node:NeighborRegions | none | A list of regions the gateway prefers after its own and before the others (Several instances and regions). |
Node:NodeId | gw-<region>-<8 hex> | The gateway’s identifier. |
Node:Environment | dev | The environment name. |
Routing:DefaultTimeout | 30s | The timeout of endpoints that declare none. Endpoint classes and bridged endpoints always declare one, so it does not apply to them. |
Routing:GlobalTimeoutCap | 120s | The longest timeout any request gets. |
Routing:MaxRequestBodySize | 100MB | The request body limit: a larger body is answered 413. Kestrel’s body limit in the router gateway host follows it; over TCP, TLS, UDP and RabbitMQ the transport’s frame or message size also limits a body (Streaming). |
Routing:PreferLocalRegion | true | Prefer instances in Node:Region. |
Routing:AllowDegradedInstances | true | Route to degraded instances when no instance is healthy. |
Health:DegradedThreshold | 15s | Late heartbeat: the instance becomes degraded. At least twice the Messaging heartbeat (10s), so 20 seconds in effect. |
Health:StaleThreshold | 30s | Missing heartbeat: the instance becomes unhealthy and is not routed to. At least three Messaging heartbeats. |
Health:CheckInterval | 5s | How often the gateway checks heartbeats. |
Health:RequiredMicroservices | none | Service names that must be connected for /health/ready to answer 200. |
Health:ServiceNameSuffixes | none | Endings removed from service names before they are compared with RequiredMicroservices. |
OpenApi:* | enabled | The OpenAPI document (Schema validation and OpenAPI). |
Transports:<Name>:* | all disabled | The transports (below). |
TransportPlugins:ImageResidentAssemblies | none | More transport assemblies to load at start-up. |
Transports (Gateway:Transports)
Each transport starts only with Enabled set to true. Details and examples: Transports.
| Transport | Keys and defaults |
|---|---|
Tcp | BindAddress 0.0.0.0; Port 9100; ReceiveBufferSize, SendBufferSize 65536; MaxFrameSize 16777216 |
Tls | As TCP (Port 9443), plus ServerCertificatePath, ServerCertificateKeyPath, ServerCertificatePassword, RequireClientCertificate (false), AllowSelfSigned (false), CheckCertificateRevocation (false), EnabledProtocols (Tls12, Tls13), EnableCertificateHotReload (false), CertificatePinning:ThumbprintsSha256, AllowedSubjects, AllowedSans |
Udp | BindAddress 0.0.0.0; Port 5102; MaxDatagramSize 8192 |
RabbitMq | HostName localhost; Port 5672; VirtualHost /; UserName, Password guest; UseSsl (false); NodeId (required); ExchangePrefix stella.router; QueuePrefix stella; DurableQueues (false); AutoDeleteQueues (true); PrefetchCount 10; MaxMessageSize 16777216 (a larger request is answered 413, a larger response 502; keep it at or below the broker’s max_message_size) |
Messaging | valkey:ConnectionString localhost:6379; valkey:Database; RequestQueueTemplate router:requests:{service}; CancelControlQueueTemplate router:cancels:{service}:{connection}; ResponseQueueName router:responses; ConsumerGroup router-gateway; RequestTimeout; LeaseDuration 5m; BatchSize 10; MaxConcurrentRequests 10; HeartbeatInterval |
Router:Frame:Envelope:ActiveKeyId, Keys:<id> and ReplayWindow (a .NET time span, default 00:05:00) turn on frame protection for RabbitMQ and Messaging (Transports).
Rate limiting (rate_limiting)
| Key | Meaning |
|---|---|
process_back_pressure_when_more_than_per_5min | Check environment limits only above this many requests per 5 minutes; 0 always |
for_instance:rules[] | per_seconds, max_requests: per target service (and per stellaops:tenant claim), in each gateway process |
for_environment:valkey_connection, valkey_bucket | The Valkey server of the environment limits |
for_environment:circuit_breaker | failure_threshold (5 failed Valkey calls open the circuit), timeout_seconds (30: how long it stays open), half_open_timeout (10); each at least 1, or the gateway stops at start-up. While the circuit is open, environment limits are not checked. |
for_environment:rules[] | Environment rules |
for_environment:microservices:<service>:rules[], routes:<name> | Overrides (Rate limiting), counted per tenant for callers with a stellaops:tenant claim |
Licence monitor (StellaOps:ComponentLicence)
| Key | Default | Meaning |
|---|---|---|
Path | none | A licence file, or a directory of *.dsse.json files |
Key | none | The licence file as one line of base64; set it or Path, not both |
InstallationId | none | The installation identifier the licence record names |
Environment variables outside configuration
| Variable | Meaning |
|---|---|
STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS | true, yes or 1 allows the TCP and UDP transports in this process. Gateway and services. |
ASPNETCORE_ENVIRONMENT, DOTNET_ENVIRONMENT | The environment name; the in-memory harness runs only in Development, Testing or Local. |
ASPNETCORE_URLS | The gateway’s HTTP addresses, as --urls does. |
Services (code)
Service options are set in code and are not bound from configuration; read configuration values yourself, as the code on these pages reads Router:Host, Router:Port, Router:InstanceId and Router:Region.
| Options | Page |
|---|---|
StellaMicroserviceOptions (AddStellaMicroservice) | Microservice SDK: options |
StellaRouterBridgeOptions (AddStellaRouterBridge) | ASP.NET Core bridge: options |
Transport client options (Add<Name>TransportClient) | Transports |
[StellaEndpoint], [ValidateSchema], microservice.yaml | Microservice SDK, Schema validation |
Settings the gateway host refuses
Gateway:Auth, Gateway:Routes, Gateway:HttpsRedirect, Gateway:HttpClient, Gateway:TransportPlugins:AllowedSignerThumbprints, Gateway:TransportPlugins:RequireSignedManifest and Gateway:MessagingBackendPlugins are not used by the gateway host. The host stops at start-up and names each one present.
