Summary

Redirects specify how URLs may need to be rewritten. Each Redirect has a name, a regex that matches the requested URL, a to indicating how the url should be rewritten, and a flag to indicate how the redirect will be handled by the proxying layer.

Example object

Fields

name

Common name for this redirect, e.g. "force-https".

from

Regex pattern to match against incoming request URLs. Capture groups set here can be used in the field.

to

New URL of the redirect. Can be direct string (") or reference capture groups from the field ("").

redirect_type

One of "permanent" or "temporary". Selection "permanent" will set the response code to 301, "temporary" will be 302.

header_constraints

Array of that must match for the redirect to take effect.

Summary

Grey Matter supports the configuration of cross-origin resource sharing on a sidecar. CORS can be configured to allow an application to access resources at a different origin (domain, protocol, or port) than its own.

For more information on CORS, see this CORS reference.

Simple Requests

Simple requests are classified as requests that don't require a . This distinction is made between requests that might be dangerous (i.e. modifies server resources) and those that are most likely benign. A request is considered simple when all of the following criteria is true:

• The method is GET, HEAD, or POST

• Only are present

• The Content Type header is set to one of application/x-www-form-urlencoded

A more comprehensive list and explanation can be found .

As an example, say an app running at http://localhost:8080 is trying to call a backend service with a Grey Matter sidecar at http://localhost:10808. Without a CORS configuration, this request would fail, because the app localhost:8080 is trying to access resources from a server at a different origin, localhost:10808. To solve this, the following CORS config is set on its domain:

With this configuration, if a simple request comes in to the sidecar from the app, it will have an Origin header value of http://localhost:8080, and this request will succeed. The server will attach a header Access-Control-Allow-Origin: http://localhost:8080 to the response, which signals to the browser that this request is allowed.

Preflight Requests

are initiated by the browser using the OPTIONS HTTP method before sending a request in order to determine if the real request is safe to send. The response to this kind of request contains information about what is allowed from a request, and the server determines whether or not to send the actual request based on this information.

This response information is in the form of three HTTP headers, access-control-request-method, access-control-request-headers, and the origin header. These correspond to of the cors_config - thus these configurations can be specified to determine how the Grey Matter sidecar will respond to preflight requests. If a preflight request comes in to the Grey Matter Sidecar that does not meet the specification for one of these configured fields, the sidecar will send back a response to not initiate the request.

Based on the same , say the app running at http://localhost:8080 wants to send requests to the backend service at http://localhost:10808 with a content-type of application/json;charset=UTF-8. This particular content-type is outside of those allowed by CORS for simple requests, and thus would result in sending a preflight request to determine if the request can be sent. In order for the CORS configuration to indicate that the request can be sent, it would need to allow the content-type header by configuring the field:

In the above configuration, CORS will allow requests with Origin header value http://localhost:8080 only and indicate that the content-type header can be set according to the request.

Configuration

To set up CORS, set the cors_config field on a domain object with the desired configuration, see the below.

For an existing domain, run

and add the desired cors_config object.

Example object

Fields

allowed_origins

This field specifies an array of string patterns that match allowed origins. The proxy will use these matchers to set the header. This header will be set on any cross-origin response that matches one of the allowed_origins.

Available matchers include:

• exact

• prefix

• suffix

Example:

A wildcard value * is allowed except when using the regex matcher.

allow_credentials

Specifies the content for the header that the proxy will set on any cross-origin request that matches one of the allowed_origins. This header specifies whether or not the upstream service allows credentials.

exposed_headers

Specifies the content for the header that the proxy will set on any cross-origin request that matches one of the allowed_origins. This header specifies an array of headers that are allowed on the response.

max_age

Specifies the content for the header that the proxy will set on the preflight response. This header is an integer value specifying how long a preflight request can be cached by the browser.

allowed_methods

Specifies the content for the header that the proxy will set on the preflight response. This header specifies an array of methods allowed by the upstream service.

allowed_headers

Specifies the content for the header that the proxy will set on the preflight response. This header specifies an array of headers allowed by the upstream service.

Notes

• By default, the proxy will use the upstream service's CORS policy on the gateway and on the upstream service. The gateway policy is ignored.

• Because CORS is a browser construct, curl can always make a request to the server, with or without CORS. However, it can be used to mimic a browser and verify how the proxy will react to CORS requests:

Summary

Example object

Fields

cipher_filter

. If specified, only the listed ciphers will be accepted. Only valid with TLSv1-TLSv1.2, but has no affect with TLSv1.3.

Examples include the values below, but full options should be found in the link above.

• [ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]

• [ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]

• ECDHE-ECDSA-AES128-SHA

• ECDHE-RSA-AES128-SHA

protocols

Array of SSL protocols to accept: "TLSv1, TLSv1.1, TLSv1.2, TLSv1.3"

cert_key_pairs

Array of (cert, key) pairs to use when receiving requests on this . Each cert or key must point to files on disk.

require_client_certs

If true, client cert verification will be performed. false will disable this check and not require client certificates to be presented when connecting to this listener.

trust_file

String representing the path on disk to the SSL trust file to use when receiving requests on this . If omitted, then no trust verification will be performed.

sni

String representing how this listener will identify itself during SSL SNI.

Summary

Each domain controls requests for a specific host:port. This permits different handling of requests to domains like localhost:8080 or catalog:8080 if desired. If uniform handling is required, wildcards are understood to apply to all domains. A domain set to match *:8080 will match both of the above domains.

NOTEThe domain port should, in most cases, match the port of the exposed on the proxy. If they do not match, users will need to supply HOST: header keywords to all requests to match the virtual domain.

Features

• Virtual host:port matching and redirecting

• GZIP of requests

• CORS

• Setting custom headers for downstream requests

Example Object

TLS Configuration

NOTE Do not set an ssl_config on any domain object whose service you want to use SPIFFE/SPIRE. If a domain ssl_config is set, it will override the secret set on the corresponding listener and the mesh configuration will be wrong.

The domain object has an optional ssl_config field, which can be used to set up TLS and specify it's configuration. The Domain SSL Config Object appears as follows:

The Domain SSL Configuration is used to populate a for the Envoy Listener.

The sni field for a domain accepts a list of strings and configures the Envoy Listener to detect the requested Server Name Indication.

To specify a minimum and maximum TLS protocol version, set the protocols field to one of the following: "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3". If one protocol is specified, it will be set as both the minimum and maximum protocol versions in Envoy. If more than one protocol version is specified in the list, the lowest will set the minimum TLS protocol version and the highest will set the maximum TLS protocol version. If this field is left empty, Envoy will choose the default TLS version.

The cipher_filter field takes a colon : delimited string to populate the cipher_suites cipher list in envoy for TLS.

redirects

This field can be used to configure redirect routes for the domain. See for details.

Fields:

• name

  • the name of the redirect

• from

Envoy Reference

Fields

domain_key

A unique key used to identify this particular domain configuration. This key is used in proxy, listener, and route objects.

zone_key

The zone in which this object will live. It will only be able to be referenced by objects or sent to Sidecars that live in the same zone.

name

The name of this virtual domain, e.g. localhost, www.greymatter.io, or catalog.svc.local. Only requests coming in to the named host will be matched and handled by attached . Is used in conjunction with the field.

This field can be set to a wildcard (*) which will match against all hostnames.

port

Set the specific port of the virtual host to match. Is used in conjunction with the field.

E.g. port: 8080 and name: * will setup a virtual domain matching any request made to port 8080 regardless of the host.

ssl_config

for this cluster. Setting the SSL Config at the domain level set this same config on all that are directly linked to this domain.

redirects

Array of URL

gzip_enabled

DEPRECATION: This field has been deprecated and will be removed in the next major version release.

This field has no effect.

cors_config

A to attach to this domain.

aliases

An array of additional hostnames that should be matched in this domain. E.g. name: "www.greymatter.io" with aliases: ["greymatter.io", "localhost"]

force_https

If true, listeners attached to this domain will only accept HTTPS connections. In this case, one of the or fields should be set. If false, attached listeners will only accept plaintext HTTP connections.

custom_headers

An array of header key, value pairs to set on all requests that pass through this domain.

E.g.

checksum

An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.

Summary

Example object

Fields

name

Header key to match on. Supports regex expressions.

value

Header value to match on. Supports regex expressions.

case_sensitive

If true, then the regex matching will be case sensitive. Defaults to false.

invert

If true, invert the regex match. This allows easier "not" expressions.

For example, to match only X-Forwarded-Proto: "http":

But to match anything NOT "https":