Permalink
Fetching contributors…
Cannot retrieve contributors at this time
273 lines (261 sloc) 16.1 KB
---
name: gorouter
description: "Gorouter maintains a dynamic routing table based on updates received from NATS and (when enabled) the Routing API. This routing table maps URLs to backends. The router finds the URL in the routing table that most closely matches the host header of the request and load balances across the associated backends."
templates:
pre-start.erb: bin/pre-start
post-start.erb: bin/post-start
dns_health_check.erb: bin/dns_health_check
publish_to_nats.erb: bin/publish_to_nats
gorouter.yml.erb: config/gorouter.yml
drain: bin/drain
uaa_ca.crt.erb: config/certs/uaa/ca.crt
bpm.yml.erb: config/bpm.yml
bpm-pre-start.erb: bin/bpm-pre-start
packages:
- routing_utils
- gorouter
provides:
- name: gorouter
type: http-router
consumes:
- name: nats
type: nats
optional: true
properties:
router.port:
description: "Listening Port for Router."
default: 80
router.status.port:
description: "Port for the /health, /varz, and /routes endpoints."
default: 8080
router.status.user:
description: "Username for HTTP basic auth to the /varz and /routes endpoints."
default: router-status
router.status.password:
description: "Password for HTTP basic auth to the /varz and /routes endpoints."
router.requested_route_registration_interval_in_seconds:
description: |
On startup, the router will delay listening for requests by this duration to increase likelihood that it has a complete routing table before serving requests.
The router also broadcasts the same duration as a recommended interval to registering clients via NATS.
This must be less than 60, otherwise monit will mark the process as failed.
default: 20
router.load_balancer_healthy_threshold:
description: "Time period in seconds to wait until declaring the router instance started after starting the listener socket. This allows an external load balancer time to register the instance as healthy."
default: 20
router.balancing_algorithm:
description: "Algorithm used to distribute requests for a route across backends. Supported values are round-robin and least-connection"
default: round-robin
router.number_of_cpus:
description: "Number of CPUs to utilize, the default (-1) will equal the number of available CPUs"
default: -1
router.debug_address:
description: "Endpoint for process profiling. For more info see https://github.com/cloudfoundry/debugserver"
default: "127.0.0.1:17002"
router.secure_cookies:
description: "Set secure flag on http cookies"
default: false
router.drain_wait:
description: |
Delay in seconds after shut down is initiated before server stops listening.
During this time the server will reject requests to the /health endpoint.
This accommodates requests forwarded by a load balancer until it considers the router unhealthy.
default: 20
router.healthcheck_user_agent:
description: DEPRECATED. Use /health endpoint on port specified by status.port. User-Agent for the health check agent (usually the Load Balancer).
example: "ELB-HealthChecker/1.0"
default: "HTTP-Monitor/1.1"
router.enable_ssl:
description: "When enabled, Gorouter will listen on port 443 and terminate TLS for requests received on this port."
default: false
router.client_cert_validation:
description: |
none - Gorouter will not request client certificates in TLS handshakes, and will ignore them if presented. Incompatible with `forwarded_client_cert: forward` or `sanitize_set`.
request - Gorouter will request client certificates in TLS handshakes, and will validate them when presented, but will not require them.
require - Gorouter will fail a TLS handshake if the client does not provide a certificate signed by a CA it trusts. Select this option if your load balancer terminates TLS and does not require client certificates, and the load balancer provides a compatible client certificate of its own to Gorouter in an independent TLS handshake. This option may also be selected for Isolation Segments when Gorouter is the first point of TLS termination. Many clients of CF platform APIs do not present client certificates in TLS handshakes, so the first point of TLS termination for requests to the system domain must not require them. This option has no effect on the HTTP listener; to disable HTTP support set `disable_http: true`.
default: request
router.disable_http:
description: Disables the http listener on port specified by router.port. This cannot be set to true if enable_ssl is false.
default: false
router.min_tls_version:
description: Minimum accepted version of TLS protocol. All versions above this will also be accepted. Valid values are TLSv1.0, TLSv1.1, and TLSv1.2.
default: TLSv1.2
router.dns_health_check_host:
description: "Host to ping for confirmation of DNS resolution, only used when Routing API is enabled"
default: "uaa.service.cf.internal"
router.tls_pem:
description: "Array of private keys and certificates used for TLS handshakes with downstream clients. Each element in the array is an object containing fields 'private_key' and 'cert_chain', each of which supports a PEM block. Required if router.enable_ssl is true."
example: |
- cert_chain: |
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
router.ca_certs:
description: "String of concatenated certificate authorities in PEM format, used to validate certificates provided by remote systems. By default, Gorouter will trust certificates signed by well-known CAs and by CA certificates installed on the filesystem."
router.backends.cert_chain:
description: Certificate chain used for client authentication to TLS-registered backends. In PEM format.
router.backends.private_key:
description: Private key used for client authentication to TLS-registered backends. In PEM format.
router.ssl_skip_validation:
description: "Skip validation of TLS certificates received from route services and UAA. Warning: If this is set to true Gorouter will not validate the backend identity which could result in misrouting. For more information see https://docs.cloudfoundry.org/concepts/http-routing.html#consistency"
default: false
router.cipher_suites:
description:
An ordered, colon-delimited list of golang supported TLS cipher suites in OpenSSL or RFC format.
The selected cipher suite will be negotiated according to the order of this list during a TLS handshake.
See https://github.com/golang/go/blob/release-branch.go1.9/src/crypto/tls/cipher_suites.go#L369-L390 for golang supported cipher suites.
The first four of these are supported for TLSv1.0/1.1 only.
See https://www.openssl.org/docs/man1.1.0/apps/ciphers.html for a mapping of OpenSSL and RFC suite names.
default: "ECDHE-RSA-AES128-GCM-SHA256:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
router.forwarded_client_cert:
description: |
How to handle the x-forwarded-client-cert (XFCC) HTTP header. Possible values are:
- always_forward: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
Use this value when your load balancer is forwarding the client certificate and requests are not forwarded to Gorouter over mTLS. In the case where the connection between load balancer and Gorouter is mTLS, the client certificate received by Gorouter in the TLS handshake will not be forwarded.
- forward: Forward the XFCC header received from the client only when the client connection is mTLS.
This is a more secure version of `always_forward`. The client certificate received by Gorouter in the TLS handshake will not be forwarded.
Requires `client_cert_validation: request` or `require`.
- sanitize_set: Strip any instances of XFCC headers from the client request.
When the client connection is mTLS, the client certificate received by Gorouter in the TLS handshake will be forwarded in this header.
Values will be base64 encoded PEM. Use this value when Gorouter is the first component to terminate TLS.
Requires `client_cert_validation: request` or `require`.
default: always_forward
router.route_services_secret:
description: "Support for route services is disabled when no value is configured. A robust passphrase is recommended."
default: ""
router.route_services_secret_decrypt_only:
description: "To rotate keys, add your new key here and deploy. Then swap this key with the value of route_services_secret and deploy again."
default: ""
router.route_services_recommend_https:
description: "Route Services are told where to send requests after processing using the X-CF-Forwarded-Url header. When this property is true, the scheme for this URL is https. When false, the scheme is http. As requests from Route Services to applications on CF transit load balancers and gorouter, disable this property for deployments that have TLS termination disabled."
default: true
router.route_services_timeout:
description: "Expiry time of a route service signature in seconds"
default: 60
router.extra_headers_to_log:
description: "An array of headers that access log events will be annotated with"
default: []
router.logging_level:
description: "Log level for router"
default: "info"
router.enable_proxy:
description: "Enables support for the popular PROXY protocol, allowing downstream load balancers that do not support HTTP to pass along client information."
default: false
router.max_idle_connections:
default: 0
description: "Maximum total idle keepalive connections to backends. When 0, support for keepalive connections is disabled. Maximum idle connections per backend is 100."
router.force_forwarded_proto_https:
description: "Enables setting X-Forwarded-Proto header if SSL termination happened upstream and incorrectly set the header value. When this property is set to true gorouter sets the header X-Forwarded-Proto to https. When this value set to false, gorouter set the header X-Forwarded-Proto to the protocol of the incoming request"
default: false
router.sanitize_forwarded_proto:
description: |
When true, Gorouter will strip the X-Forwarded-Proto header when present in client request and set it to the scheme of the request.
When false, Gorouter will pass through the value of this header.
When force_forwarded_proto_https: true, this property will be ignored.
Otherwise, we recommend setting the property to true if Gorouter is the first component to terminate TLS, and set to false when your load balancer is terminating TLS and setting the X-Forwarded-Proto header.
default: false
router.frontend_idle_timeout:
description: |
(optional, integer) Duration in seconds to maintain an open connection when client supports keep-alive.
This property must be configured with regards to how an IaaS-provided load balancer behaves in order to prevent connections from being closed prematurely.
Generally, this timeout must be greater than that of the load balancer. As examples, GCP has a default timeout of 600 seconds so a value greater than 600 is recommended and AWS ELB has a default timeout of 60 seconds so a value greater than 60 is recommended.
However, depending on the IaaS, this timeout may need to be shorter than the load balancer's timeout, e.g., Azure's load balancer times out at 240 seconds (by default) without sending a TCP RST to clients, so a value lower than this is recommended in order to force it to send the TCP RST.
default: 900
router.backends.enable_tls:
description:
(optional, boolean) By default, Gorouter forwards requests to backends over unencrypted connections and will ignore routes registered with a TLS port,
preferring a non-tls port when both are present. When this property is set to true, Gorouter will connect to backends using TLS when routes are
registered with a TLS port, ignoring non-tls ports when both are present.
default: false
router.backends.max_conns:
description: "Maximum concurrent TCP connections per backend. When set to 0 there is no limit"
default: 0
router.tracing.enable_zipkin:
description: "Enables the addition of the X-B3-Trace-Id header to incoming requests. If the header already exists on the incoming request, it will not be overwritten."
default: false
router.isolation_segments:
description: "Routes with these isolation segments will be registered. Used in combination with routing_table_sharding_mode."
default: []
router.routing_table_sharding_mode:
description: |
all: all routes will be registered.
shared-and-segments: both routes for the configured isolation segments and those that do not have an isolation segment specified will be registered.
segments: only routes for the configured isolation segments will be registered.
default: all
router.disable_log_forwarded_for:
description: |
(optional, boolean) When false, gorouter will include the value of the HTTP header X-Forwarded-For which it sends to a backend.
When true, the value of this header will not be logged. This is to comply with EU regulations that do not allow persisting personal data.
default: false
router.disable_log_source_ip:
description: |
(optional, boolean) When false, gorouter will include the source IP in access logs. When true, the source IP will not be logged.
This is to comply with EU regulations that do not allow persisting personal data. When Gorouter is behind an L3 load balancer that
persists the IP of the originating client, set this to true to comply with GDPR.
default: false
nats.user:
description: User name for NATS authentication
example: nats
nats.password:
description: Password for NATS authentication
example: natSpa55w0rd
nats.port:
description: TCP port of NATS servers
example: 4222
nats.machines:
description: IPs of each NATS cluster member
example: |
- 192.168.50.123
- 192.168.52.123
router.offset:
description:
default: 0
router.trace_key:
description:
If the X-Vcap-Trace request header is set and has this value,
trace headers are added to the response.
default: 22
request_timeout_in_seconds:
description: "Timeout in seconds for Router -> Endpoint roundtrip."
default: 900
metron.port:
description: "The port used to emit dropsonde messages to the Metron agent."
default: 3457
uaa.clients.gorouter.secret:
description: "Password for UAA client for the gorouter."
uaa.token_endpoint:
description: "UAA token endpoint host name. Do not include a scheme in this value; TCP Router will always use TLS to connect to UAA."
default: uaa.service.cf.internal
uaa.ssl.port:
description: "Secure Port on which UAA is running."
routing_api.uri:
description: "URL where the routing API can be reached internally"
default: http://routing-api.service.cf.internal
routing_api.port:
description: "Port on which Routing API is running."
default: 3000
routing_api.auth_disabled:
description: "When false, Routing API requires OAuth tokens for authentication."
default: false
routing_api.enabled:
description: "When enabled, GoRouter will fetch HTTP routes from the Routing API in addition to routes obtained via NATS."
default: false
router.enable_access_log_streaming:
description: "Enables streaming of access log to syslog."
default: false
router.write_access_logs_locally:
description: "Enables writing access log to local disk."
default: true
router.suspend_pruning_if_nats_unavailable:
description: |
Suspend pruning of routes when NATs is unavailable and maintain the
current routing table. WARNING: This strategy favors availability over
consistency and there is a possibility of routing to an incorrect
endpoint in the case of port re-use. To be used with caution."
default: false
uaa.ca_cert:
description : "Certificate authority for communication between clients and uaa."
default: ""