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. The value must be one or both of default-proxy – the default configuration for non-ingress data planes – or ingress – the default configuration for zone-ingress proxy.

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.

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:

  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.           value: | # you can specify only part of listener definition that will be merged into existing listener
  28.             continueOnListenerFiltersTimeout: true
  29.       - listener:
  30.           operation: remove
  31.           match: # optional: if absent, all listeners will be removed
  32.             name: test-listener # optional: if absent, all listeners regardless of name will be removed
  33.             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.         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 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.

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

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

VirtualHost

Modifications that are applied on VirtualHost 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_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.

  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.           value: |
  20.             name: envoy.filters.http.lua
  21.             typedConfig:
  22.               '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
  23.               inline_code: |
  24.                 function envoy_on_request(request_handle)
  25.                   request_handle:headers():add("x-header", "test")
  26.                 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.         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")
  23.               end

Matching

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