Configure Sidecar Filters

This guide will help you enable and disable Grey Matter Sidecar filters.

This guide will walk through how to enable and configure filters on the Grey Matter sidecar. To see the many filter options, check out the filters documentation.

Filters can be set on any service that is configured in the mesh. This guide will be an overview of the general steps to enabling a filter, and will use the Grey Matter Observables filter on the Grey Matter SLO service as an example. There are several existing guides for configuring and setting specific filters - fault injection, rate limiting, and the OIDC filter chain.

The Grey Matter Sidecar's functionality allows for deep request and response lifecycle observability in your network. We've extended Envoy's filters with in-house Go libraries.

Prerequisites

  1. An existing Grey Matter deployment running on Kubernetes (tutorial)

  2. kubectl or oc setup with access to the cluster

  3. greymatter cli setup with access to the deployment

Steps

Overview

There are two options for setting filters on a Grey Matter sidecar. They can either be set on a listener object for your service, or on its proxy object. Setting the filters at the listener level is recommended as it allows for more clear and specific granularity to the behavior of the filters. We will set at the listener level in this guide. Applying filters to the proxy object for a sidecar will enable the filter for every listener attached to it.

Filters can be set at either the HTTP or the network level. This guide will walk through setting an HTTP filter.

1. Generate filter configuration

To generate the configuration for a filter, get its active filter name from the list of available filters.

Note: For enabling a network filter, the available filters and their active filter names can be found here.

The active filter name for the Grey Matter Observables filter is gm.observables. It's corresponding configuration name will then be gm_observables. This pattern is consistent for all filters.

The configuration will be different for each filter, see the reference docs for the specific configuration options. For this guide, we will set the following configuration for observables:

"gm_observables": {
"emitFullResponse": false,
"useKafka": false,
"topic": "example-topic",
"eventTopic": "greymatter"
}

Since useKafka is false, the observables will be emitted to stdout, and we will be able to see them in the sidecar logs to test that the filter has been enabled.

2. Enable the filter

There are two updates to a listener object to enable a filter, adding the active filter name to the active_http_filters list, and adding it's configuration to the http_filters map object.

Note: For network filters, you would make the corresponding changes to active_network_filters and network_filters instead. For setting filters on a proxy object, you would make the corresponding changes to active_proxy_filters and proxy_filters instead.

Run the following to edit the SLO ingress listener:

greymatter edit listener listener-slo

And add the active filter name, "gm.observables", to the active_http_filters field, so that it looks like:

"active_http_filters": [
...
"gm.observables"
],

Then, we will add the configuration generated in step 1 to the http_filters map, with key gm_observables, the listener should look like:

{
"active_http_filters": [
...
"gm.observables"
],
"http_filters": {
...
"gm_observables": {
"emitFullResponse": false,
"useKafka": false,
"topic": "example-topic",
"eventTopic": "greymatter"
}
},
"listener_key": "listener-slo",
...
}

Once the listener object looks like the above, save the configuration. If you don't see any errors from the CLI, the filter should be enabled.

3. Verify

To verify that the filter has been enabled, follow the sidecar logs:

kubectl logs -l greymatter.io/control=slo -c sidecar -f

Then make a request to the SLO service in your browser - you can hit the docs at path /services/slo/latest. In the logs you will see the observable:

{"eventId":"109253e7-3975-11eb-b12f-82ca5b8a7000","eventChain":["109253e7-3975-11eb-b12f-82ca5b8a7000"],"schemaVersion":"1.0","originatorToken":["CN=quickstart,OU=Engineering,O=Decipher Technology Studios,L=Alexandria,ST=Virginia,C=US","CN=quickstart,OU=Engineering,O=Decipher Technology Studios,L=Alexandria,ST=Virginia,C=US"],"eventType":"example-topic","timestamp":1607446051, ...

This shows a successful filter configuration!

Modifying and disabling

Any available filter can be configured in this way.

To make any configuration modifications, you can edit the listener (or proxy) object directly, once the object is saved, the changes will take affect.

To disable a filter at any time, you can delete the active filter name from the active_*_filters list. The configuration will remain in *_filters so you can quickly turn it on/off if necessary. If you don't plan to re-enable the filter at any time, you can delete both the name from the active_*_filters list, and the configuration from the *_filters map.

Questions

Need help with your installation?

Create an account at Grey Matter Support to reach our team.