MeshProxyPatch

The MeshProxyPatch 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 MeshProxyPatch policy can modify:

This policy uses a new policy matching algorithm. Do not combine with Proxy Template.

targetRef support matrix

targetRefAllowed kinds
targetRef.kindMesh, MeshSubset, MeshService, MeshServiceSubset
targetRefAllowed kinds
targetRef.kindMesh, MeshGateway
targetRefAllowed kinds
targetRef.kindMesh, MeshSubset, MeshService, MeshServiceSubset

To learn more about the information in this table, see the matching docs.

Configuration

Modifications

MeshProxyPatch lets you specify modifications in appendModification block that can add a new resource, patch an existing resource or remove an existing resource.

Each xDS resource modification consists of 3 fields:

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

and one of

  • jsonPatches - list of modifications in JSON Patch notation.

  • 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 specific resources.

Examples: add new filters but only on inbound listeners, set timeouts on outbound clusters.

Well known origins:

  • inbound - resources generated for incoming traffic.
  • outbound - resources generated for outgoing traffic.
  • transparent - resources generated for transparent proxy functionality.
  • prometheus - resources generated for Prometheus to scrape when metrics on the Mesh is enabled.
  • direct-access - resources generated for Direct Access functionality.
  • gateway - resources generated for MeshGateway.

