Proxy Template

The proxy template provides configuration options for low-level Envoy resources that Kuma policies do not directly expose.

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

A ProxyTemplate policy can provide custom definitions of:

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

Usage

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. 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: '*'
  10.   conf:
  11.     # `imports` allows us to reuse the dataplane configuration that Kuma
  12.     # generates automatically and add more customizations on top of it
  13.     imports:
  14.       # `default-proxy` is a reference name for the default
  15.       # data plane proxy configuration generated by Kuma
  16.       - default-proxy
  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 data plane proxies 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. Possible values:
  • default-proxy - the default configuration for non-ingress data planes.
  • ingress-proxy - the default configuration for zone-ingress proxy.
  • gateway-proxy - the default configuration for mesh gateway.
  • egress-proxy - the default configuration for zone-egress proxy.

You can choose more than one import object.

Modifications

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.

Available origins:

  • 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 Zone Ingress.
  • gateway - resources generated for MeshGateway

Cluster

Modifications that are applied on Clusters 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:

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

  • tags - tags of inbound or outbound listeners. They match Listener.metadata.filterMetadata[io.kuma.tags] in XDS configuration.

  • Kubernetes

  • Universal
  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_default_svc_80
  10.   conf:
  11.     imports:
  12.       - default-proxy
  13.     modifications:
  14.       - listener:
  15.           operation: add
  16.           value: |
  17.             name: test-listener
  18.             address:
  19.               socketAddress:
  20.                 address: 192.168.0.1
  21.                 portValue: 8080
  22.       - listener:
  23.           operation: patch
  24.           match: # optional: if absent, all listeners will be patched
  25.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
  26.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  27.             tags: # optional: if absent, all listeners are matched
  28.               kuma.io/service: backend
  29.           value: | # you can specify only part of listener definition that will be merged into existing listener
  30.             continueOnListenerFiltersTimeout: true
  31.       - listener:
  32.           operation: remove
  33.           match: # optional: if absent, all listeners will be removed
  34.             name: test-listener # optional: if absent, all listeners regardless of name will be removed
  35.             origin: inbound # optional: if absent, all listeners 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.     - 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.           tags: # optional: if absent, all listeners are matched
  25.             kuma.io/service: backend
  26.         value: | # you can specify only part of listener definition that will be merged into existing listener
  27.           continueOnListenerFiltersTimeout: true
  28.     - listener:
  29.         operation: remove
  30.         match: # optional: if absent, all listeners will be removed
  31.           name: test-listener # optional: if absent, all listeners regardless of name will be removed
  32.           origin: inbound # optional: if absent, all listeners regardless of its origin will be removed

Network Filter

Modifications that are applied on Network Filters that are part of Listeners resource. Modifications are applied on all Filter Chains in the Listener.

