Skip to content

01-route-registrar-usage.md

Latest commit

 

History

History
156 lines (139 loc) · 6.21 KB

01-route-registrar-usage.md

File metadata and controls

156 lines (139 loc) · 6.21 KB
title Route-Registrar Usage
expires_at never
tags
routing-release
route-registrar

Route-Registrar Usage

Configuration

Route-registrar expects a configuration JSON file like the one below:

{
  "message_bus_servers": [
    {
      "host": "NATS_SERVER_HOST:PORT",
      "user": "NATS_SERVER_USERNAME",
      "password": "NATS_SERVER_PASSWORD"
    }
  ],
  "host": "HOSTNAME_OR_IP_OF_ROUTE_DESTINATION",
  "routes": [
    {
      "name": "SOME_ROUTE_NAME",
      "tls_port": "TLS_PORT_OF_ROUTE_DESTINATION",
      "tags": {
        "optional_tag_field": "some_tag_value",
        "another_tag_field": "some_other_value"
      },
      "uris": [
        "some_source_uri_for_the_router_to_map_to_the_destination",
        "some_other_source_uri_for_the_router_to_map_to_the_destination"
      ],
      "server_cert_domain_san": "some.service.internal",
      "route_service_url": "https://route-service.example.com",
      "registration_interval": "REGISTRATION_INTERVAL",
      "health_check": {
        "name": "HEALTH_CHECK_NAME",
        "script_path": "/path/to/check/executable",
        "timeout": "HEALTH_CHECK_TIMEOUT"
      },
      "terminate_frontend_tls": true,
      "enable_backend_tls": false,
      "alpns": [
        "alpn1",
        "alpn2"
      ],
      "options": {
        "loadbalancing": "least-connection"
      }
    }
  ]
}
  • message_bus_servers is an array of data with location and credentials for the NATS servers; route-registrar currently registers and deregisters routes via NATS messages. message_bus_servers.host must include both hostname and port; e.g. host: 10.0.32.11:4222
  • host is the destination hostname or IP for the routes being registered. To Gorouter, these are backends.
  • routes is required and is an array of hashes. For each route collection:
    • name must be provided and be a string
    • port or tls_port are for the destination host (backend). At least one must be provided and must be a positive integer > 1.
    • server_cert_domain_san is the SAN on the destination host's TLS certificate. Required when tls_port is provided.
    • uris are the routes being registered for the destination host. Must be provided and be a non empty array of strings. All URIs in a given route collection will be mapped to the same host and port.
    • registration_interval is the interval for which routes are registered with NATS. Must be provided and be a string with units (e.g. "20s"). It must parse to a positive time duration e.g. "-5s" is not permitted.
    • route_service_url is optional. When provided, Gorouter will proxy requests received for the uris above to this address.
    • health_check is optional and explained in more detail below.
    • sni_routable_san is the SAN used to route the request to the appropriate backend. Required when type is sni and terminate_frontend_tls is enabled.
    • sni_rewrite_san is the SAN used to override the SNI hostname sent to backend servers during TLS handshakes. Optional, but when provided, requires type to be sni and terminate_frontend_tls to be enabled. This allows backends to receive a different hostname than what the client provided.
    • terminate_frontend_tls is optional. When set to true, the router terminates TLS before forwarding requests to backend servers. Default: false
    • enable_backend_tls is optional. When set to true, the router initiates a TLS connection to backend servers. Default: false
    • alpns is optional and is an array of Application Layer Protocol Negotiation strings.
    • options is optional and explained in more detail below.

Run the route-registrar binary using the following command:

route-registrar -configPath FILE_PATH_TO_CONFIG_JSON -pidfile PATH_TO_PIDFILE

SNI Routing

Route-registrar can be used to configure SNI routing. This is an example route JSON:

{
  "routes": [
    {
      "type": "sni",
      "external_port": "TLS_PORT_OF_ROUTE_SOURCE",
      "name": "SOME_ROUTE_NAME",
      "sni_port": "TLS_PORT_OF_ROUTE_DESTINATION",
      "router_group": "SOME_ROUTER_GROUP",
      "registration_interval": "20s",
      "terminate_frontend_tls": true,
      "sni_routable_san": "routable.example.com",
      "sni_rewrite_san": "backend.internal.hostname"
    }
  ]
}

The sni_rewrite_san field is optional. When provided, it requires type to be sni and terminate_frontend_tls to be enabled. It allows you to specify a different SNI hostname to send to backend servers than the one received from the client. This is useful when backends require specific hostnames for certificate validation or routing purposes.

Health check

If the health_check is not configured for a route collection, the routes are continually registered according to the registration_interval.

If the health_check is configured, then, at the registration_interval, the executable provided at health_check.script_path is invoked. The following applies:

  • if the executable exits with success, the routes are registered.
  • if the executable exits with error, the routes are deregistered.
  • if health_check.timeout is configured, it must parse to a positive time duration (similar to registration_interval), and the executable must exit within the timeout. If the executable does not terminate within the timeout, it is forcibly terminated (with SIGKILL) and the routes are deregistered.
  • if health_check.timeout is not configured, the executable must exit within half the registration_interval. If the executable does not terminate within the timeout, it is forcibly terminated (with SIGKILL) and the routes are deregistered.

Options

Custom per-route options can be defined for specific routes.

  • loadbalancing selects the load balancing algorithm for routing incoming requests to backends. Choose between round-robin and least-connection. If not specified, the algorithm defined by the platform operator is used.