You are browsing unreleased documentation. See the latest documentation here.

Proxy Template

The proxy template 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 ProxyTemplate policy can provide custom definitions of:

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

Usage

Kong Mesh uses the following default ProxyTemplate resource for every data plane proxy (kuma-dp) that is added to a Mesh. This resource looks like:

Kubernetes

Universal

apiVersion: kuma.io/v1alpha1
kind: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: '*'
  conf:
    # `imports` allows us to reuse the dataplane configuration that Kong Mesh
    # generates automatically and add more customizations on top of it
    imports:
      # `default-proxy` is a reference name for the default
      # data plane proxy configuration generated by Kong Mesh
      - default-proxy

type: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: '*'
conf:
  # `imports` allows us to reuse the dataplane configuration that Kong Mesh
  # generates automatically and add more customizations on top of it
  imports:
    # `default-proxy` is a reference name for the default
    # data plane proxy configuration generated by Kong Mesh
    - default-proxy

In these examples, note:

The selectors object specifies the data plane proxies that are targeted by the ProxyTemplate resource. Values are provided as Kong Mesh tags.
The imports object specifies the reusable configuration that Kong Mesh generates automatically. Kong Mesh then extends the imports object with the custom configuration you specify. Possible values:
default-proxy - the default configuration for non-ingress data planes.
ingress-proxy - the default configuration for zone-ingress proxy.
gateway-proxy - the default configuration for mesh gateway.
egress-proxy - the default configuration for zone-egress proxy.

You can choose more than one import object.

Modifications

To customize the configuration of data plane proxies, you can combine modifications of any type in one ProxyTemplate. Each modification consists of the following sections:

operation - operation applied to the generated config (e.g. add, remove, patch).
match - some operations can be applied on matched resources (e.g. remove only resource of given name, patch all outbound resources).
value - raw Envoy xDS configuration. Can be partial if operation is patch.

Origin

All resources generated by Kong Mesh are marked with the origin value, so you can match resources. Examples: add new filters but only on inbound listeners, set timeouts on outbound clusters.

Available origins:

inbound - resources generated for incoming traffic.
outbound - resources generated for outgoing traffic.
transparent - resources generated for transparent proxy functionality.
prometheus - resources generated when Prometheus metrics are enabled.
direct-access - resources generated for Direct Access functionality.
ingress - resources generated for Zone Ingress.
gateway - resources generated for MeshGateway

Cluster

Modifications that are applied on Clusters resources.

Available operations:

add - add a new cluster or replace existing if the name is the same.
remove - remove a cluster.
patch - patch a part of cluster definition.

Available matchers:

name - name of the cluster.
origin - origin of the cluster.

Kubernetes

Universal

apiVersion: kuma.io/v1alpha1
kind: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy
    modifications:
      - 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: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - 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: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy
    modifications:
      - 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: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - 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: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy
    modifications:
      - 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: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - 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

Example how to change streamIdleTimeout for MeshGateway:

apiVersion: kuma.io/v1alpha1
kind: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: '*'
  conf:
    imports:
      - gateway-proxy # default configuration for MeshGateway
    modifications:
      - 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

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 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: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy
    modifications:
      - 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: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - 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: ProxyTemplate
mesh: default
metadata:
  name: custom-template-1
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy
    modifications:
      - 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: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - 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

How Kong Mesh handles the proxy template

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

Kong Mesh searches for all the ProxyTemplates resources that have been defined in the specified Mesh.
It loads in memory the ProxyTemplates resources whose selectors match either an inbound or a gateway definition of any data plane proxies accordingly to the Kong Mesh Tags selected.
Every matching ProxyTemplate is ranked. The ProxyTemplate resource with the highest ranking is used to generate the configuration for the specified data plane proxy (or proxies).
If the ProxyTemplate resource specifies an imports object, these resources are generated first.
If a ProxyTemplate defines a modification object, all modifications are applied, one by one in the order defined in modification section.

Lua filter example

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

Kubernetes

Universal

apiVersion: kuma.io/v1alpha1
kind: ProxyTemplate
mesh: default
metadata:
  name: backend-lua-filter
spec:
  selectors:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    imports:
      - default-proxy # apply modifications on top of resources generated by Kong Mesh
    modifications:
      - 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: ProxyTemplate
mesh: default
name: backend-lua-filter
selectors:
  - match:
      kuma.io/service: backend
conf:
  imports:
    - default-proxy # apply modifications on top of resources generated by Kong Mesh
  modifications:
    - 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

Matching

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

Builtin Gateway support

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

Schema

$schema: http://json-schema.org/draft-04/schema#

$ref: #/definitions/ProxyTemplate

definitions

ProxyTemplate

## Proxy Template
ProxyTemplate defines the desired state of ProxyTemplate
Type: object
This schema accepts additional properties.
Properties
- selectors
  - List of Dataplane selectors.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- conf
  - Configuration for ProxyTemplate
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Conf
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.ProxyTemplate.Conf
## Conf
Type: object
This schema accepts additional properties.
Properties
- imports
  - List of imported profiles. +optional
  - Type: array
    - Items
    - Type: string
- resources
  - List of raw xDS resources. +optional
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplateRawResource
- modifications
  - List of config modifications
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications kuma.mesh.v1alpha1.ProxyTemplate.Modifications
## Modifications
Modifications to xDS config generated by Proxy Template
Type: object
This schema accepts additional properties.
Properties
- cluster
  - Cluster modification
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Cluster
  - This schema accepts additional properties.
  - Properties