Available operations:

  • 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.
  • listenerTags - tags of inbound or outbound listeners. They match Listener.metadata.filterMetadata[io.kuma.tags] in XDS configuration.

  • origin - origin of the listener.

  • Kubernetes

  • Universal
  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_default_svc_80
  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.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  18.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  19.               kuma.io/service: backend
  20.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  21.           value: |
  22.             name: envoy.filters.network.local_ratelimit
  23.             typedConfig:
  24.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  25.               statPrefix: rateLimit
  26.               tokenBucket:
  27.                 fillInterval: 1s
  28.       - networkFilter:
  29.           operation: addLast
  30.           match: # optional: if absent, filter will be added to all listeners
  31.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  32.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  33.               kuma.io/service: backend
  34.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  35.           value: |
  36.             name: envoy.filters.network.local_ratelimit
  37.             typedConfig:
  38.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  39.               statPrefix: rateLimit
  40.               tokenBucket:
  41.                 fillInterval: 1s
  42.       - networkFilter:
  43.           operation: addBefore
  44.           match:
  45.             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.
  46.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  47.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  48.               kuma.io/service: backend
  49.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  50.           value: |
  51.             name: envoy.filters.network.local_ratelimit
  52.             typedConfig:
  53.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  54.               statPrefix: rateLimit
  55.               tokenBucket:
  56.                 fillInterval: 1s
  57.       - networkFilter:
  58.           operation: addAfter
  59.           match:
  60.             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.
  61.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  62.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  63.               kuma.io/service: backend
  64.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  65.           value: |
  66.             name: envoy.filters.network.local_ratelimit
  67.             typedConfig:
  68.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  69.               statPrefix: rateLimit
  70.               tokenBucket:
  71.                 fillInterval: 1s
  72.       - networkFilter:
  73.           operation: patch
  74.           match:
  75.             name: envoy.filters.network.tcp_proxy 
  76.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  77.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  78.               kuma.io/service: backend
  79.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  80.           value: | # you can specify only part of filter definition that will be merged into existing filter
  81.             name: envoy.filters.network.tcp_proxy
  82.             typedConfig:
  83.               '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
  84.               idleTimeout: 10s
  85.       - networkFilter:
  86.           operation: remove
  87.           match: # optional: if absent, all filters from all listeners will be removed
  88.             name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
  89.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  90.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  91.               kuma.io/service: backend
  92.             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.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  16.             kuma.io/service: backend
  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:
  21.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  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.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  30.             kuma.io/service: backend
  31.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  32.         value: |
  33.           name: envoy.filters.network.local_ratelimit
  34.           typedConfig:
  35.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  36.             statPrefix: rateLimit
  37.             tokenBucket:
  38.               fillInterval: 1s
  39.     - networkFilter:
  40.         operation: addBefore
  41.         match:
  42.           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.
  43.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  44.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  45.             kuma.io/service: backend
  46.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  47.         value: |
  48.           name: envoy.filters.network.local_ratelimit
  49.           typedConfig:
  50.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  51.             statPrefix: rateLimit
  52.             tokenBucket:
  53.               fillInterval: 1s
  54.     - networkFilter:
  55.         operation: addAfter
  56.         match:
  57.           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.
  58.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  59.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  60.             kuma.io/service: backend
  61.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  62.         value: |
  63.           name: envoy.filters.network.local_ratelimit
  64.           typedConfig:
  65.             '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  66.             statPrefix: rateLimit
  67.             tokenBucket:
  68.               fillInterval: 1s
  69.     - networkFilter:
  70.         operation: patch
  71.         match:
  72.           name: envoy.filters.network.tcp_proxy 
  73.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  74.           listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  75.             kuma.io/service: backend
  76.           origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  77.         value: | # you can specify only part of filter definition that will be merged into existing filter
  78.           name: envoy.filters.network.tcp_proxy
  79.           typedConfig:
  80.             '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
  81.             idleTimeout: 10s
  82.     - networkFilter:
  83.         operation: remove
  84.         match: # optional: if absent, all filters from all listeners will be removed
  85.           name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
  86.           listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  87.           listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  88.             kuma.io/service: backend
  89.           origin: inbound # optional: if absent, all filters regardless of its origin will be removed

Example how to change streamIdleTimeout for MeshGateway:

  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: '*'
  10.   conf:
  11.     imports:
  12.       - gateway-proxy # default configuration for MeshGateway
  13.     modifications:
  14.       - networkFilter:
  15.           operation: patch
  16.           match:
  17.             name: envoy.filters.network.http_connection_manager
  18.             origin: gateway # you can also specify the name of the listener
  19.           value: |
  20.             name: envoy.filters.network.http_connection_manager
  21.             typedConfig:
  22.               '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  23.               streamIdleTimeout: 15s

HTTP Filter

Modifications that are applied on HTTP Filters that are part of Listeners resource. Modifications are applied on all HTTP Connection Managers in the Listener.

