From 56b03fbe74398a9597972c0576e1c60c32afd18f Mon Sep 17 00:00:00 2001 From: "data-plane-api(Azure Pipelines)" Date: Thu, 5 Jan 2023 17:31:48 +0000 Subject: [PATCH] Envoy's L7 Go extension API (#22573) Signed-off-by: wangfakang Mirrored from https://github.com/envoyproxy/envoy @ c256b948683b8bd800df80f69f470e1202510242 --- BUILD | 1 + .../filters/http/golang/v3alpha/BUILD | 12 + .../filters/http/golang/v3alpha/golang.proto | 214 ++++++++++++++++++ versioning/BUILD | 1 + 4 files changed, 228 insertions(+) create mode 100644 contrib/envoy/extensions/filters/http/golang/v3alpha/BUILD create mode 100644 contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto diff --git a/BUILD b/BUILD index f51f62ce..5743322c 100644 --- a/BUILD +++ b/BUILD @@ -73,6 +73,7 @@ proto_library( visibility = ["//visibility:public"], deps = [ "//contrib/envoy/extensions/filters/http/dynamo/v3:pkg", + "//contrib/envoy/extensions/filters/http/golang/v3alpha:pkg", "//contrib/envoy/extensions/filters/http/language/v3alpha:pkg", "//contrib/envoy/extensions/filters/http/squash/v3:pkg", "//contrib/envoy/extensions/filters/http/sxg/v3alpha:pkg", diff --git a/contrib/envoy/extensions/filters/http/golang/v3alpha/BUILD b/contrib/envoy/extensions/filters/http/golang/v3alpha/BUILD new file mode 100644 index 00000000..ec1e778e --- /dev/null +++ b/contrib/envoy/extensions/filters/http/golang/v3alpha/BUILD @@ -0,0 +1,12 @@ +# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "@com_github_cncf_udpa//udpa/annotations:pkg", + "@com_github_cncf_udpa//xds/annotations/v3:pkg", + ], +) diff --git a/contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto b/contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto new file mode 100644 index 00000000..db53f0b7 --- /dev/null +++ b/contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto @@ -0,0 +1,214 @@ +syntax = "proto3"; + +package envoy.extensions.filters.http.golang.v3alpha; + +import "google/protobuf/any.proto"; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.http.golang.v3alpha"; +option java_outer_classname = "GolangProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/golang/v3alpha"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: golang extension filter] +// Golang :ref:`configuration overview `. +// [#extension: envoy.filters.http.golang] +// +// In the below example, we configured the go plugin 'auth' and 'limit' dynamic libraries into +// Envoy, which can avoid rebuilding Envoy. +// +// * Develop go-plugin +// +// We can implement the interface of ``StreamFilter `` +// API by the GO language to achieve the effects of Envoy native filter. +// +// The filter based on the APIs implementation ``StreamFilter `` +// For details, take a look at the :repo:`/contrib/golang/filters/http/test/test_data/echo`. +// +// Then put the GO plugin source code into the ${OUTPUT}/src/ directory with the name of the plugin +// for GO plugin builds. +// The following examples implement limit and auth GO plugins. +// +// .. code-block:: bash +// +// $ tree /home/admin/envoy/go-plugins/src/ +// |--auth +// | |--config.go +// | |--filter.go +// ---limit +// |--config.go +// |--filter.go +// +// * Build go-plugin +// +// Build the Go plugin so by `go_plugin_generate.sh` script, below example the `liblimit.so` and +// `libauth.so` will be generated in the `/home/admin/envoy/go-plugins/` directory. +// +// .. code-block:: bash +// +// #!/bin/bash +// if [ $# != 2 ]; then +// echo "need input the go plugin name" +// exit 1 +// fi +// +// PLUGINNAME=$1 +// OUTPUT=/home/admin/envoy/go-plugins/ +// PLUGINSRCDIR=${OUTPUT}/src/${PLUGINNAME} +// go build --buildmode=c-shared -v -o $OUTPUT/lib${PLUGINNAME}.so $PLUGINSRCDIR +// +// .. code-block:: bash +// +// $ go_plugin_generate.sh limit +// $ go_plugin_generate.sh auth +// +// * Configure go-plugin +// +// Use the http filter of :ref: `golang ` to specify +// :ref: `library` in ingress and egress to enable the plugin. +// +// Example: +// +// .. code-block:: yaml +// +// static_resources: +// listeners: +// - name: ingress +// address: +// socket_address: +// protocol: TCP +// address: 0.0.0.0 +// port_value: 8080 +// filter_chains: +// - filters: +// - name: envoy.filters.network.http_connection_manager +// ...... +// http_filters: +// - name: envoy.filters.http.golang +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config +// library_id: limit-id +// library_path: "/home/admin/envoy/go-plugins/liblimit.so" +// plugine_name: limit +// plugin_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.limit.v3.Config +// xxx1: xx1 +// xxx2: xx2 +// - name: envoy.filters.http.header_to_metadata +// - name: envoy.filters.http.golang +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config +// library_id: auth-id +// library_path: "/home/admin/envoy/go-plugins/libauth.so" +// plugine_name: auth +// plugin_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.auth.v3.Config +// xxx1: xx1 +// xxx2: xx2 +// - name: envoy.filters.http.router +// - name: egress +// address: +// socket_address: +// protocol: TCP +// address: 0.0.0.0 +// port_value: 8081 +// filter_chains: +// - filters: +// - name: envoy.filters.network.http_connection_manager +// ...... +// http_filters: +// - name: envoy.filters.http.golang +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config +// library_id: auth-id +// library_path: "/home/admin/envoy/go-plugins/libauth.so" +// plugine_name: auth +// plugin_config: +// "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.auth.v3.Config +// xxx1: xx1 +// xxx2: xx2 +// - name: envoy.filters.http.router +// [#next-free-field: 6] +message Config { + enum MergePolicy { + MERGE_VIRTUALHOST_ROUTER_FILTER = 0; + MERGE_VIRTUALHOST_ROUTER = 1; + OVERRIDE = 3; + } + + // library_id is a unique ID for a dynamic library file, must be unique globally. + string library_id = 1 [(validate.rules).string = {min_len: 1}]; + + // Dynamic library implementing the interface of + // ``StreamFilter ``. + // [#comment:TODO(wangfakang): Support for downloading libraries from remote repositories.] + string library_path = 2 [(validate.rules).string = {min_len: 1}]; + + // plugin_name is the name of the go plugin, which needs to be consistent with the name + // registered in http::RegisterHttpFilterConfigFactory. + string plugin_name = 3 [(validate.rules).string = {min_bytes: 1}]; + + // plugin_config is the configuration of the go plugin, note that this configuration is + // only parsed in the go plugin. + google.protobuf.Any plugin_config = 4; + + // merge_policy is the merge policy configured by the go plugin. + // go plugin configuration supports three dimensions: the virtual host’s typed_per_filter_config, + // the route’s typed_per_filter_config or filter's config. + // The meanings are as follows: + // MERGE_VIRTUALHOST_ROUTER_FILTER: pass all configuration into go plugin. + // MERGE_VIRTUALHOST_ROUTER: pass Virtual-Host and Router configuration into go plugin. + // OVERRIDE: override according to Router > Virtual_host > Filter priority and pass the + // configuration to the go plugin. + MergePolicy merge_policy = 5 [(validate.rules).enum = {defined_only: true}]; +} + +message RouterPlugin { + // Example + // + // .. code-block:: yaml + // + // typed_per_filter_config: + // envoy.filters.http.golang: + // "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.ConfigsPerRoute + // plugins_config: + // plugin1: + // disabled: true + oneof override { + option (validate.required) = true; + + // [#not-implemented-hide:] + // Disable the filter for this particular vhost or route. + // If disabled is specified in multiple per-filter-configs, the most specific one will be used. + bool disabled = 1 [(validate.rules).bool = {const: true}]; + + // The config field is used to setting per-route plugin config. + google.protobuf.Any config = 2; + } +} + +message ConfigsPerRoute { + // plugins_config is the configuration of the go plugin at the per-router, and + // key is the name of the go plugin. + // Example + // + // .. code-block:: yaml + // + // typed_per_filter_config: + // envoy.filters.http.golang: + // "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.ConfigsPerRoute + // plugins_config: + // plugin1: + // disabled: true + // plugin2: + // config: + // "@type": type.googleapis.com/golang.http.plugin2 + // xxx: xxx + map plugins_config = 1; +} diff --git a/versioning/BUILD b/versioning/BUILD index aa51c232..8cd4cfad 100644 --- a/versioning/BUILD +++ b/versioning/BUILD @@ -11,6 +11,7 @@ proto_library( deps = [ "//contrib/envoy/extensions/config/v3alpha:pkg", "//contrib/envoy/extensions/filters/http/dynamo/v3:pkg", + "//contrib/envoy/extensions/filters/http/golang/v3alpha:pkg", "//contrib/envoy/extensions/filters/http/language/v3alpha:pkg", "//contrib/envoy/extensions/filters/http/squash/v3:pkg", "//contrib/envoy/extensions/filters/http/sxg/v3alpha:pkg",