From fa914b487f47d65a1acbba78bcfa5c786717a207 Mon Sep 17 00:00:00 2001 From: Yuval Kohavi Date: Fri, 22 Dec 2017 20:33:14 -0500 Subject: [PATCH] filter: pb definition for squash filter (#353) Signed-off-by: Yuval Kohavi --- api/BUILD | 1 + api/filter/http/BUILD | 5 ++ api/filter/http/squash.proto | 48 ++++++++++++++++ .../network/http_connection_manager.proto | 1 + docs/build.sh | 1 + .../api-v1/http_filters/squash_filter.rst | 56 +++++++++++++++++++ .../http_filters/http_filters.rst | 1 + .../http_filters/squash_filter.rst | 40 +++++++++++++ test/validate/BUILD | 1 + test/validate/pgv_test.cc | 1 + 10 files changed, 155 insertions(+) create mode 100644 api/filter/http/squash.proto create mode 100644 docs/root/api-v1/http_filters/squash_filter.rst create mode 100644 docs/root/configuration/http_filters/squash_filter.rst diff --git a/api/BUILD b/api/BUILD index 4e42338d..d80a1462 100644 --- a/api/BUILD +++ b/api/BUILD @@ -171,6 +171,7 @@ proto_library( "//api/filter/http:lua", "//api/filter/http:rate_limit", "//api/filter/http:router", + "//api/filter/http:squash", "//api/filter/http:transcoder", "//api/filter/network:client_ssl_auth", "//api/filter/network:http_connection_manager", diff --git a/api/filter/http/BUILD b/api/filter/http/BUILD index e7d7a362..c02f4342 100644 --- a/api/filter/http/BUILD +++ b/api/filter/http/BUILD @@ -52,3 +52,8 @@ api_proto_library( name = "gzip", srcs = ["gzip.proto"], ) + +api_proto_library( + name = "squash", + srcs = ["squash.proto"], +) diff --git a/api/filter/http/squash.proto b/api/filter/http/squash.proto new file mode 100644 index 00000000..c46b18e2 --- /dev/null +++ b/api/filter/http/squash.proto @@ -0,0 +1,48 @@ +syntax = "proto3"; + +package envoy.api.v2.filter.http; + +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "validate/validate.proto"; + +// [#protodoc-title: Squash] +// Squash :ref:`configuration overview `. + +// [#proto-status: experimental] +message Squash { + // The name of the cluster that hosts the Squash server. + string cluster = 1 [(validate.rules).string.min_bytes = 1]; + + // When the filter requests the Squash server to create a DebugAttachment, it will use this + // structure as template for the body of the request. It can contain reference to environment + // variables in the form of '{{ ENV_VAR_NAME }}'. These can be used to provide the Squash server + // with more information to find the process to attach the debugger to. For example, in a + // Istio/k8s environment, this will contain information on the pod: + // + // .. code-block:: json + // + // { + // "spec": { + // "attachment": { + // "pod": "{{ POD_NAME }}", + // "namespace": "{{ POD_NAMESPACE }}" + // }, + // "match_request": true + // } + // } + // + // (where POD_NAME, POD_NAMESPACE are configured in the pod via the Downward API) + google.protobuf.Struct attachment_template = 2; + + // The timeout for individual requests sent to the Squash cluster. Defaults to 1 second. + google.protobuf.Duration request_timeout = 3; + + // The total timeout Squash will delay a request and wait for it to be attached. Defaults to 60 + // seconds. + google.protobuf.Duration attachment_timeout = 4; + + // Amount of time to poll for the status of the attachment object in the Squash server + // (to check if has been attached). Defaults to 1 second. + google.protobuf.Duration attachment_poll_period = 5; +} diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index 637e2099..f442a617 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -208,6 +208,7 @@ message HttpFilter { // * :ref:`envoy.lua ` // * :ref:`envoy.rate_limit ` // * :ref:`envoy.router ` + // * :ref:`envoy.squash ` string name = 1 [(validate.rules).string.min_bytes = 1]; // Filter specific configuration which depends on the filter being diff --git a/docs/build.sh b/docs/build.sh index 37b2304e..e50ba301 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -47,6 +47,7 @@ PROTO_RST=" /api/filter/http/lua/api/filter/http/lua.proto.rst /api/filter/http/rate_limit/api/filter/http/rate_limit.proto.rst /api/filter/http/router/api/filter/http/router.proto.rst + /api/filter/http/squash/api/filter/http/squash.proto.rst /api/filter/http/transcoder/api/filter/http/transcoder.proto.rst /api/filter/network/client_ssl_auth/api/filter/network/client_ssl_auth.proto.rst /api/filter/network/http_connection_manager/api/filter/network/http_connection_manager.proto.rst diff --git a/docs/root/api-v1/http_filters/squash_filter.rst b/docs/root/api-v1/http_filters/squash_filter.rst new file mode 100644 index 00000000..04637bf9 --- /dev/null +++ b/docs/root/api-v1/http_filters/squash_filter.rst @@ -0,0 +1,56 @@ +.. _config_http_filters_squash_v1: + +Squash +====== + +Squash :ref:`configuration overview `. + +.. code-block:: json + + { + "name": "squash", + "config": { + "cluster": "...", + "attachment_template": "{...}", + "attachment_timeout_ms": "...", + "attachment_poll_period_ms": "...", + "request_timeout_ms": "..." + } + } + +cluster + *(required, object)* The name of the cluster that hosts the Squash server. + +attachment_template + *(required, object)* When the filter requests the Squash server to create a DebugAttachment, it + will use this structure as template for the body of the request. It can contain reference to + environment variables in the form of '{{ ENV_VAR_NAME }}'. These can be used to provide the Squash + server with more information to find the process to attach the debugger to. For example, in a + Istio/k8s environment, this will contain information on the pod: + + .. code-block:: json + + { + "spec": { + "attachment": { + "pod": "{{ POD_NAME }}", + "namespace": "{{ POD_NAMESPACE }}" + }, + "match_request": true + } + } + + (where POD_NAME, POD_NAMESPACE are configured in the pod via the Downward API) + +request_timeout_ms + *(required, integer)* The timeout for individual requests sent to the Squash cluster. Defaults to + 1 second. + +attachment_timeout_ms + *(required, integer)* The total timeout Squash will delay a request and wait for it to be + attached. Defaults to 60 seconds. + +attachment_poll_period_ms + *(required, integer)* Amount of time to poll for the status of the attachment object in the Squash + server (to check if has been attached). Defaults to 1 second. + diff --git a/docs/root/configuration/http_filters/http_filters.rst b/docs/root/configuration/http_filters/http_filters.rst index 3469bd8d..ee5c6019 100644 --- a/docs/root/configuration/http_filters/http_filters.rst +++ b/docs/root/configuration/http_filters/http_filters.rst @@ -17,3 +17,4 @@ HTTP filters rate_limit_filter router_filter lua_filter + squash_filter diff --git a/docs/root/configuration/http_filters/squash_filter.rst b/docs/root/configuration/http_filters/squash_filter.rst new file mode 100644 index 00000000..01f86d73 --- /dev/null +++ b/docs/root/configuration/http_filters/squash_filter.rst @@ -0,0 +1,40 @@ +.. _config_http_filters_squash: + +Squash +====== + +Squash is an HTTP filter which enables Envoy to integrate with Squash microservices debugger. +Code: https://github.com/solo-io/squash, API Docs: https://squash.solo.io/ + +Overview +-------- + +The main use case for this filter is in a service mesh, where Envoy is deployed as a sidecar. +Once a request marked for debugging enters the mesh, the Squash Envoy filter reports its 'location' +in the cluster to the Squash server - as there is a 1-1 mapping between Envoy sidecars and +application containers, the Squash server can find and attach a debugger to the application container. +The Squash filter also holds the request until a debugger is attached (or a timeout occurs). This +enables developers (via Squash) to attach a native debugger to the container that will handle the +request, before the request arrive to the application code, without any changes to the cluster. + +Configuration +------------- + +* :ref:`v1 API reference ` +* :ref:`v2 API reference ` + +How it works +------------ + +When the Squash filter encounters a request containing the header 'x-squash-debug' it will: + +1. Delay the incoming request. +2. Contact the Squash server and request the creation of a DebugAttachment + + - On the Squash server side, Squash will attempt to attach a debugger to the application Envoy + proxies to. On success, it changes the state of the DebugAttachment + to attached. + +3. Wait until the Squash server updates the DebugAttachment object's state to attached (or + error state) +4. Resume the incoming request diff --git a/test/validate/BUILD b/test/validate/BUILD index 1563d47a..6ae1a807 100644 --- a/test/validate/BUILD +++ b/test/validate/BUILD @@ -18,6 +18,7 @@ api_cc_test( "//api/filter/http:health_check", "//api/filter/http:lua", "//api/filter/http:router", + "//api/filter/http:squash", "//api/filter/http:transcoder", "//api/filter/network:http_connection_manager", "//api/filter/network:mongo_proxy", diff --git a/test/validate/pgv_test.cc b/test/validate/pgv_test.cc index bfbd2b3f..b6060abc 100644 --- a/test/validate/pgv_test.cc +++ b/test/validate/pgv_test.cc @@ -16,6 +16,7 @@ #include "api/filter/http/health_check.pb.validate.h" #include "api/filter/http/lua.pb.validate.h" #include "api/filter/http/router.pb.validate.h" +#include "api/filter/http/squash.pb.validate.h" #include "api/filter/http/transcoder.pb.validate.h" #include "api/filter/network/http_connection_manager.pb.validate.h" #include "api/filter/network/mongo_proxy.pb.validate.h"