Protocols

Grey Matter supports a variety of network protocols. This doc describes each type of connections we support and how to configure it.

• http

• https

• http2

• grpc

• tcp

• websockets

http

Http is the default network protocol. To use http, set the ssl_config parameter in the domain and cluster to an empty bracket, or omit it entirely.

Example cluster:

{
  "zone_key": "default-zone",
  "cluster_key": "exapmle-cluster",
  "name": "example",
  "instances": []
}

example domain

{
  "zone_key": "default-zone",
  "domain_key": "example-domain",
  "name": "*",
  "port": 8080
}

This will ensure the proxy both handles incoming connections and makes outgoing upstream connections as http.

https

Https is http encrypted with tls. We can enable https by configuring the ssl_config attribute in the domain and cluster objects. Here is an example of a cluster using https:

{
  "zone_key": "default-zone",
  "cluster_key": "exapmle-cluster",
  "name": "example",
  "instances": [],
  "ssl_config": {
      "protocols": [
        "TLSv1.2"
      ],
    "require_client_certs": true,
    "trust_file": "/etc/proxy/tls/sidecar/ca.crt",
    "cert_key_pairs": [
      {
        "certificate_path": "/etc/proxy/tls/sidecar/server.crt",
        "key_path": "/etc/proxy/tls/sidecar/server.key"
      }
    ]
  },
  "require_tls": true,
}

and a domain:

{
  "zone_key": "default-zone",
  "domain_key": "example-domain",
  "name": "*",
  "port": 8080,
  "ssl_config": {
      "protocols": [
        "TLSv1.2"
      ],
    "require_client_certs": true,
    "trust_file": "/etc/proxy/tls/sidecar/ca.crt",
    "cert_key_pairs": [
      {
        "certificate_path": "/etc/proxy/tls/sidecar/server.crt",
        "key_path": "/etc/proxy/tls/sidecar/server.key"
      }
    ]
  },
  "force_https": true,
}

Together, the configured proxy will only handle incoming and create outgoing https requests using TLS version 1.2 and which contain valid cert / key pairs. For more information on different types of https configurations, see this doc on configuring ssl throughout the mesh.

At this writing, Grey Matter supports the following http encryption protocols: SSLv2, SSLv3, TLSv1.1, TLSv1.2.

http2

http2 is similar to http, but with added performance and optimizations. For more information see http2 specifications.

Http2 is supported by Grey Matter automatically via envoy's Protocol Selection attribute. Each cluster is hard-coded to use the protocol of the downstream cluster. For example, to make a request to a sidecar in front of a http2 service the client should initiate an http2 request. For more detailed information see this tutorial on making requests to tls and non-tls http2 clusters.

grpc

GRPC is an RPC framework that uses protocol buffers as an interface for bidirectional streaming. Currently, GRPC is not supported by Grey Matter.

However, Grey Matter should in theory support the envoy json -> grpc transcoder http filter. Using this filter, clients can make http JSON requests to a proxy instance, which is translated into gRPC compliant with the back end service's protobuf definitions. See this WIP example of this for more information.

tcp

Sidecars are able to field incoming and outgoing tcp connections using envoy's tcp network filter. To activate tcp, add envoy.tcp_proxy to the list of active network filters in the listener object. You must also specify the upstream cluster in the network_filters.envoy_tcp_proxy attribute.

{
  "zone_key": "default-zone",
  "listener_key": "example-listener",
  "name": "example-listener",
  "domain_keys": ["example-domain"],
  "ip": "0.0.0.0",
  "port": 8181,
  "protocol": "http_auto",
  "active_network_filters": ["envoy.tcp_proxy"],
  "network_filters": {
    "envoy_tcp_proxy": {
      "stat_prefix":"tcp_proxy",
      "cluster":"tcp_proxy"
    }
  }
}

For more info see this example on setting up a tcp listener.

websockets

Websockets open a two-way interactive stream between the client and server, whereas other protocols such as http are unidirectional. Websockets can be configured for a sidecar sitting in front of a compatible backend service by enabling websocket and http upgrades. This is done in Grey Matter by setting the "upgrade" : "websocket" attribute in the proxy object of the sidecar. This can be done in the following ways:

Environment Variable

Simply set UPGRADES=websocket as an environment variable.

The proxy will see this on startup and write the applicable envoy template. This is a string delimited list which can handle multiple upgrade types. Each upgrade corresponds to an envoy upgrade config type.

Dynamic Configuration in the Mesh

Upgrades can also be configured dynamically with the Grey Matter cli. Each proxy object has an attribute upgrades, which corresponds to the UPGRADES environment variable. To enable websockets, set upgrades to "websocket". A full example is below:

{
  "proxy_key": "gm-proxy-proxy",
  "zone_key": "default-zone",
  "name": "gm-proxy",
  "domain_keys": [
    "domain"
  ],
  "listener_keys": [
    "listener"
  ],
  "listeners": null,
  "upgrades": "websocket",
  "active_proxy_filters": null,
  "proxy_filters": null
}

Note that setting upgrades configures websocket connections, but will defer to the protocol of the incoming request. This allows for the sidecar to handle websocket connections to certain routes and clusters, and http request for others.

See this tutorial on configuring websockets for more detailed examples.