Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Deploy a standalone control plane
    • Multi-zone deployment
    • Deploy a multi-zone global control plane
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Non-mesh traffic
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshAccessLog (Beta)
    • MeshCircuitBreaker (Beta)
    • MeshFaultInjection (Beta)
    • MeshHealthCheck (Beta)
    • MeshHTTPRoute (Beta)
    • MeshProxyPatch (Beta)
    • MeshRateLimit (Beta)
    • MeshRetry (Beta)
    • MeshTimeout (Beta)
    • MeshTrace (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference
    • Open source License
    • Contribute to Mesh

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • targetRef support matrix
  • Configuration
    • Modifications
  • Merging
  • Examples
    • Timeout adjustment for MeshGateway
    • Lua filter
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Policies
  • MeshProxyPatch (beta)

MeshProxyPatch (beta)

The MeshProxyPatch provides configuration options for low-level Envoy resources that Kong Mesh policies do not directly expose.

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

A MeshProxyPatch policy can modify:

  • Listeners
  • Clusters
  • Network Filters
  • HTTP Filters
  • VirtualHost

This policy uses a new policy matching algorithm and is in beta state. It should not be combined with Proxy Template.

targetRef support matrix

targetRef.kind top level
Mesh ✅
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).
  • value - raw Envoy xDS configuration. Can be partial if operation is patch.

Origin

All resources generated by Kong Mesh 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:

  • name - name of the Cluster.
  • origin - origin of the Cluster.
Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - cluster:
          operation: Add
          value: |
            name: test-cluster
            connectTimeout: 5s
            type: STATIC
      - cluster:
          operation: Patch
          match: # optional: if absent, all clusters will be patched
            name: test-cluster # optional: if absent, all clusters regardless of name will be patched
            origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
          value: | # you can specify only part of cluster definition that will be merged into existing cluster
            connectTimeout: 5s
      - cluster:
          operation: Remove
          match: # optional: if absent, all clusters will be removed
            name: test-cluster # optional: if absent, all clusters regardless of name will be removed
            origin: inbound # optional: if absent, all clusters regardless of its origin will be removed
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: backend
  default:
    appendModifications:
      - cluster:
          operation: Add
          value: |
            name: test-cluster
            connectTimeout: 5s
            type: STATIC
      - cluster:
          operation: Patch
          match: # optional: if absent, all clusters will be patched
            name: test-cluster # optional: if absent, all clusters regardless of name will be patched
            origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
          value: | # you can specify only part of cluster definition that will be merged into existing cluster
            connectTimeout: 5s
      - cluster:
          operation: Remove
          match: # optional: if absent, all clusters will be removed
            name: test-cluster # optional: if absent, all clusters regardless of name will be removed
            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
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - listener:
          operation: Add
          value: |
            name: test-listener
            address:
              socketAddress:
                address: 192.168.0.1
                portValue: 8080
      - listener:
          operation: Patch
          match: # optional: if absent, all listeners will be patched
            name: test-listener # optional: if absent, all listeners regardless of name will be patched
            origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
            tags: # optional: if absent, all listeners are matched
              kuma.io/service: backend
          value: | # you can specify only part of listener definition that will be merged into existing listener
            continueOnListenerFiltersTimeout: true
      - listener:
          operation: Remove
          match: # optional: if absent, all listeners will be removed
            name: test-listener # optional: if absent, all listeners regardless of name will be removed
            origin: inbound # optional: if absent, all listeners regardless of its origin will be removed
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: backend
  default:
    appendModifications:
      - listener:
          operation: Add
          value: |
            name: test-listener
            address:
              socketAddress:
                address: 192.168.0.1
                portValue: 8080
      - listener:
          operation: Patch
          match: # optional: if absent, all listeners will be patched
            name: test-listener # optional: if absent, all listeners regardless of name will be patched
            origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
            tags: # optional: if absent, all listeners are matched
              kuma.io/service: backend
          value: | # you can specify only part of listener definition that will be merged into existing listener
            continueOnListenerFiltersTimeout: true
      - listener:
          operation: Remove
          match: # optional: if absent, all listeners will be removed
            name: test-listener # optional: if absent, all listeners regardless of name will be removed
            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
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - networkFilter:
          operation: AddFirst
          match: # optional: if absent, filter will be added to all listeners
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddLast
          match: # optional: if absent, filter will be added to all listeners
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddBefore
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddAfter
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: Patch
          match:
            name: envoy.filters.network.tcp_proxy 
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
            listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
          value: | # you can specify only part of filter definition that will be merged into existing filter
            name: envoy.filters.network.tcp_proxy
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
              idleTimeout: 10s
      - networkFilter:
          operation: Remove
          match: # optional: if absent, all filters from all listeners will be removed
            name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
            listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
            listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
              kuma.io/service: backend
            origin: inbound # optional: if absent, all filters regardless of its origin will be removed
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: backend
  default:
    appendModifications:
      - networkFilter:
          operation: AddFirst
          match: # optional: if absent, filter will be added to all listeners
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddLast
          match: # optional: if absent, filter will be added to all listeners
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddBefore
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: AddAfter
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.network.local_ratelimit
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
              statPrefix: rateLimit
              tokenBucket:
                fillInterval: 1s
      - networkFilter:
          operation: Patch
          match:
            name: envoy.filters.network.tcp_proxy
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
            listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
          value: | # you can specify only part of filter definition that will be merged into existing filter
            name: envoy.filters.network.tcp_proxy
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
              idleTimeout: 10s
      - networkFilter:
          operation: Remove
          match: # optional: if absent, all filters from all listeners will be removed
            name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
            listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
            listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
              kuma.io/service: backend
            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 Kong Mesh 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
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - httpFilter:
          operation: AddFirst
          match: # optional: if absent, filter will be added to all HTTP Connection Managers
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddLast
          match: # optional: if absent, filter will be added to all HTTP Connection Managers
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddBefore
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddAfter
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: Patch
          match:
            name: envoy.filters.http.router 
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
            listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
          value: | # you can specify only part of filter definition that will be merged into existing filter
            name: envoy.filters.http.router 
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
              dynamicStats: false
      - httpFilter:
          operation: Remove
          match: # optional: if absent, all filters from all listeners will be removed
            name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
            listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
            listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
              kuma.io/service: backend
            origin: inbound # optional: if absent, all filters regardless of its origin will be removed
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - httpFilter:
          operation: AddFirst
          match: # optional: if absent, filter will be added to all HTTP Connection Managers
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddLast
          match: # optional: if absent, filter will be added to all HTTP Connection Managers
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddBefore
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: AddAfter
          match:
            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.
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
            listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
          value: |
            name: envoy.filters.http.gzip
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
              memoryLevel: 9
      - httpFilter:
          operation: Patch
          match:
            name: envoy.filters.http.router
            listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
            listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
              kuma.io/service: backend
            origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
          value: | # you can specify only part of filter definition that will be merged into existing filter
            name: envoy.filters.http.router 
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
              dynamicStats: false
      - httpFilter:
          operation: Remove
          match: # optional: if absent, all filters from all listeners will be removed
            name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
            listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
            listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
              kuma.io/service: backend
            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:

  • name - name of the VirtualHost.
  • origin - origin of the VirtualHost.
  • routeConfigurationName - name of the RouteConfiguration.
Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: backend_default_svc_80
  default:
    appendModifications:
      - virtualHost:
          operation: Add
          value: |
            name: backend
            domains:
            - "*"
            routes:
            - match:
                prefix: /
              route:
                cluster: backend
      - virtualHost:
          operation: Patch
          match: # optional: if absent, all listeners will be patched
            name: backend # optional: if absent, all virtual hosts regardless of name will be patched
            origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
            routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
          value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
            retryPolicy:
              retryOn: 5xx
              numRetries: 3
      - virtualHost:
          operation: Remove
          match: # optional: if absent, all virtual hosts will be removed
            name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
            origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: backend
  default:
    appendModifications:
      - virtualHost:
          operation: Add
          value: |
            name: backend
            domains:
            - "*"
            routes:
            - match:
                prefix: /
              route:
                cluster: backend
      - virtualHost:
          operation: Patch
          match: # optional: if absent, all listeners will be patched
            name: backend # optional: if absent, all virtual hosts regardless of name will be patched
            origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
            routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
          value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
            retryPolicy:
              retryOn: 5xx
              numRetries: 3
      - virtualHost:
          operation: Remove
          match: # optional: if absent, all virtual hosts will be removed
            name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
            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.

