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

JSONPatch

If you use JSONPatch, remember to always use camelCase instead of snake_case in path parameter even though you see snake_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