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 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.

extensions.filters.http.golang.v3alpha.Config

[extensions.filters.http.golang.v3alpha.Config proto]

Golang 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 <contrib/golang/filters/http/source/go/pkg/api.StreamFilter> API by the GO language to achieve the effects of Envoy native filter.

The filter based on the APIs implementation StreamFilter <contrib/golang/filters/http/source/go/pkg/api.StreamFilter> For details, take a look at the /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.

$ 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.

#!/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

$ go_plugin_generate.sh limit
$ go_plugin_generate.sh auth

Configure go-plugin

Use the http filter of :ref: golang <envoy.filters.http.golang> to specify :ref: library <envoy.filters.http.golang> in ingress and egress to enable the plugin.

Example:

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

This extension has the qualified name envoy.filters.http.golang

Note

This extension is only available in 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:

envoy.filters.http

{
  "library_id": ...,
  "library_path": ...,
  "plugin_name": ...,
  "plugin_config": {...},
  "merge_policy": ...
}

library_id: (string, REQUIRED) library_id is a unique ID for a dynamic library file, must be unique globally.

library_path: (string, REQUIRED) Dynamic library implementing the interface of StreamFilter <contrib/golang/filters/http/source/go/pkg/api.StreamFilter>.

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.

plugin_config: (Any) plugin_config is the configuration of the go plugin, note that this configuration is only parsed in the go plugin.

merge_policy: (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.

Enum extensions.filters.http.golang.v3alpha.Config.MergePolicy

[extensions.filters.http.golang.v3alpha.Config.MergePolicy proto]

MERGE_VIRTUALHOST_ROUTER_FILTER: (DEFAULT) ⁣

MERGE_VIRTUALHOST_ROUTER: ⁣

OVERRIDE: ⁣

extensions.filters.http.golang.v3alpha.RouterPlugin

[extensions.filters.http.golang.v3alpha.RouterPlugin proto]

{
  "config": {...}
}

config

(Any, REQUIRED) The config field is used to setting per-route plugin config.

Example

typed_per_filter_config:
  envoy.filters.http.golang:
    "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.ConfigsPerRoute
    plugins_config:
      plugin1:
       disabled: true

extensions.filters.http.golang.v3alpha.ConfigsPerRoute

[extensions.filters.http.golang.v3alpha.ConfigsPerRoute proto]

{
  "plugins_config": {...}
}

plugins_config

(repeated map<string, 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

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