# Proxy Template

This policy allows to configure low-level Envoy resources directly in those situations where Kuma-native policies do not expose the Envoy functionality we are looking for.

Please open a new issue on GitHub describing what missing functionality couldn't be found as a Kuma-native policy and we will make sure to prioritize it in the roadmap for future versions of Kuma.

Specifically by using the ProxyTemplate policy we can provide custom definitions of:

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

# Usage

By default Kuma uses the following default ProxyTemplate resource for every data plane proxy (kuma-dp, which embeds Envoy) that is being added to a Mesh. With a custom ProxyTemplate resource it is possible to extend or replace the default Envoy configuration that Kuma provides to every data plane proxy.

The default ProxyTemplate resource that by default Kuma applies to every data plane proxy looks like:

    In the examples described above, please note that:

    1. The selectors object allows us to determine what data plane proxies will be targeted by the ProxyTemplate resource (accordingly to the Kuma Tags specified).
    2. The imports object allows us to reuse the configuration that Kuma generates automatically so that it can be extended by our own custom configuration.

    The only available builtin configuration that can be used inside the imports section are:

    • default-proxy - default configuration for regular dataplanes.
    • ingress - default configuration for Ingress dataplanes.

    # Modifications

    In order to customize the configuration of a particular data plane proxy (or a group of data plane proxies), we can apply modifications. You can combine many modifications of any type within one ProxyTemplate. Each modification consists of the following sections:

    • operation - operation that will be applied on generated config (e.g. add, remove, patch).
    • match - some operation 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 origin value, so you can match resources by it. Examples: add new filters but only on inbound listeners, set timeouts on outbound clusters etc.

    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 Ingress Dataplane.

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

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

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

          # HTTP Filter

          Modifications that are applied on HTTP Filters that are part of Listeners resource. Modifications are applied on all HTTP Connection Managers 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 resources.

            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.

              # How is ProxyTemplate processed by Kuma

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

              1. Kuma will search for all the ProxyTemplates resources that have been defined in the specified Mesh.
              2. Then, it will load in memory those 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 will be then ranked. The ProxyTemplate resource with the highest ranking will be used to generate the configuration for that specific data plane proxy (or proxies).
              4. If the ProxyTemplate resource specifies an imports object, these resources will be generated first.
              5. If a ProxyTemplate defines a modification object, all modifications will be applied, one by one in order defined in modification section.

              # Examples

              Here we will show a more complete examples of ProxyTemplate.

              # Set timeouts

              In the future, Kuma will provide native timeouts settings. For now, you can patch Envoy resources to set them.

                # Lua filter

                Example of Lua filter that adds new header x-header: test on all outgoing HTTP requests.

                  # Retries

                  In the future, Kuma will provide native retries settings. For now, you can patch Envoy resources to set them.

                    Last Updated: 8/13/2020, 12:04:35 AM