Configuration file

The gateway reads a single YAML file, given with --gConfigPath (or GATEWAY_CONFIG_PATH). Keys are case sensitive and unknown keys are rejected, so a typo is reported instead of silently ignored. Run nocleye check to validate a file.

Structure

ApiVersion: v1Beta        # required

AuthMethods: {}           # how tokens are validated (optional)

Rules:                    # reusable rules, defined once, referenced by name
  HeaderRules: {}
  ClientIDRules: {}
  UsageControlRules: {}

GlobalConfig: {}          # default rules for every server and route (optional)

ServerConfigs: {}         # backend services (at least one required)

ServerRoutes: {}          # public paths mapped to servers (at least one required)

Key	Required	Description
ApiVersion	yes	Version of the config format. The only supported value is v1Beta.
AuthMethods	no	Named authentication methods. See Authentication.
Rules	no	Named, reusable rules. See header rules, client ID rules and usage control.
GlobalConfig	no	Rules and authentication applied to everything by default.
ServerConfigs	yes	Backend services, by name. See Servers and routes.
ServerRoutes	yes	Routes, by name. See Servers and routes.

Referencing rules

A rule is defined once under Rules and then referenced by its name. GlobalConfig, every server and every route accept the same set of keys:

Key	Value	Description
HeaderRule	rule name	Header rule to use.
ClientIDRule	rule name	Client ID rule to use.
UsageControlRules	list of rule names	Usage control rules to apply. Several can be bound at once.
AuthMethod	method name	Authentication method to use.

Servers and routes also accept UsageControlMode (see usage control mode).

Referring to a name that does not exist is an error.

Which scope is used

What	Resolution
HeaderRule, ClientIDRule, AuthMethod	The closest scope wins: the route’s value, otherwise the server’s, otherwise GlobalConfig’s. Only one is used.
UsageControlRules	Rules from several scopes can apply at once. See Usage control.

When no header rule applies, all request headers are forwarded. When no client ID rule applies, callers are identified by IP.

Complete example

gateway.yaml

ApiVersion: v1Beta

AuthMethods:
  secure-hs256-bearer:
    Mode: Bearer
    SigningMethod: HS256
    KeyRef: "file:/etc/gateway/keys/hs256.key"
    IdClaimName: sub
    RefuseOnMissing: true
    RefuseOnExpired: true
  secure-hs512-raw:
    Mode: RawHeader
    SigningMethod: HS512
    HeaderName: X-Auth-Token
    KeyRef: "env:HS512_SECRET"
    IdClaimName: sub
    RefuseOnMissing: true
    RefuseOnExpired: true

Rules:
  HeaderRules:
    allowlist-headers:
      Mode: Custom
      CustomHeadersList: [X-Request-Id, X-Trace-Id]
    strip-and-set:
      Mode: All
      Remove: [X-Internal]
      Set:
        X-Source: gateway
    preserve-host:
      Mode: All
      PreserveHost: true

  ClientIDRules:
    client-id-header:
      Modes: [CustomHeader]
      HeaderCustomValue: "X-Customer-Id"
    token-or-ip:
      Modes: [BearerToken, IP]

  UsageControlRules:
    global-limit:
      RequestCount: 1000
      WindowTime: 1m
    limit-a-low:
      RequestCount: 20
      WindowTime: 1m
    limit-b-server:
      RequestCount: 50
      WindowTime: 1m
    limit-b-route:
      RequestCount: 10
      WindowTime: 1m

GlobalConfig:
  UsageControlRules: [global-limit]

ServerConfigs:
  svc-a:
    URL: "http://svc-a:9090"
  svc-b:
    URL: "https://svc-b:9090"
    TLS:
      CACertFile: "/etc/gateway/certs/ca.pem"
    UsageControlRules: [limit-b-server]

ServerRoutes:
  a-open:
    TargetServer: svc-a
    PathPattern: /a/open
    RemovePathPatternFromFinalRoute: true
    HeaderRule: allowlist-headers

  b-open:
    TargetServer: svc-b
    PathPattern: /b/open
    RemovePathPatternFromFinalRoute: true
    HeaderRule: strip-and-set

  a-limited:
    TargetServer: svc-a
    PathPattern: /a/limited
    RemovePathPatternFromFinalRoute: true
    UsageControlRules: [limit-a-low]

  b-limited:
    TargetServer: svc-b
    PathPattern: /b/limited
    RemovePathPatternFromFinalRoute: true
    UsageControlRules: [limit-b-route]

  a-secure:
    TargetServer: svc-a
    PathPattern: /a/secure
    RemovePathPatternFromFinalRoute: true
    AuthMethod: secure-hs256-bearer

  b-secure:
    TargetServer: svc-b
    PathPattern: /b/secure
    RemovePathPatternFromFinalRoute: true
    AuthMethod: secure-hs512-raw

  a-clients:
    TargetServer: svc-a
    PathPattern: /a/clients
    RemovePathPatternFromFinalRoute: true
    ClientIDRule: client-id-header

  a-rewrite:
    TargetServer: svc-a
    PathPattern: /a/rewrite
    RemovePathPatternFromFinalRoute: true
    AddPrefixToFinalRoute: /rewritten
    HeaderRule: preserve-host

With this file:

• A request to /a/open/status/500 reaches svc-a as /status/500 with only X-Request-Id and X-Trace-Id (plus the headers the gateway always keeps) forwarded.
• /b/limited is limited by global-limit, limit-b-server and limit-b-route together.
• /a/secure requires a valid bearer token signed with the HS256 key.