The list is not complete, as policy plugins can introduce new resources. For example MeshTrace plugin can create Cluster with mesh-trace origin.

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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: backend_default_svc_80
  10.   default:
  11.     appendModifications:
  12.       - cluster:
  13.           operation: Add
  14.           value: |
  15.             name: test-cluster
  16.             connectTimeout: 5s
  17.             type: STATIC
  18.       - cluster:
  19.           operation: Patch
  20.           match: # optional: if absent, all clusters will be patched
  21.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
  22.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
  23.           value: | # you can specify only part of cluster definition that will be merged into existing cluster
  24.             connectTimeout: 5s
  25.       - cluster:
  26.           operation: Patch
  27.           match: # optional: if absent, all clusters will be patched
  28.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
  29.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
  30.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  31.             - op: add
  32.               path: /transportSocket/typedConfig/commonTlsContext/tlsParams # remember to always use camelCase
  33.               value:
  34.                 tlsMinimumProtocolVersion: TLSv1_2
  35.             - op: add
  36.               path: /transportSocket/typedConfig/commonTlsContext/tlsParams/tlsMaximumProtocolVersion
  37.               value: TLSv1_2
  38.             - op: replace
  39.               path: /connectTimeout
  40.               value: 77s
  41.       - cluster:
  42.           operation: Remove
  43.           match: # optional: if absent, all clusters will be removed
  44.             name: test-cluster # optional: if absent, all clusters regardless of name will be removed
  45.             origin: inbound # optional: if absent, all clusters regardless of its origin will be removed
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: backend
  8.   default:
  9.     appendModifications:
  10.       - cluster:
  11.           operation: Add
  12.           value: |
  13.             name: test-cluster
  14.             connectTimeout: 5s
  15.             type: STATIC
  16.       - cluster:
  17.           operation: Patch
  18.           match: # optional: if absent, all clusters will be patched
  19.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
  20.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
  21.           value: | # you can specify only part of cluster definition that will be merged into existing cluster
  22.             connectTimeout: 5s
  23.       - cluster:
  24.           operation: Patch
  25.           match: # optional: if absent, all clusters will be patched
  26.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
  27.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
  28.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  29.             - op: add
  30.               path: /transportSocket/typedConfig/commonTlsContext/tlsParams
  31.               value:
  32.                 tlsMinimumProtocolVersion: TLSv1_2
  33.             - op: add
  34.               path: /transportSocket/typedConfig/commonTlsContext/tlsParams/tlsMaximumProtocolVersion
  35.               value: TLSv1_2
  36.             - op: replace
  37.               path: /connectTimeout
  38.               value: 77s
  39.       - cluster:
  40.           operation: Remove
  41.           match: # optional: if absent, all clusters will be removed
  42.             name: test-cluster # optional: if absent, all clusters regardless of name will be removed
  43.             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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: backend_default_svc_80
  10.   default:
  11.     appendModifications:
  12.       - listener:
  13.           operation: Add
  14.           value: |
  15.             name: test-listener
  16.             address:
  17.               socketAddress:
  18.                 address: 192.168.0.1
  19.                 portValue: 8080
  20.       - listener:
  21.           operation: Patch
  22.           match: # optional: if absent, all listeners will be patched
  23.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
  24.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  25.             tags: # optional: if absent, all listeners are matched
  26.               kuma.io/service: backend
  27.           value: | # you can specify only part of listener definition that will be merged into existing listener
  28.             continueOnListenerFiltersTimeout: true
  29.       - listener:
  30.           operation: Patch
  31.           match: # optional: if absent, all listeners will be patched
  32.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
  33.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  34.             tags: # optional: if absent, all listeners are matched
  35.               kuma.io/service: backend
  36.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  37.             - op: add
  38.               path: /continueOnListenerFiltersTimeout
  39.               value: true
  40.       - listener:
  41.           operation: Remove
  42.           match: # optional: if absent, all listeners will be removed
  43.             name: test-listener # optional: if absent, all listeners regardless of name will be removed
  44.             origin: inbound # optional: if absent, all listeners regardless of its origin will be removed
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: backend
  8.   default:
  9.     appendModifications:
  10.       - listener:
  11.           operation: Add
  12.           value: |
  13.             name: test-listener
  14.             address:
  15.               socketAddress:
  16.                 address: 192.168.0.1
  17.                 portValue: 8080
  18.       - listener:
  19.           operation: Patch
  20.           match: # optional: if absent, all listeners will be patched
  21.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
  22.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  23.             tags: # optional: if absent, all listeners are matched
  24.               kuma.io/service: backend
  25.           value: | # you can specify only part of listener definition that will be merged into existing listener
  26.             continueOnListenerFiltersTimeout: true
  27.       - listener:
  28.           operation: Patch
  29.           match: # optional: if absent, all listeners will be patched
  30.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
  31.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  32.             tags: # optional: if absent, all listeners are matched
  33.               kuma.io/service: backend
  34.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  35.             - op: add
  36.               path: /continueOnListenerFiltersTimeout
  37.               value: true
  38.       - listener:
  39.           operation: Remove
  40.           match: # optional: if absent, all listeners will be removed
  41.             name: test-listener # optional: if absent, all listeners regardless of name will be removed
  42.             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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: backend_default_svc_80
  10.   default:
  11.     appendModifications:
  12.       - networkFilter:
  13.           operation: AddFirst
  14.           match: # optional: if absent, filter will be added to all listeners
  15.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  16.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  17.               kuma.io/service: backend
  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.             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.network.local_ratelimit
  35.             typedConfig:
  36.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  37.               statPrefix: rateLimit
  38.               tokenBucket:
  39.                 fillInterval: 1s
  40.       - networkFilter:
  41.           operation: AddBefore
  42.           match:
  43.             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.
  44.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  45.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  46.               kuma.io/service: backend
  47.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  48.           value: |
  49.             name: envoy.filters.network.local_ratelimit
  50.             typedConfig:
  51.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  52.               statPrefix: rateLimit
  53.               tokenBucket:
  54.                 fillInterval: 1s
  55.       - networkFilter:
  56.           operation: AddAfter
  57.           match:
  58.             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.
  59.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  60.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  61.               kuma.io/service: backend
  62.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  63.           value: |
  64.             name: envoy.filters.network.local_ratelimit
  65.             typedConfig:
  66.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  67.               statPrefix: rateLimit
  68.               tokenBucket:
  69.                 fillInterval: 1s
  70.       - networkFilter:
  71.           operation: Patch
  72.           match:
  73.             name: envoy.filters.network.tcp_proxy 
  74.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  75.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  76.               kuma.io/service: backend
  77.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  78.           value: | # you can specify only part of filter definition that will be merged into existing filter
  79.             name: envoy.filters.network.tcp_proxy
  80.             typedConfig:
  81.               '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
  82.               idleTimeout: 10s
  83.       - networkFilter:
  84.           operation: Patch
  85.           match:
  86.             name: envoy.filters.network.tcp_proxy 
  87.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  88.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  89.               kuma.io/service: backend
  90.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  91.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  92.             - op: replace
  93.               path: /idleTimeout
  94.               value: 10s
  95.       - networkFilter:
  96.           operation: Remove
  97.           match: # optional: if absent, all filters from all listeners will be removed
  98.             name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
  99.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  100.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  101.               kuma.io/service: backend
  102.             origin: inbound # optional: if absent, all filters regardless of its origin will be removed
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: backend
  8.   default:
  9.     appendModifications:
  10.       - networkFilter:
  11.           operation: AddFirst
  12.           match: # optional: if absent, filter will be added to all listeners
  13.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  14.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  15.               kuma.io/service: backend
  16.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  17.           value: |
  18.             name: envoy.filters.network.local_ratelimit
  19.             typedConfig:
  20.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  21.               statPrefix: rateLimit
  22.               tokenBucket:
  23.                 fillInterval: 1s
  24.       - networkFilter:
  25.           operation: AddLast
  26.           match: # optional: if absent, filter will be added to all listeners
  27.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  28.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  29.               kuma.io/service: backend
  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.             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.network.local_ratelimit
  48.             typedConfig:
  49.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  50.               statPrefix: rateLimit
  51.               tokenBucket:
  52.                 fillInterval: 1s
  53.       - networkFilter:
  54.           operation: AddAfter
  55.           match:
  56.             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.
  57.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  58.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  59.               kuma.io/service: backend
  60.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  61.           value: |
  62.             name: envoy.filters.network.local_ratelimit
  63.             typedConfig:
  64.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  65.               statPrefix: rateLimit
  66.               tokenBucket:
  67.                 fillInterval: 1s
  68.       - networkFilter:
  69.           operation: Patch
  70.           match:
  71.             name: envoy.filters.network.tcp_proxy
  72.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  73.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  74.               kuma.io/service: backend
  75.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  76.           value: | # you can specify only part of filter definition that will be merged into existing filter
  77.             name: envoy.filters.network.tcp_proxy
  78.             typedConfig:
  79.               '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
  80.               idleTimeout: 10s
  81.       - networkFilter:
  82.           operation: Patch
  83.           match:
  84.             name: envoy.filters.network.tcp_proxy
  85.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  86.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  87.               kuma.io/service: backend
  88.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  89.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  90.             - op: replace
  91.               path: /idleTimeout
  92.               value: 10s
  93.       - networkFilter:
  94.           operation: Remove
  95.           match: # optional: if absent, all filters from all listeners will be removed
  96.             name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
  97.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  98.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  99.               kuma.io/service: backend
  100.             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 that Kuma applies 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 HTTP 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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: backend_default_svc_80
  10.   default:
  11.     appendModifications:
  12.       - httpFilter:
  13.           operation: AddFirst
  14.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
  15.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  16.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  17.               kuma.io/service: backend
  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.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  29.               kuma.io/service: backend
  30.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  31.           value: |
  32.             name: envoy.filters.http.gzip
  33.             typedConfig:
  34.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  35.               memoryLevel: 9
  36.       - httpFilter:
  37.           operation: AddBefore
  38.           match:
  39.             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.
  40.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  41.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  42.               kuma.io/service: backend
  43.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  44.           value: |
  45.             name: envoy.filters.http.gzip
  46.             typedConfig:
  47.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  48.               memoryLevel: 9
  49.       - httpFilter:
  50.           operation: AddAfter
  51.           match:
  52.             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.
  53.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  54.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  55.               kuma.io/service: backend
  56.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  57.           value: |
  58.             name: envoy.filters.http.gzip
  59.             typedConfig:
  60.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  61.               memoryLevel: 9
  62.       - httpFilter:
  63.           operation: Patch
  64.           match:
  65.             name: envoy.filters.http.router 
  66.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  67.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  68.               kuma.io/service: backend
  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.http.router 
  72.             typedConfig:
  73.               '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  74.               dynamicStats: false
  75.       - httpFilter:
  76.           operation: Patch
  77.           match:
  78.             name: envoy.filters.http.router 
  79.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  80.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  81.               kuma.io/service: backend
  82.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  83.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  84.             - op: replace
  85.               path: /dynamicStats
  86.               value: false
  87.       - httpFilter:
  88.           operation: Remove
  89.           match: # optional: if absent, all filters from all listeners will be removed
  90.             name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
  91.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  92.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
  93.               kuma.io/service: backend
  94.             origin: inbound # optional: if absent, all filters regardless of its origin will be removed
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: backend_default_svc_80
  8.   default:
  9.     appendModifications:
  10.       - httpFilter:
  11.           operation: AddFirst
  12.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
  13.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  14.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  15.               kuma.io/service: backend
  16.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  17.           value: |
  18.             name: envoy.filters.http.gzip
  19.             typedConfig:
  20.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  21.               memoryLevel: 9
  22.       - httpFilter:
  23.           operation: AddLast
  24.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
  25.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  26.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  27.               kuma.io/service: backend
  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.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  40.               kuma.io/service: backend
  41.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  42.           value: |
  43.             name: envoy.filters.http.gzip
  44.             typedConfig:
  45.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  46.               memoryLevel: 9
  47.       - httpFilter:
  48.           operation: AddAfter
  49.           match:
  50.             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.
  51.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  52.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
  53.               kuma.io/service: backend
  54.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  55.           value: |
  56.             name: envoy.filters.http.gzip
  57.             typedConfig:
  58.               '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
  59.               memoryLevel: 9
  60.       - httpFilter:
  61.           operation: Patch
  62.           match:
  63.             name: envoy.filters.http.router
  64.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  65.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  66.               kuma.io/service: backend
  67.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  68.           value: | # you can specify only part of filter definition that will be merged into existing filter
  69.             name: envoy.filters.http.router 
  70.             typedConfig:
  71.               '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  72.               dynamicStats: false
  73.       - httpFilter:
  74.           operation: Patch
  75.           match:
  76.             name: envoy.filters.http.router
  77.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  78.             listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
  79.               kuma.io/service: backend
  80.             origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  81.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  82.             - op: replace
  83.               path: /dynamicStats
  84.               value: false
  85.       - httpFilter:
  86.           operation: Remove
  87.           match: # optional: if absent, all filters from all listeners will be removed
  88.             name: envoy.filters.http.gzip # 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

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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: backend_default_svc_80
  10.   default:
  11.     appendModifications:
  12.       - virtualHost:
  13.           operation: Add
  14.           value: |
  15.             name: backend
  16.             domains:
  17.             - "*"
  18.             routes:
  19.             - match:
  20.                 prefix: /
  21.               route:
  22.                 cluster: backend
  23.       - virtualHost:
  24.           operation: Patch
  25.           match: # optional: if absent, all listeners will be patched
  26.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
  27.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
  28.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
  29.           value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
  30.             retryPolicy:
  31.               retryOn: 5xx
  32.               numRetries: 3
  33.       - virtualHost:
  34.           operation: Patch
  35.           match: # optional: if absent, all listeners will be patched
  36.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
  37.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
  38.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
  39.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  40.             - op: add
  41.               path: /retryPolicy
  42.               value:
  43.                 retryOn: 5xx
  44.                 numRetries: 3
  45.       - virtualHost:
  46.           operation: Remove
  47.           match: # optional: if absent, all virtual hosts will be removed
  48.             name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
  49.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: backend
  8.   default:
  9.     appendModifications:
  10.       - virtualHost:
  11.           operation: Add
  12.           value: |
  13.             name: backend
  14.             domains:
  15.             - "*"
  16.             routes:
  17.             - match:
  18.                 prefix: /
  19.               route:
  20.                 cluster: backend
  21.       - virtualHost:
  22.           operation: Patch
  23.           match: # optional: if absent, all listeners will be patched
  24.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
  25.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
  26.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
  27.           value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
  28.             retryPolicy:
  29.               retryOn: 5xx
  30.               numRetries: 3
  31.       - virtualHost:
  32.           operation: Patch
  33.           match: # optional: if absent, all listeners will be patched
  34.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
  35.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
  36.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
  37.           jsonPatches: # optional and mutually exclusive with "value": list of modifications in JSON Patch notation
  38.             - op: add
  39.               path: /retryPolicy
  40.               value:
  41.                 retryOn: 5xx
  42.                 numRetries: 3
  43.       - virtualHost:
  44.           operation: Remove
  45.           match: # optional: if absent, all virtual hosts will be removed
  46.             name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
  47.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed

