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:

FormExample
JSON{ "Gateway": { "Routing": { "GlobalTimeoutCap": "10m" } } }
Environment variableGateway__Routing__GlobalTimeoutCap=10m (__ separates sections)
Command line--Gateway:Routing:GlobalTimeoutCap=10m
List entryAuthentication__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

KindFormatExamples
Gateway durations (Gateway:Routing:*, Gateway:Health:*)A number and ms, s, m or h, or a .NET time span500ms, 30s, 10m, 00:00:30
Transport durations (Gateway:Transports:Tcp|Tls|Udp|RabbitMq:*)A .NET time span only00: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 default30s, 5m, 1d
Sizes (Gateway:Routing:MaxRequestBodySize)A number and b, kb, mb or gb (1024-based); M alone is refused100MB, 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)

KeyDefaultMeaning
Authority or MetadataAddressnoneThe OpenID Connect provider. One of these or SigningKeys is required.
SigningKeysnoneSymmetric keys (Issuer, base64 Value), for development and tests.
ValidIssuer, ValidIssuersnoneRequired. Accepted issuers.
ValidAudience, ValidAudiencesnoneRequired. Accepted audiences.
RequireHttpsMetadatatruefalse allows an http provider address; development only.
MapInboundClaimsfalseKeep the token’s claim names (scope, scp, roles).

Gateway (Gateway)

KeyDefaultMeaning
Node:RegionlocalThe gateway’s region; it prefers instances in this region.
Node:NeighborRegionsnoneA list of regions the gateway prefers after its own and before the others (Several instances and regions).
Node:NodeIdgw-<region>-<8 hex>The gateway’s identifier.
Node:EnvironmentdevThe environment name.
Routing:DefaultTimeout30sThe timeout of endpoints that declare none. Endpoint classes and bridged endpoints always declare one, so it does not apply to them.
Routing:GlobalTimeoutCap120sThe longest timeout any request gets.
Routing:MaxRequestBodySize100MBThe 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:PreferLocalRegiontruePrefer instances in Node:Region.
Routing:AllowDegradedInstancestrueRoute to degraded instances when no instance is healthy.
Health:DegradedThreshold15sLate heartbeat: the instance becomes degraded. At least twice the Messaging heartbeat (10s), so 20 seconds in effect.
Health:StaleThreshold30sMissing heartbeat: the instance becomes unhealthy and is not routed to. At least three Messaging heartbeats.
Health:CheckInterval5sHow often the gateway checks heartbeats.
Health:RequiredMicroservicesnoneService names that must be connected for /health/ready to answer 200.
Health:ServiceNameSuffixesnoneEndings removed from service names before they are compared with RequiredMicroservices.
OpenApi:*enabledThe OpenAPI document (Schema validation and OpenAPI).
Transports:<Name>:*all disabledThe transports (below).
TransportPlugins:ImageResidentAssembliesnoneMore transport assemblies to load at start-up.

Transports (Gateway:Transports)

Each transport starts only with Enabled set to true. Details and examples: Transports.

TransportKeys and defaults
TcpBindAddress 0.0.0.0; Port 9100; ReceiveBufferSize, SendBufferSize 65536; MaxFrameSize 16777216
TlsAs TCP (Port 9443), plus ServerCertificatePath, ServerCertificateKeyPath, ServerCertificatePassword, RequireClientCertificate (false), AllowSelfSigned (false), CheckCertificateRevocation (false), EnabledProtocols (Tls12, Tls13), EnableCertificateHotReload (false), CertificatePinning:ThumbprintsSha256, AllowedSubjects, AllowedSans
UdpBindAddress 0.0.0.0; Port 5102; MaxDatagramSize 8192
RabbitMqHostName 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)
Messagingvalkey: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)

KeyMeaning
process_back_pressure_when_more_than_per_5minCheck 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_bucketThe Valkey server of the environment limits
for_environment:circuit_breakerfailure_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)

KeyDefaultMeaning
PathnoneA licence file, or a directory of *.dsse.json files
KeynoneThe licence file as one line of base64; set it or Path, not both
InstallationIdnoneThe installation identifier the licence record names

Environment variables outside configuration

VariableMeaning
STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTStrue, yes or 1 allows the TCP and UDP transports in this process. Gateway and services.
ASPNETCORE_ENVIRONMENT, DOTNET_ENVIRONMENTThe environment name; the in-memory harness runs only in Development, Testing or Local.
ASPNETCORE_URLSThe 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.

OptionsPage
StellaMicroserviceOptions (AddStellaMicroservice)Microservice SDK: options
StellaRouterBridgeOptions (AddStellaRouterBridge)ASP.NET Core bridge: options
Transport client options (Add<Name>TransportClient)Transports
[StellaEndpoint], [ValidateSchema], microservice.yamlMicroservice 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.