# Proxy Template

The proxy template provides configuration options for low-level Envoy resources (opens new window) that Kuma policies do not directly expose.

If you need features that aren't available as a Kuma policy, open a new issue on GitHub (opens new window) so they can be added to the Kuma roadmap.

A ProxyTemplate policy can provide custom definitions of:

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

# Usage

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

    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. The value must be one or both of default-proxy -- the default configuration for non-ingress data planes -- or ingress -- the default configuration for zone-ingress proxy.

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

    # Cluster

    Modifications that are applied on Clusters (opens new window) 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.

      # Listener

      Modifications that are applied on Listeners (opens new window) 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.

        # Network Filter

        Modifications that are applied on Network Filters (opens new window) that are part of Listeners (opens new window) resource. Modifications are applied on all Filter Chains (opens new window) 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.
        • origin - origin of the listener.

          # HTTP Filter

          Modifications that are applied on HTTP Filters (opens new window) that are part of Listeners (opens new window) resource. Modifications are applied on all HTTP Connection Managers (opens new window) in the Listener.

          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
          • origin - origin of the listener

            # VirtualHost

            Modifications that are applied on VirtualHost (opens new window) resources.

            Available operations:

            • add - add a new VirtualHost.
            • remove - remove a VirtualHost.
            • patch - patch a part of VirtualHost definition.

            Available matchers:

              # How Kuma handles the proxy template

              At runtime, whenever kuma-cp generates the configuration for a given data plane proxy, 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 match either an inbound or a gateway definition of any data plane proxy accordingly to the Kuma Tags selected.
              3. 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).
              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.

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

                # Matching

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

                Last Updated: 11/22/2021, 4:36:48 PM