Proxy Template

    If you need features that aren’t available as a Kuma policy, open a new issue on GitHub (opens new window) so they can be added to the Kuma roadmap.

    A policy can provide custom definitions of:

    The custom definitions either complement or replace the resources that Kuma generates automatically.

    Kuma uses the following default ProxyTemplate resource for every data plane proxy (kuma-dp) that is added to a Mesh. This resource looks like:

    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: '*'
    7. conf:
    8.   # `imports` allows us to reuse the dataplane configuration that Kuma
    9.   # generates automatically and add more customizations on top of it
    10.   imports:
    11.     # `default-proxy` is a reference name for the default
    12.     # data plane proxy configuration generated by Kuma
    13.     - default-proxy

    In these examples, note:

    • The selectors object specifies the that are targeted by the ProxyTemplate resource. Values are provided as Kuma tags.
    • The imports object specifies the reusable configuration that Kuma generates automatically. Kuma then extends the imports object with the custom configuration you specify. The value must be one or both of default-proxy — the default configuration for non-ingress data planes — or ingress — the default configuration for ingress data planes.

    To customize the configuration of data plane proxies, you can combine modifications of any type in one ProxyTemplate. Each modification consists of the following sections:

    • operation - operation applied to the generated config (e.g. add, remove, patch).
    • match - some operations can be applied on matched resources (e.g. remove only resource of given name, patch all outbound resources).
    • value - raw Envoy xDS configuration. Can be partial if operation is patch.

    Origin

    All resources generated by Kuma are marked with the origin value, so you can match resources. Examples: add new filters but only on inbound listeners, set timeouts on outbound clusters.

    • inbound - resources generated for incoming traffic.
    • outbound - resources generated for outgoing traffic.
    • transparent - resources generated for transparent proxy functionality.
    • prometheus - resources generated when Prometheus metrics are enabled.
    • direct-access - resources generated for Direct Access functionality.
    • ingress - resources generated for Ingress Dataplane.

    Cluster

    Modifications that are applied on resources.

    Available operations:

    • add - add a new cluster or replace existing if the name is the same.
    • remove - remove a cluster.
    • patch - patch a part of cluster definition.

    Available matchers:

    • name - name of the cluster.
    • origin - origin of the cluster.
    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - cluster:
    15.           operation: add
    16.           value: |
    17.             name: test-cluster
    18.             connectTimeout: 5s
    19.             type: STATIC
    20.       - cluster:
    21.           operation: patch
    22.           match: # optional: if absent, all clusters will be patched
    23.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
    24.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
    25.           value: | # you can specify only part of cluster definition that will be merged into existing cluster
    26.             connectTimeout: 5s
    27.       - cluster:
    28.           operation: remove
    29.           match: # optional: if absent, all clusters will be removed
    30.             name: test-cluster # optional: if absent, all clusters regardless of name will be removed
    31.             origin: inbound # optional: if absent, all clusters regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - cluster:
    12.         operation: add
    13.         value: |
    14.           name: test-cluster
    15.           connectTimeout: 5s
    16.           type: STATIC
    17.     - cluster:
    18.         operation: patch
    19.         match: # optional: if absent, all clusters will be patched
    20.           name: test-cluster # optional: if absent, all clusters regardless of name will be patched
    21.           origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
    22.         value: | # you can specify only part of cluster definition that will be merged into existing cluster
    23.           connectTimeout: 5s
    24.     - cluster:
    25.         operation: remove
    26.         match: # optional: if absent, all clusters will be removed
    27.           name: test-cluster # optional: if absent, all clusters regardless of name will be removed
    28.           origin: inbound # optional: if absent, all clusters regardless of its origin will be removed

    Listener

    Modifications that are applied on resources.

    Available operations:

    • add - add a new listener or replace existing if the name is the same.
    • remove - remove a listener.
    • patch - patch a part of listener definition.

    Available matchers:

    • name - name of the listener.
    • origin - origin of the listener.
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - listener:
    12.         operation: add
    13.         value: |
    14.           name: test-listener
    15.           address:
    16.             socketAddress:
    17.               address: 192.168.0.1
    18.               portValue: 8080
    19.     - listener:
    20.         operation: patch
    21.         match: # optional: if absent, all listeners will be patched
    22.           name: test-listener # optional: if absent, all listeners regardless of name will be patched
    23.           origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
    24.         value: | # you can specify only part of listener definition that will be merged into existing listener
    25.           continueOnListenerFiltersTimeout: true
    26.     - listener:
    27.         operation: remove
    28.         match: # optional: if absent, all listeners will be removed
    29.           name: test-listener # optional: if absent, all listeners regardless of name will be removed
    30.           origin: inbound # optional: if absent, all listeners regardless of its origin will be removed

    Network Filter

    Modifications that are applied on that are part of ListenersProxy Template - 图11 (opens new window) resource. Modifications are applied on all in the Listener.

    • addFirst - add a new filter as a first filter in Filter Chain.
    • addLast - add a new filter as a last filter in Filter Chain.
    • addAfter - add a new filter after other filter in Filter Chain that is matched using match section.
    • addBefore - add a new filter before other filter in Filter Chain that is matched using match section.
    • patch - patch a matched filter in Filter Chain.
    • remove - remove a filter in Filter Chain.

    Available matchers:

    • name - name of the network filter.
    • listenerName - name of the listener.
    • origin - origin of the listener.
    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - networkFilter:
    15.           operation: addFirst
    16.           match: # optional: if absent, filter will be added to all listeners
    17.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    18.           value: |
    19.             name: envoy.filters.network.local_ratelimit
    20.             typedConfig:
    22.               statPrefix: rateLimit
    23.               tokenBucket:
    24.                 fillInterval: 1s
    25.       - networkFilter:
    26.           operation: addLast
    27.           match: # optional: if absent, filter will be added to all listeners
    28.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    29.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    30.           value: |
    31.             name: envoy.filters.network.local_ratelimit
    32.             typedConfig:
    33.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    34.               statPrefix: rateLimit
    35.               tokenBucket:
    36.                 fillInterval: 1s
    37.       - networkFilter:
    38.           operation: addBefore
    39.           match:
    40.             name: envoy.filters.network.tcp_proxy # a new filter (Local RateLimit) will be added before existing (TcpProxy). If there is no TcpProxy filter, Local RateLimit won't be added.
    41.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    42.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    43.           value: |
    44.             name: envoy.filters.network.local_ratelimit
    45.             typedConfig:
    46.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    47.               statPrefix: rateLimit
    48.               tokenBucket:
    49.                 fillInterval: 1s
    50.       - networkFilter:
    51.           operation: addAfter
    52.           match:
    53.             name: envoy.filters.network.tcp_proxy # a new filter (Local RateLimit) will be added after existing (TcpProxy). If there is no TcpProxy filter, Local RateLimit won't be added.
    54.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    55.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    56.           value: |
    57.             name: envoy.filters.network.local_ratelimit
    58.             typedConfig:
    59.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    60.               statPrefix: rateLimit
    61.               tokenBucket:
    62.                 fillInterval: 1s
    63.       - networkFilter:
    64.           operation: patch
    65.           match:
    66.             name: envoy.filters.network.tcp_proxy 
    67.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    68.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    69.           value: | # you can specify only part of filter definition that will be merged into existing filter
    70.             name: envoy.filters.network.tcp_proxy
    71.             typedConfig:
    72.               '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
    73.               idleTimeout: 10s
    74.       - networkFilter:
    75.           operation: remove
    76.           match: # optional: if absent, all filters from all listeners will be removed
    77.             name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
    78.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    79.             origin: inbound # optional: if absent, all filters regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - networkFilter:
    12.         operation: addFirst
    13.         match: # optional: if absent, filter will be added to all listeners
    14.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    15.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    16.         value: |
    17.           name: envoy.filters.network.local_ratelimit
    18.           typedConfig:
    19.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    20.             statPrefix: rateLimit
    21.             tokenBucket:
    22.               fillInterval: 1s
    23.     - networkFilter:
    24.         operation: addLast
    25.         match: # optional: if absent, filter will be added to all listeners
    26.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    27.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    28.         value: |
    29.           name: envoy.filters.network.local_ratelimit
    30.           typedConfig:
    31.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    32.             statPrefix: rateLimit
    33.             tokenBucket:
    34.               fillInterval: 1s
    35.     - networkFilter:
    36.         operation: addBefore
    37.         match:
    38.           name: envoy.filters.network.tcp_proxy # a new filter (Local RateLimit) will be added before existing (TcpProxy). If there is no TcpProxy filter, Local RateLimit won't be added.
    39.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    40.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    41.         value: |
    42.           name: envoy.filters.network.local_ratelimit
    43.           typedConfig:
    44.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    45.             statPrefix: rateLimit
    46.             tokenBucket:
    47.               fillInterval: 1s
    48.     - networkFilter:
    49.         operation: addAfter
    50.         match:
    51.           name: envoy.filters.network.tcp_proxy # a new filter (Local RateLimit) will be added after existing (TcpProxy). If there is no TcpProxy filter, Local RateLimit won't be added.
    52.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    53.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    54.         value: |
    55.           name: envoy.filters.network.local_ratelimit
    56.           typedConfig:
    57.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    58.             statPrefix: rateLimit
    59.             tokenBucket:
    60.               fillInterval: 1s
    61.     - networkFilter:
    62.         operation: patch
    63.         match:
    64.           name: envoy.filters.network.tcp_proxy 
    65.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    66.           origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    67.         value: | # you can specify only part of filter definition that will be merged into existing filter
    68.           name: envoy.filters.network.tcp_proxy
    69.           typedConfig:
    70.             '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
    71.             idleTimeout: 10s
    72.     - networkFilter:
    73.         operation: remove
    74.         match: # optional: if absent, all filters from all listeners will be removed
    75.           name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
    76.           listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    77.           origin: inbound # optional: if absent, all filters regardless of its origin will be removed

    HTTP Filter

    Modifications that are applied on that are part of Listeners (opens new window) resource. Modifications are applied on all in the Listener.

    Available operations:

    • addFirst - add a new filter as a first filter in HTTP Connection Manager.
    • addLast - add a new filter as a last filter in HTTP Connection Manager.
    • addAfter - add a new filter after other filter in HTTP Connection Manager that is matched using match section.
    • addBefore - add a new filter before other filter in HTTP Connection Manager that is matched using match section.
    • patch - patch a matched filter in HTTP Connection Manager.
    • remove - remove a filter in HTTP Connection Manager.

    Available matchers:

    • name - name of the network filter
    • listenerName - name of the listener
    • origin - origin of the listener
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - httpFilter:
    12.         operation: addFirst
    13.         match: # optional: if absent, filter will be added to all HTTP Connection Managers
    14.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    15.         value: |
    16.           name: envoy.filters.http.gzip
    17.           typedConfig:
    18.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    19.             memoryLevel: 9
    21.         operation: addLast
    22.         match: # optional: if absent, filter will be added to all HTTP Connection Managers
    23.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    24.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    25.         value: |
    26.           name: envoy.filters.http.gzip
    27.           typedConfig:
    28.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    29.             memoryLevel: 9
    30.     - httpFilter:
    31.         operation: addBefore
    32.         match:
    33.           name: envoy.filters.http.router # a new filter (Gzip) will be added before existing (Router). If there is no Router filter, Gzip won't be added.
    34.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    35.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    36.         value: |
    37.           name: envoy.filters.http.gzip
    38.           typedConfig:
    39.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    40.             memoryLevel: 9
    41.     - httpFilter:
    42.         operation: addAfter
    43.         match:
    44.           name: envoy.filters.http.router # a new filter (Gzip) will be added after existing (Router). If there is no Router filter, Gzip won't be added.
    45.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    46.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    47.         value: |
    48.           name: envoy.filters.http.gzip
    49.           typedConfig:
    50.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    51.             memoryLevel: 9
    52.     - httpFilter:
    53.         operation: patch
    54.         match:
    55.           name: envoy.filters.http.router 
    56.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    57.           origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    58.         value: | # you can specify only part of filter definition that will be merged into existing filter
    59.           name: envoy.filters.http.router 
    60.           typedConfig:
    61.             '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
    62.             dynamicStats: false
    63.     - httpFilter:
    64.         operation: remove
    65.         match: # optional: if absent, all filters from all listeners will be removed
    66.           name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
    67.           listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    68.           origin: inbound # optional: if absent, all filters regardless of its origin will be removed

    VirtualHost

    Modifications that are applied on resources.

    Available operations:

    • add - add a new VirtualHost.
    • remove - remove a VirtualHost.
    • patch - patch a part of VirtualHost definition.

    Available matchers:

    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - virtualHost:
    15.           operation: add
    16.           value: |
    17.             name: backend
    18.             domains:
    19.             - "*"
    20.             routes:
    21.             - match:
    22.                 prefix: /
    23.               route:
    24.                 cluster: backend
    25.       - virtualHost:
    26.           operation: patch
    27.           match: # optional: if absent, all listeners will be patched
    28.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
    29.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
    30.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
    31.           value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
    32.             retryPolicy:
    33.               retryOn: 5xx
    34.               numRetries: 3
    35.       - virtualHost:
    36.           operation: remove
    37.           match: # optional: if absent, all virtual hosts will be removed
    38.             name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
    39.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - virtualHost:
    12.         operation: add
    13.         value: |
    14.           name: backend
    15.           domains:
    16.           - "*"
    17.           routes:
    18.           - match:
    19.               prefix: /
    20.             route:
    21.               cluster: backend
    22.     - virtualHost:
    23.         operation: patch
    24.         match: # optional: if absent, all listeners will be patched
    25.           name: backend # optional: if absent, all virtual hosts regardless of name will be patched
    26.           origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
    27.           routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
    28.         value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
    29.           retryPolicy:
    30.             retryOn: 5xx
    31.             numRetries: 3
    32.     - virtualHost:
    33.         operation: remove
    34.         match: # optional: if absent, all virtual hosts will be removed
    35.           name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
    36.           origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed
    1. Kuma searches for all the ProxyTemplates resources that have been defined in the specified .
    2. It loads in memory the ProxyTemplates resources whose selectors match either an inbound or a gateway definition of any accordingly to the Kuma Tags selected.
    3. Every matching ProxyTemplate is ranked. The ProxyTemplate resource with the highest ranking is used to generate the configuration for the specified data plane proxy (or proxies).
    4. If the ProxyTemplate resource specifies an imports object, these resources are generated first.
    5. If a ProxyTemplate defines a modification object, all modifications are applied, one by one in the order defined in modification section.

    For a more complete example, explore this Lua filter that adds the new x-header: test header to all outgoing HTTP requests.

    1. type: ProxyTemplate
    2. mesh: default
    3. name: backend-lua-filter
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy # apply modifications on top of resources generated by Kuma
    10.   modifications:
    11.     - httpFilter:
    12.         operation: addBefore
    13.         match:
    14.           name: envoy.filters.http.router
    15.           origin: outbound
    16.         value: |
    17.           name: envoy.filters.http.lua
    18.           typedConfig:
    19.             '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    20.             inline_code: |
    21.               function envoy_on_request(request_handle)
    22.                 request_handle:headers():add("x-header", "test")