.. _envoy_v3_api_file_contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto: contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto (proto) ========================================================================= .. warning:: This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the :ref:`threat model `, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points. .. _envoy_v3_api_msg_extensions.filters.http.golang.v3alpha.Config: extensions.filters.http.golang.v3alpha.Config --------------------------------------------- :repo:`[extensions.filters.http.golang.v3alpha.Config proto] ` Golang :ref:`configuration overview `. 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 .. _extension_envoy.filters.http.golang: This extension has the qualified name ``envoy.filters.http.golang`` .. note:: This extension is only available in :ref:`contrib ` images. .. note:: This extension is functional but has not had substantial production burn time, use only with this caveat. This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted. .. tip:: This extension extends and can be used with the following extension category: - :ref:`envoy.filters.http ` .. code-block:: json :force: { "library_id": ..., "library_path": ..., "plugin_name": ..., "plugin_config": {...}, "merge_policy": ... } .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.Config.library_id: library_id (`string `_, *REQUIRED*) library_id is a unique ID for a dynamic library file, must be unique globally. .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.Config.library_path: library_path (`string `_, *REQUIRED*) Dynamic library implementing the interface of ``StreamFilter ``. .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.Config.plugin_name: plugin_name (`string `_, *REQUIRED*) plugin_name is the name of the go plugin, which needs to be consistent with the name registered in http::RegisterHttpFilterConfigFactory. .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.Config.plugin_config: plugin_config (`Any `_) plugin_config is the configuration of the go plugin, note that this configuration is only parsed in the go plugin. .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.Config.merge_policy: merge_policy (:ref:`extensions.filters.http.golang.v3alpha.Config.MergePolicy `) 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. .. _envoy_v3_api_enum_extensions.filters.http.golang.v3alpha.Config.MergePolicy: Enum extensions.filters.http.golang.v3alpha.Config.MergePolicy -------------------------------------------------------------- :repo:`[extensions.filters.http.golang.v3alpha.Config.MergePolicy proto] ` .. _envoy_v3_api_enum_value_extensions.filters.http.golang.v3alpha.Config.MergePolicy.MERGE_VIRTUALHOST_ROUTER_FILTER: MERGE_VIRTUALHOST_ROUTER_FILTER *(DEFAULT)* ⁣ .. _envoy_v3_api_enum_value_extensions.filters.http.golang.v3alpha.Config.MergePolicy.MERGE_VIRTUALHOST_ROUTER: MERGE_VIRTUALHOST_ROUTER ⁣ .. _envoy_v3_api_enum_value_extensions.filters.http.golang.v3alpha.Config.MergePolicy.OVERRIDE: OVERRIDE ⁣ .. _envoy_v3_api_msg_extensions.filters.http.golang.v3alpha.RouterPlugin: extensions.filters.http.golang.v3alpha.RouterPlugin --------------------------------------------------- :repo:`[extensions.filters.http.golang.v3alpha.RouterPlugin proto] ` .. code-block:: json :force: { "config": {...} } .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.RouterPlugin.config: config (`Any `_, *REQUIRED*) The config field is used to setting per-route plugin config. 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 .. _envoy_v3_api_msg_extensions.filters.http.golang.v3alpha.ConfigsPerRoute: extensions.filters.http.golang.v3alpha.ConfigsPerRoute ------------------------------------------------------ :repo:`[extensions.filters.http.golang.v3alpha.ConfigsPerRoute proto] ` .. code-block:: json :force: { "plugins_config": {...} } .. _envoy_v3_api_field_extensions.filters.http.golang.v3alpha.ConfigsPerRoute.plugins_config: plugins_config (**repeated** map<`string `_, :ref:`extensions.filters.http.golang.v3alpha.RouterPlugin `>) 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