HTTP
For a list of available HTTP filters, see HTTP Filters table.
Configuration Overview
HTTP filters may be configured in Grey Matter Control API in one of two configuration object types: Listener and Proxy.
When configured in a Listener object, the HTTP filter will be enabled only for that listener and not any other listener registered to the same Grey Matter Proxy. On the other hand, when configured in a Proxy object, the HTTP filter will be enabled for all registered listeners in a Grey Matter Proxy.
Listener Configuration Preferred
Note that the Fabric mesh's control plane gives higher priority to HTTP filter configurations in a Listener object versus its related Proxy object.
In fact, HTTP filter configurations added to a Proxy object will only be applied if there are no HTTP filters and no Network filter configurations added to a Listener object. If filters of either type are configured in a Listener object, any filter configurations in its related Proxy object will be ignored.
In a future version of the Fabric mesh, support for configuring HTTP filters in a Proxy object will likely be deprecated.
Example Configurations
Listener
To edit the Listener object, run:
greymatter edit listener <listener-key>The following is an example of configuring an HTTP filter in a Listener object by specifying values in two of its fields -- the active_http_filters field and the http_filters field:
{
"zone_key": "default-zone",
"listener_key": "listener1",
"name": "listener1",
"domain_keys": [
"domain1"
],
"ip": "0.0.0.0",
"port": 8080,
"protocol": "http_auto",
"active_http_filters": [
"gm.inheaders",
"envoy.ip_tagging"
],
"http_filters": {
"gm_inheaders": {
"debug": true
},
"envoy_ip_tagging": {
"request_type": 0,
"ip_tags": [
{
"ip_tag_name": "my-tag",
"ip_list": [
{
"address_prefix": "0.0.0.0",
"prefix_len": {
"value": 32
}
}
]
}
]
}
}
}This configuration tells the corresponding Grey Matter Proxy to register and use the gm.inheaders filter for its listener1 Listener only. This allows for configuring unique filter types on a per-Listener basis within a single instance of Grey Matter Proxy.
Again, note that the keys in the active_http_filters array use a period following their prefix, while the http_filters object uses underscores all the way through.
Proxy
To edit the Listener object, run:
greymatter edit proxy <proxy-key>The following is an example of configuring a filter in a Proxy object by specifying values in two of its fields -- the active_proxy_filters field and the proxy_filters field:
{
"zone_key": "default-zone",
"proxy_key": "sidecar-proxy",
"name": "sidecar",
"domain_keys": [
"domain1",
"domain2"
],
"listener_keys": [
"listener1",
"listener2"
],
"active_proxy_filters": [
"gm.inheaders",
"envoy.ip_tagging"
],
"proxy_filters": {
"gm_inheaders": {
"debug": true
},
"envoy_ip_tagging": {
"request_type": 0,
"ip_tags": [
{
"ip_tag_name": "my-tag",
"ip_list": [
{
"address_prefix": "0.0.0.0",
"prefix_len": {
"value": 32
}
}
]
}
]
}
}
}The configuration tells the corresponding Grey Matter Proxy to enable the gm.inheaders and envoy.ip_tagging filters for all its registered listeners (i.e. listener1 and listener2, according to the listener_keys field).
Note that the keys in the active_proxy_filters array use a period following their prefix, while the proxy_filters object uses underscores all the way through.
Known Ordering Dependencies
NOTES:
Well Known Dynamic Metadata: Filters can emit dynamic metadata via the setDynamicMetadata routine in the StreamInfo interface on a Connection. This metadata emitted by a filter can be consumed by other filters and useful features can be built by stacking such filters. For example, a logging filter can consume dynamic metadata from an RBAC filter to log details about runtime shadow rule behavior. Another example is where an RBAC filter permits/restricts MySQL/MongoDB operations by looking at the operational metadata emitted by the MongoDB filter.
HTTP Filters
To learn how to enable any of the Envoy HTTP filters in the Fabric mesh, refer to the HTTP Filters configuration overview.
The following table lists all Grey Matter and Envoy HTTP filters that may be configured. Some general information on each filter is available; otherwise please refer to the Envoy documentation. Also, some Envoy filters have been excluded due to being marked by Envoy as experimental.
Note that the Active Filter Name is a simplified form of the name used in Grey Matter Proxy (e.g. envoy.header_to_metadata is used in place of envoy.filters.http.header_to_metadata).
Available Filter Summary
Filter
Active Filter Name
Guide
Envoy documentation
Detailed Filter Description
Observables
The Observables Filter configures the Proxy to emit a JSON payload with every request made to the microservice. This JSON payload contains a variety of different information about the request being made, as well as the user/system issuing the request. These Observables can then be aggregated to perform analysis like: audits, user-experience tracking, etc.
Observable publishing defaults to stdout but can also be published to a Kafka topic or location on disk.
Impersonation
The ACL Impersonation Filter gives whitelist server distinguished names (DNs) the privilege to impersonate on behalf of users.
Inheaders
This filter sets up HTTP request headers on all incoming traffic for purposes of security and audits throughout the mesh. Set headers are:
USER_DN
EXTERNAL_SYS_DN
SSL_CLIENT_S_DN
NOTE This filter is primarily intended to be used only on Edge nodes. These nodes are ingress points which require header normalization before propagating the requests throughout the mesh. Turning this filter on at other points may result in extra latency and unintended behavior, and is thus discouraged.
ListAuth
This filter restricts access to the proxied microservice based on the user's Distinguished Name (DN). The whitelist will allow given DNs, and the blacklist will forbid given DNs. The behavior of each list is slightly different:
whitelist allows all by default, but then allows only the specified DNs if given a non-default string.
blacklist denies none, but then denies only the specified DNs when given a non-default string.
NOTE The users DN comes from the USER_DN host header. These headers must be supplied by the user, or can set by the gm.inheaders filter somewhere up the connection stream.
Metrics gm.metrics
gm.metricsThis filter sets up a local metrics server to gather and report real-time statistics for the sidecar, microservice, and host system.
Optionally, this filter can serve the computed statistics in a form suitable for scraping by Prometheus. The prometheus endpoint will be hosted at {METRICS_HOST}:{METRICS_PORT}{METRICS_PROMETHEUS_URI_PATH}, which can then be scraped directly through the supported Prometheus service discovery mechanisms.
The metrics filter can also push the compiled statistics directly to AWS Cloudwatch. This allows the Grey Matter Proxy metrics to be directly used to trigger things like AutoScale actions or just for tighter monitoring directly in AWS.
OAuth gm.oauth
gm.oauthGrey Matter’s sidecar proxy supports full OAuth 2.0 negotiation.
JWT Security
On incoming requests, the gm-jwt-security filter creates a jwt token from the gm-jwt-security service "/policies" endpoint using the incoming USER_DN. It passes the token along with the request in a jwt header.
Ensure Variables
This filter enforces certain attributes of a request like a header, cookie, or query string and optionally moves it to another location. The filter can be configured to reject the request completely if one of these variables is not present. This is meant to act as a normalization filter that makes it easier for downstream filters to find and use variables.
OIDC Authentication
Authentication filter has all the information needed to initiate an authentication handshake with an OpenID Connect provider. It begins by checking whether a request contains an access token in a specified location (header, query string, or cookie). If it exists, it assumes that the token was verified at least once by previous filters in the chain and passes the request onto the next filter. If an access token was not found, it will check for the query token to see if there is an access code. This happens when a request is coming back from the identity provider (specified by callback URL). If the code is found, it will exchange it for a bearer token and an id token - both of them will then be stored in specified locations. If no access code was found, the authentication process gets kicked off by forwarding the user to the identity provider.
OIDC Validation
The oidc-validation filter handles bearer token (aka access token) validation. It can be configured to check for bearer tokens in headers, cookies, or query parameters. If it finds a token, it validates the token with the provided IdP and sets the desired user attributes into a configurable header. If the token is invalid, it strips it from the request so that it can be dealt with upstream. If enforce is set to true, the request will be rejected with a 403 (configurable).
Buffer
Delays iterating through the filter chain to wait for a fully buffered request.
CSRF
Prevents Cross-Site Request Forgery based on a route or virtual host settings.
External Authorization
Integrates with an external gRPC or HTTP service for checking whether an incoming HTTP request is authorized or not. If unauthorized, the request will be denied with a 403 Forbidden response.
JWT Authentication
Verifies JSON Web Tokens and permits forwarding of the payload to additional filters or services.
Fault Injection
Enables the injection of delays and abort requests with custom error codes in order to simulate various failure scenarios (e.g. service failures, overloads, high network latency, network partitions, etc). It can be configured for a given upstream cluster of a request and/or a set of predefined request headers.
gRPC-JSON Transcoder
Transcodes incoming HTTP requests into protobuf and proxies them to a gRPC service. This require creating an HTTP mapping for the gRPC service and providing Grey Matter Proxy with the proto descriptor of the gRPC service. gRPC responses returned to the JSON API client are encoded into JSON.
Gzip
Enables compressing dispatched data from an upstream service, given specific request headers.
Header-to-Metadata
Instructs Grey Matter Proxy to record and emit dynamic metadata based on request headers that match some configured rule, which can then be used further down in the filter chain for operations like defining load balancing behaviors.
Health Check
Supports active health checking configuration by defining distinct modes of operation (e.g. Whether to pass health check requests to an underlying service, whether to cache health check results for a certain period of time).
IP Tagging
Sets the header x-envoy-ip-tags with the string tags for the trusted address from x-forwarded-for. This provides a scalable way to compare an IP address to a large list of CIDR ranges effectively.
Lua
Injects a Lua script in-line to be run during request and response flows. A Lua script can inspect and modify headers, body, and trailers. Note that blocking operations should not be run from a Lua script here.
Rate Limit
Integrates with a global gRPC rate limiting service such as Lyft's reference implementation to control throughput throughout the Fabric mesh by preventing downstream hosts from overwhelming upstream clusters.
Unlike the Network Rate Limit filter, rate limit configurations must be specified at the route level.
Role Based Access Control
Allows or denies actions (permissions) by identified downstream clients (principals). It supports configuration using either a safe-list (ALLOW) or block-list (DENY) set of policies based on properties of the connection (IPs, ports, SSL subject) as well as the incoming request's HTTP headers.
For a more in-depth guide on configuring RBAC, see rbac.md.
Squash
Enables Envoy to integrate with Solo.io's Squash microservices debugger.
Last updated
Was this helpful?