Gateway

Configuration

Config reference, YAML example, and options for Gateway

YAML Configuration Example

config.yaml
extensions:
  gateway:
    enabled: true
    basePath: ""

    timeouts:
      connect: "10s"
      read: "30s"
      write: "30s"
      idle: "90s"

    retry:
      enabled: true
      maxAttempts: 3
      initialDelay: "100ms"
      maxDelay: "5s"
      jitter: true

    circuitBreaker:
      enabled: true
      failureThreshold: 5
      failureWindow: "60s"
      resetTimeout: "30s"

    healthCheck:
      enabled: true
      interval: "10s"
      path: "/_/health"
      failureThreshold: 3
      successThreshold: 2

    loadBalancing:
      strategy: "round_robin"       # round_robin, weighted, random, least_connections, consistent_hash

    discovery:
      enabled: true
      pollInterval: "30s"
      watchMode: true
      autoPrefix: true
      prefixTemplate: "/{{.ServiceName}}"
      stripPrefix: true

    dashboard:
      enabled: true
      basePath: "/gateway"
      realtime: true

    openAPI:
      enabled: true
      path: "/gateway/openapi.json"
      uiPath: "/gateway/docs"

    routes:
      - path: "/api/users/*"
        target: "http://users-service:8080"
        methods: ["GET", "POST", "PUT", "DELETE"]
        stripPrefix: true

The extension loads config from extensions.gateway first, falling back to gateway.

Programmatic Configuration

ext := gateway.NewExtension(
    // Enable FARP discovery with watch mode.
    gateway.WithDiscoveryEnabled(true),
    gateway.WithDiscoveryWatchMode(true),
    gateway.WithDiscoveryAutoPrefix(true),
    gateway.WithDiscoveryStripPrefix(true),

    // Dashboard and load balancing.
    gateway.WithDashboard(gateway.DashboardConfig{Enabled: true}),
    gateway.WithLoadBalancing(gateway.LoadBalancingConfig{
        Strategy: gateway.LBRoundRobin,
    }),
    gateway.WithCircuitBreaker(gateway.CircuitBreakerConfig{
        Enabled:          true,
        FailureThreshold: 5,
        FailureWindow:    60 * time.Second,
        ResetTimeout:     30 * time.Second,
    }),
    gateway.WithHealthCheck(gateway.HealthCheckConfig{
        Enabled:  true,
        Interval: 10 * time.Second,
        Path:     "/_/health",
    }),
)

Key Config Sections

Timeouts

FieldDefaultDescription
Connect10sUpstream connection timeout
Read30sResponse read timeout
Write30sRequest write timeout
Idle90sIdle connection timeout

Retry

FieldDefaultDescription
EnabledtrueEnable retries
MaxAttempts3Maximum retry attempts
InitialDelay100msInitial backoff delay
MaxDelay5sMaximum backoff delay
JittertrueAdd random jitter

Circuit Breaker

FieldDefaultDescription
EnabledtrueEnable circuit breakers
FailureThreshold5Failures before opening
FailureWindow60sWindow for counting failures
ResetTimeout30sTime before half-open

Discovery

FieldDefaultDescription
EnabledtrueEnable FARP auto-discovery
PollInterval30sDiscovery poll interval
WatchModetrueWatch for service changes instead of polling
ServiceFilters[]Service filter rules (include/exclude by name, tags, metadata)
AutoPrefixtrueAuto-prefix routes with service name
PrefixTemplate"/{{.ServiceName}}"Route prefix template (Go text/template syntax)
StripPrefixtrueStrip prefix before forwarding to upstream

Service Filters

FieldDescription
IncludeNamesOnly include services matching these names (supports * wildcards)
ExcludeNamesExclude services matching these names (supports * wildcards)
IncludeTagsOnly include services that have all of these tags
ExcludeTagsExclude services that have any of these tags
RequireMetadataRequire specific key-value pairs in service metadata

Discovery Config Options

OptionDescription
WithDiscovery(cfg)Set the full discovery configuration
WithDiscoveryEnabled(bool)Enable or disable FARP discovery
WithDiscoveryPollInterval(d)Set the polling interval
WithDiscoveryWatchMode(bool)Use watch mode instead of polling
WithDiscoveryAutoPrefix(bool)Auto-generate path prefixes from service names
WithDiscoveryPrefixTemplate(tmpl)Set the prefix template
WithDiscoveryStripPrefix(bool)Strip prefix before proxying
WithDiscoveryServiceFilters(filters...)Set service filters

Dashboard

FieldDefaultDescription
EnabledtrueEnable admin dashboard
BasePath"/gateway"Dashboard URL base path
RealtimetrueEnable WebSocket updates

How is this guide?

On this page