Proxy Template

    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 policy can provide custom definitions of:

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

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

    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: '*'
    7. conf:
    8.   # `imports` allows us to reuse the dataplane configuration that Kuma
    9.   # generates automatically and add more customizations on top of it
    10.   imports:
    11.     # `default-proxy` is a reference name for the default
    12.     # data plane proxy configuration generated by Kuma
    13.     - default-proxy

    In these examples, note:

    • The selectors object specifies the data plane proxies that are targeted by the ProxyTemplate resource. Values are provided as Kuma tags.
    • The imports object specifies the reusable configuration that Kuma generates automatically. Kuma then extends the imports object with the custom configuration you specify. 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.

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

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

    Origin

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

    Available origins:

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

    Cluster

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

    • Universal
    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - cluster:
    15.           operation: add
    16.           value: |
    17.             name: test-cluster
    18.             connectTimeout: 5s
    19.             type: STATIC
    20.       - cluster:
    21.           operation: patch
    22.           match: # optional: if absent, all clusters will be patched
    23.             name: test-cluster # optional: if absent, all clusters regardless of name will be patched
    24.             origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
    25.           value: | # you can specify only part of cluster definition that will be merged into existing cluster
    26.             connectTimeout: 5s
    27.       - cluster:
    28.           operation: remove
    29.           match: # optional: if absent, all clusters will be removed
    30.             name: test-cluster # optional: if absent, all clusters regardless of name will be removed
    31.             origin: inbound # optional: if absent, all clusters regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - cluster:
    12.         operation: add
    13.         value: |
    14.           name: test-cluster
    15.           connectTimeout: 5s
    16.           type: STATIC
    17.     - cluster:
    18.         operation: patch
    19.         match: # optional: if absent, all clusters will be patched
    20.           name: test-cluster # optional: if absent, all clusters regardless of name will be patched
    21.           origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
    22.         value: | # you can specify only part of cluster definition that will be merged into existing cluster
    23.           connectTimeout: 5s
    24.     - cluster:
    25.         operation: remove
    26.         match: # optional: if absent, all clusters will be removed
    27.           name: test-cluster # optional: if absent, all clusters regardless of name will be removed
    28.           origin: inbound # optional: if absent, all clusters regardless of its origin will be removed

    Listener

    Modifications that are applied on Listeners resources.

    Available operations:

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

    Available matchers:

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

    • Universal
    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - listener:
    15.           operation: add
    16.           value: |
    17.             name: test-listener
    18.             address:
    19.               socketAddress:
    20.                 address: 192.168.0.1
    21.                 portValue: 8080
    22.       - listener:
    23.           operation: patch
    24.           match: # optional: if absent, all listeners will be patched
    25.             name: test-listener # optional: if absent, all listeners regardless of name will be patched
    26.             origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
    27.             tags: # optional: if absent, all listeners are matched
    28.               kuma.io/service: backend
    29.           value: | # you can specify only part of listener definition that will be merged into existing listener
    30.             continueOnListenerFiltersTimeout: true
    31.       - listener:
    32.           operation: remove
    33.           match: # optional: if absent, all listeners will be removed
    34.             name: test-listener # optional: if absent, all listeners regardless of name will be removed
    35.             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 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.

    • Universal
    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - networkFilter:
    15.           operation: addFirst
    16.           match: # optional: if absent, filter will be added to all listeners
    17.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    18.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    19.               kuma.io/service: backend
    20.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    21.           value: |
    22.             name: envoy.filters.network.local_ratelimit
    23.             typedConfig:
    24.               '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    25.               statPrefix: rateLimit
    26.               tokenBucket:
    27.                 fillInterval: 1s
    28.       - networkFilter:
    29.           operation: addLast
    30.           match: # optional: if absent, filter will be added to all listeners
    31.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    32.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    33.               kuma.io/service: backend
    34.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    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
    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: remove
    86.           match: # optional: if absent, all filters from all listeners will be removed
    87.             name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
    88.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    89.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    90.               kuma.io/service: backend
    91.             origin: inbound # optional: if absent, all filters regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - networkFilter:
    12.         operation: addFirst
    13.         match: # optional: if absent, filter will be added to all listeners
    14.           listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    15.           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: remove
    84.         match: # optional: if absent, all filters from all listeners will be removed
    85.           name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
    86.           listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    87.           listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    88.             kuma.io/service: backend
    89.           origin: inbound # optional: if absent, all filters regardless of its origin will be removed

    Example how to change streamIdleTimeout for MeshGateway:

    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: '*'
    10.   conf:
    11.     imports:
    12.       - gateway-proxy # default configuration for MeshGateway
    13.     modifications:
    14.       - networkFilter:
    15.           operation: patch
    16.           match:
    17.             name: envoy.filters.network.http_connection_manager
    18.             origin: gateway # you can also specify the name of the listener
    19.           value: |
    20.             name: envoy.filters.network.http_connection_manager
    21.             typedConfig:
    22.               '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
    23.               streamIdleTimeout: 15s

    HTTP Filter

    Modifications that are applied on HTTP Filters that are part of resource. Modifications that Kuma applies on all HTTP Connection Managers in the Listener.

    HTTP Filter modifications can only be applied on services .

    • 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

    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - httpFilter:
    15.           operation: addFirst
    16.           match: # optional: if absent, filter will be added to all HTTP Connection Managers
    17.             listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    18.             listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    19.               kuma.io/service: backend
    20.             origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    21.           value: |
    22.             name: envoy.filters.http.gzip
    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
    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: remove
    78.           match: # optional: if absent, all filters from all listeners will be removed
    79.             name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
    80.             listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    81.             listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    82.               kuma.io/service: backend
    83.             origin: inbound # optional: if absent, all filters regardless of its origin will be removed

    VirtualHost

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

    • Kubernetes

    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: custom-template-1
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy
    13.     modifications:
    14.       - virtualHost:
    15.           operation: add
    16.           value: |
    17.             name: backend
    18.             domains:
    19.             - "*"
    20.             routes:
    21.             - match:
    22.                 prefix: /
    23.               route:
    24.                 cluster: backend
    25.       - virtualHost:
    26.           operation: patch
    27.           match: # optional: if absent, all listeners will be patched
    28.             name: backend # optional: if absent, all virtual hosts regardless of name will be patched
    29.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
    30.             routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
    31.           value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
    32.             retryPolicy:
    33.               retryOn: 5xx
    34.               numRetries: 3
    35.       - virtualHost:
    36.           operation: remove
    37.           match: # optional: if absent, all virtual hosts will be removed
    38.             name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
    39.             origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed
    1. type: ProxyTemplate
    2. mesh: default
    3. name: custom-template-1
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy
    10.   modifications:
    11.     - virtualHost:
    12.         operation: add
    13.         value: |
    14.           name: backend
    15.           domains:
    16.           - "*"
    17.           routes:
    18.           - match:
    19.               prefix: /
    20.             route:
    21.               cluster: backend
    22.     - virtualHost:
    23.         operation: patch
    24.         match: # optional: if absent, all listeners will be patched
    25.           name: backend # optional: if absent, all virtual hosts regardless of name will be patched
    26.           origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
    27.           routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
    28.         value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
    29.           retryPolicy:
    30.             retryOn: 5xx
    31.             numRetries: 3
    32.     - virtualHost:
    33.         operation: remove
    34.         match: # optional: if absent, all virtual hosts will be removed
    35.           name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
    36.           origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed

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

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

    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.

    1. apiVersion: kuma.io/v1alpha1
    2. kind: ProxyTemplate
    3. mesh: default
    4. metadata:
    5.   name: backend-lua-filter
    6. spec:
    7.   selectors:
    8.     - match:
    9.         kuma.io/service: backend_default_svc_80
    10.   conf:
    11.     imports:
    12.       - default-proxy # apply modifications on top of resources generated by Kuma
    13.     modifications:
    14.       - httpFilter:
    15.           operation: addBefore
    16.           match:
    17.             name: envoy.filters.http.router
    18.             origin: outbound
    19.             listenerTags:
    20.               kuma.io/service: offers
    21.           value: |
    22.             name: envoy.filters.http.lua
    23.             typedConfig:
    24.               '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    25.               inline_code: |
    26.                 function envoy_on_request(request_handle)
    27.                   request_handle:headers():add("x-header", "test")
    28.                 end
    1. type: ProxyTemplate
    2. mesh: default
    3. name: backend-lua-filter
    4. selectors:
    5.   - match:
    6.       kuma.io/service: backend
    7. conf:
    8.   imports:
    9.     - default-proxy # apply modifications on top of resources generated by Kuma
    10.   modifications:
    11.     - httpFilter:
    12.         operation: addBefore
    13.         match:
    14.           name: envoy.filters.http.router
    15.           origin: outbound
    16.           listenerTags:
    17.             kuma.io/service: offers
    18.         value: |
    19.           name: envoy.filters.http.lua
    20.           typedConfig:
    21.             '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    22.             inline_code: |
    23.               function envoy_on_request(request_handle)
    24.                 request_handle:headers():add("x-header", "test")

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

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