Examples

Timeout adjustment for MeshGateway

Example how to change streamIdleTimeout for MeshGateway:

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: mesh-gateway_gateways_svc
  default:
    appendModifications:
      - networkFilter:
          operation: Patch
          match:
            name: envoy.filters.network.http_connection_manager
            origin: gateway # you can also specify the name of the listener
          value: |
            name: envoy.filters.network.http_connection_manager
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
              streamIdleTimeout: 15s
type: MeshProxyPatch
mesh: default
name: custom-template-1
spec:
  targetRef:
    kind: MeshService
    name: gateway
  default:
    appendModifications:
      - networkFilter:
          operation: Patch
          match:
            name: envoy.filters.network.http_connection_manager
            origin: gateway # you can also specify the name of the listener
          value: |
            name: envoy.filters.network.http_connection_manager
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
              streamIdleTimeout: 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.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: MeshProxyPatch
metadata:
  name: custom-template-1
  namespace: kong-mesh-system
spec:
  targetRef:
    kind: MeshService
    name: mesh-gateway_gateways_svc
  default:
    appendModifications:
      - httpFilter:
          operation: AddBefore
          match:
            name: envoy.filters.http.router
            origin: outbound
            listenerTags:
              kuma.io/service: offers
          value: |
            name: envoy.filters.http.lua
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
              inline_code: |
                function envoy_on_request(request_handle)
                  request_handle:headers():add("x-header", "test")
                end
type: MeshProxyPatch
mesh: default
name: backend-lua-filter
spec:
  targetRef:
    kind: MeshService
    name: mesh-gateway_gateways_svc
  default:
    appendModifications:
      - httpFilter:
          operation: AddBefore
          match:
            name: envoy.filters.http.router
            origin: outbound
            listenerTags:
              kuma.io/service: offers
          value: |
            name: envoy.filters.http.lua
            typedConfig:
              '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
              inline_code: |
                function envoy_on_request(request_handle)
                  request_handle:headers():add("x-header", "test")
                end
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023