HTTP Filter modifications can only be applied on services configured as HTTP.

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
  • listenerTags - tags of inbound or outbound listeners. They match Listener.metadata.filterMetadata[io.kuma.tags] in XDS configuration.

  • origin - origin of the listener

  • Kubernetes

  • Universal
  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_default_svc_80
  10.   conf:
  11.     imports:
  12.       - default-proxy
  13.     modifications:
  14.       - httpFilter:
  15.           operation: addFirst
  16.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
  17.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  18.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  19.               kuma.io/service: backend
  20.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  21.           value: |
  22.             name: envoy.filters.http.gzip
  23.             typedConfig:
  24.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  25.               memoryLevel: 9
  26.       - httpFilter:
  27.           operation: addLast
  28.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
  29.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  30.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  31.               kuma.io/service: backend
  32.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  33.           value: |
  34.             name: envoy.filters.http.gzip
  35.             typedConfig:
  36.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  37.               memoryLevel: 9
  38.       - httpFilter:
  39.           operation: addBefore
  40.           match:
  41.             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.
  42.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  43.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  44.               kuma.io/service: backend
  45.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  46.           value: |
  47.             name: envoy.filters.http.gzip
  48.             typedConfig:
  49.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  50.               memoryLevel: 9
  51.       - httpFilter:
  52.           operation: addAfter
  53.           match:
  54.             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.
  55.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  56.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  57.               kuma.io/service: backend
  58.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  59.           value: |
  60.             name: envoy.filters.http.gzip
  61.             typedConfig:
  62.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  63.               memoryLevel: 9
  64.       - httpFilter:
  65.           operation: patch
  66.           match:
  67.             name: envoy.filters.http.router 
  68.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  69.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  70.               kuma.io/service: backend
  71.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  72.           value: | # you can specify only part of filter definition that will be merged into existing filter
  73.             name: envoy.filters.http.router 
  74.             typedConfig:
  75.               '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  76.               dynamicStats: false
  77.       - httpFilter:
  78.           operation: remove
  79.           match: # optional: if absent, all filters from all listeners will be removed
  80.             name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
  81.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  82.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  83.               kuma.io/service: backend
  84.             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.     - 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.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  16.             kuma.io/service: backend
  17.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  18.         value: |
  19.           name: envoy.filters.http.gzip
  20.           typedConfig:
  21.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  22.             memoryLevel: 9
  23.     - httpFilter:
  24.         operation: addLast
  25.         match: # optional: if absent, filter will be added to all HTTP Connection Managers
  26.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  27.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  28.             kuma.io/service: backend
  29.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  30.         value: |
  31.           name: envoy.filters.http.gzip
  32.           typedConfig:
  33.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  34.             memoryLevel: 9
  35.     - httpFilter:
  36.         operation: addBefore
  37.         match:
  38.           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.
  39.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  40.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  41.             kuma.io/service: backend
  42.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  43.         value: |
  44.           name: envoy.filters.http.gzip
  45.           typedConfig:
  46.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  47.             memoryLevel: 9
  48.     - httpFilter:
  49.         operation: addAfter
  50.         match:
  51.           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.
  52.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  53.           listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  54.             kuma.io/service: backend
  55.           origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  56.         value: |
  57.           name: envoy.filters.http.gzip
  58.           typedConfig:
  59.             '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  60.             memoryLevel: 9
  61.     - httpFilter:
  62.         operation: patch
  63.         match:
  64.           name: envoy.filters.http.router 
  65.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  66.           listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  67.             kuma.io/service: backend
  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.http.router 
  71.           typedConfig:
  72.             '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  73.             dynamicStats: false
  74.     - httpFilter:
  75.         operation: remove
  76.         match: # optional: if absent, all filters from all listeners will be removed
  77.           name: envoy.filters.http.gzip # 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.           listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  80.             kuma.io/service: backend
  81.           origin: inbound # optional: if absent, all filters regardless of its origin will be removed

VirtualHost

Modifications that are applied on VirtualHost resources.

VirtualHost modifications can only be applied on services configured as HTTP.

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

How Kuma handles the proxy template

At runtime, whenever kuma-cp generates the configuration for a given data plane proxy, it will proceed as follows:

  1. Kuma searches for all the ProxyTemplates resources that have been defined in the specified Mesh.
  2. It loads in memory the ProxyTemplates resources whose selectors match either an inbound or a gateway definition of any data plane proxy 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.

Lua filter example

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

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

Matching

ProxyTemplate is a Dataplane policy. You can use all the tags in the selectors section.

Builtin Gateway support

The Proxy Template policy supports a new gateway-proxy configuration name that can be imported. This generates the Envoy resources for a Kuma Gateway proxy. The origin name for matching template modifications is gateway.