- listener
  - Listener modification
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Listener
  - This schema accepts additional properties.
  - Properties
- networkFilter
  - Network Filter modification
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.NetworkFilter
  - This schema accepts additional properties.
  - Properties
- httpFilter
  - HTTP Filter modification
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.HttpFilter
  - This schema accepts additional properties.
  - Properties
- virtualHost
  - Virtual Host modifications
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.VirtualHost
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Cluster
## Cluster
Cluster defines modifications to generated clusters
Type: object
This schema accepts additional properties.
Properties
- match
  - Only clusters that match will be modified
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Cluster.Match
  - This schema accepts additional properties.
  - Properties
- operation
  - Operation to apply on a cluster (add, remove, patch)
  - Type: string
- value
  - xDS cluster
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Cluster.Match
## Match
Match defines match for cluster
Type: object
This schema accepts additional properties.
Properties
- origin
  - Origin of the resource generation. (inbound, outbound, prometheus, transparent, ingress)
  - Type: string
- name
  - Name of the cluster to match
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.HttpFilter
## Http Filter
HttpFilter defines modifications to generated HTTP filters
Type: object
This schema accepts additional properties.
Properties
- match
  - Only HTTP filters that match will be modified
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.HttpFilter.Match
  - This schema accepts additional properties.
  - Properties
- operation
  - Operation to apply on network filter (addFirst, addLast, addBefore, addAfter, remove, patch)
  - Type: string
- value
  - xDS HTTP filter
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.HttpFilter.Match
## Match
Match defines match for http filter
Type: object
This schema accepts additional properties.
Properties
- origin
  - Origin of the resource generation. (inbound, outbound, prometheus, transparent, ingress)
  - Type: string
- name
  - Name of the network filter
  - Type: string
- listenerName
  - Name of the listener that http filter modifications will be applied to
  - Type: string
- listenerTags
  - ListenerTags available in Listener#Metadata#FilterMetadata[io.kuma.tags]
  - Type: object
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Listener
## Listener
Listener defines modification to generated listeners
Type: object
This schema accepts additional properties.
Properties
- match
  - Only listeners that match will be modified
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Listener.Match
  - This schema accepts additional properties.
  - Properties
- operation
  - Operation to apply on a listener (add, remove, patch)
  - Type: string
- value
  - xDS listener
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.Listener.Match
## Match
Match defines match for listener
Type: object
This schema accepts additional properties.
Properties
- origin
  - Origin of the resource generation. (inbound, outbound, prometheus, transparent, ingress)
  - Type: string
- name
  - Name of the listener to match
  - Type: string
- tags
  - Tags available in Listener#Metadata#FilterMetadata[io.kuma.tags]
  - Type: object
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.ProxyTemplate.Modifications.NetworkFilter
## Network Filter
Listener defines modification to generated network filters
Type: object
This schema accepts additional properties.
Properties
- match
  - Only network filters that match will be modified
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.NetworkFilter.Match
  - This schema accepts additional properties.
  - Properties
- operation
  - Operation to apply on network filter (addFirst, addLast, addBefore, addAfter, remove, patch)
  - Type: string
- value
  - xDS network filter
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.NetworkFilter.Match
## Match
Match defines match for network filter
Type: object
This schema accepts additional properties.
Properties
- origin
  - Origin of the resource generation. (inbound, outbound, prometheus, transparent, ingress)
  - Type: string
- name
  - Name of the network filter
  - Type: string
- listenerName
  - Name of the listener that network filter modifications will be applied to
  - Type: string
- listenerTags
  - ListenerTags available in Listener#Metadata#FilterMetadata[io.kuma.tags]
  - Type: object
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.ProxyTemplate.Modifications.VirtualHost
## Virtual Host
VirtualHost defines modification to generated virtual hosts
Type: object
This schema accepts additional properties.
Properties
- match
  - Only virtual hosts that match will be modified
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.ProxyTemplate.Modifications.VirtualHost.Match
  - This schema accepts additional properties.
  - Properties
- operation
  - Operation to apply on a virtual hosts (add, remove, patch)
  - Type: string
- value
  - xDS virtual host
  - Type: string kuma.mesh.v1alpha1.ProxyTemplate.Modifications.VirtualHost.Match
## Match
Match defines match for virtual host
Type: object
This schema accepts additional properties.
Properties
- origin
  - Origin of the resource generation. (inbound, outbound, prometheus, transparent, ingress)
  - Type: string
- name
  - Name of the virtual host to match
  - Type: string
- routeConfigurationName
  - Name of the route configuration
  - Type: string kuma.mesh.v1alpha1.ProxyTemplateRawResource
## Proxy Template Raw Resource
Type: object
This schema accepts additional properties.
Properties
- name
  - The resource's name, to distinguish it from others of the same type of resource.
  - Type: string
- version
  - The resource level version. It allows xDS to track the state of individual resources.
  - Type: string
- resource
  - xDS resource.
  - Type: string kuma.mesh.v1alpha1.Selector
## Selector
Selector defines structure for selecting tags for given dataplane
Type: object
This schema accepts additional properties.
Properties
- match
  - Tags to match, can be used for both source and destinations
  - Type: object
  - This schema accepts additional properties.
  - Properties

Generated with json-schema-md-doc Sun May 18 2025 11:58:01 GMT+0000 (Coordinated Universal Time)