Merging

All modifications from appendModification list are always merged. For example, if there is a policy with targetRef.kind: Mesh and second policy with targetRef.kind: MeshService that matches a data plane proxy, all modifications from both policies will be applied.

Json patch

If you use json patch, remember to always use snakeCase instead of camel_case in path parameter even though you see camel_case in Envoy Config Dump.

Examples

Timeout adjustment for MeshGateway

Example how to change streamIdleTimeout for MeshGateway:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshGateway
  9.     name: gateway
  10.   default:
  11.     appendModifications:
  12.       - networkFilter:
  13.           operation: Patch
  14.           match:
  15.             name: envoy.filters.network.http_connection_manager
  16.             origin: gateway # you can also specify the name of the listener
  17.           jsonPatches:
  18.             - op: replace
  19.               path: /streamIdleTimeout
  20.               value: 15s
  1. type: MeshProxyPatch
  2. mesh: default
  3. name: custom-template-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshGateway
  7.     name: gateway
  8.   default:
  9.     appendModifications:
  10.       - networkFilter:
  11.           operation: Patch
  12.           match:
  13.             name: envoy.filters.network.http_connection_manager
  14.             origin: gateway # you can also specify the name of the listener
  15.           jsonPatches:
  16.             - op: replace
  17.               path: /streamIdleTimeout
  18.               value: 15s

Lua filter

Here is and example of 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: MeshProxyPatch
  3. metadata:
  4.   name: custom-template-1
  5.   namespace: kuma-system
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: mesh-gateway_gateways_svc
  10.   default:
  11.     appendModifications:
  12.       - httpFilter:
  13.           operation: AddBefore
  14.           match:
  15.             name: envoy.filters.http.router
  16.             origin: outbound
  17.             listenerTags:
  18.               kuma.io/service: offers
  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: MeshProxyPatch
  2. mesh: default
  3. name: backend-lua-filter
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: mesh-gateway_gateways_svc
  8.   default:
  9.     appendModifications:
  10.       - httpFilter:
  11.           operation: AddBefore
  12.           match:
  13.             name: envoy.filters.http.router
  14.             origin: outbound
  15.             listenerTags:
  16.               kuma.io/service: offers
  17.           value: |
  18.             name: envoy.filters.http.lua
  19.             typedConfig:
  20.               '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
  21.               inline_code: |
  22.                 function envoy_on_request(request_handle)
  23.                   request_handle:headers():add("x-header", "test")
  24.                 end

All policy options