MeshProxyPatch (beta)

    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 MeshProxyPatch policy can modify:

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

    To learn more about the information in this table, see the matching docs.

    MeshProxyPatch lets you specify modifications in appendModification block that can add a new resource, patch an existing resource or remove an existing resource.

    Each xDS resource modification consists of 3 fields:

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

    Origin

    All resources generated by Kuma are marked with the origin value, so you can match specific resources.

    Examples: add new filters but only on inbound listeners, set timeouts on outbound clusters.

    Well known origins:

    • inbound - resources generated for incoming traffic.
    • outbound - resources generated for outgoing traffic.
    • transparent - resources generated for transparent proxy functionality.
    • prometheus - resources generated for Prometheus to scrape when metrics on the Mesh is enabled.
    • direct-access - resources generated for Direct Access functionality.
    • gateway - resources generated for MeshGateway.

    The list is not complete, as policy plugins can introduce new resources. For example MeshTrace plugin can create Cluster with mesh-trace origin.

    Cluster

    Modifications that are applied on 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.
    • name - name of the Cluster.
    • origin - origin of the Cluster.

    • Kubernetes

    1. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: backend
    8. default:
    9. appendModifications:
    10. - cluster:
    11. operation: Add
    12. value: |
    13. name: test-cluster
    14. connectTimeout: 5s
    15. type: STATIC
    16. - cluster:
    17. operation: Patch
    18. match: # optional: if absent, all clusters will be patched
    19. name: test-cluster # optional: if absent, all clusters regardless of name will be patched
    20. origin: inbound # optional: if absent, all clusters regardless of its origin will be patched
    21. value: | # you can specify only part of cluster definition that will be merged into existing cluster
    22. connectTimeout: 5s
    23. - cluster:
    24. operation: Remove
    25. match: # optional: if absent, all clusters will be removed
    26. name: test-cluster # optional: if absent, all clusters regardless of name will be removed
    27. origin: inbound # optional: if absent, all clusters regardless of its origin will be removed

    Listener

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

    1. apiVersion: kuma.io/v1alpha1
    2. kind: MeshProxyPatch
    3. metadata:
    4. name: custom-template-1
    5. namespace: kuma-system
    6. spec:
    7. targetRef:
    8. kind: MeshService
    9. name: backend_default_svc_80
    10. default:
    11. appendModifications:
    12. - listener:
    13. operation: Add
    14. value: |
    15. name: test-listener
    16. address:
    17. socketAddress:
    18. address: 192.168.0.1
    19. portValue: 8080
    20. - listener:
    21. operation: Patch
    22. match: # optional: if absent, all listeners will be patched
    23. name: test-listener # optional: if absent, all listeners regardless of name will be patched
    24. origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
    25. tags: # optional: if absent, all listeners are matched
    26. kuma.io/service: backend
    27. value: | # you can specify only part of listener definition that will be merged into existing listener
    28. continueOnListenerFiltersTimeout: true
    29. - listener:
    30. operation: Remove
    31. match: # optional: if absent, all listeners will be removed
    32. name: test-listener # optional: if absent, all listeners regardless of name will be removed
    33. origin: inbound # optional: if absent, all listeners regardless of its origin will be removed
    1. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: backend
    8. default:
    9. appendModifications:
    10. - listener:
    11. operation: Add
    12. value: |
    13. name: test-listener
    14. address:
    15. socketAddress:
    16. address: 192.168.0.1
    17. portValue: 8080
    18. - listener:
    19. operation: Patch
    20. match: # optional: if absent, all listeners will be patched
    21. name: test-listener # optional: if absent, all listeners regardless of name will be patched
    22. origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
    23. tags: # optional: if absent, all listeners are matched
    24. kuma.io/service: backend
    25. value: | # you can specify only part of listener definition that will be merged into existing listener
    26. continueOnListenerFiltersTimeout: true
    27. - listener:
    28. operation: Remove
    29. match: # optional: if absent, all listeners will be removed
    30. name: test-listener # optional: if absent, all listeners regardless of name will be removed
    31. origin: inbound # optional: if absent, all listeners regardless of its origin will be removed

    Network Filter

    Modifications that are applied on that are part of Listeners resource. Modifications are applied on all 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

    1. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: backend
    8. default:
    9. appendModifications:
    10. - networkFilter:
    11. operation: AddFirst
    12. match: # optional: if absent, filter will be added to all listeners
    13. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    14. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    15. kuma.io/service: backend
    16. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    17. value: |
    18. name: envoy.filters.network.local_ratelimit
    19. typedConfig:
    20. '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    21. statPrefix: rateLimit
    22. tokenBucket:
    23. fillInterval: 1s
    24. - networkFilter:
    25. operation: AddLast
    26. match: # optional: if absent, filter will be added to all listeners
    27. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    28. kuma.io/service: backend
    29. value: |
    30. name: envoy.filters.network.local_ratelimit
    31. typedConfig:
    32. '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    33. statPrefix: rateLimit
    34. tokenBucket:
    35. fillInterval: 1s
    36. - networkFilter:
    37. operation: AddBefore
    38. match:
    39. 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.
    40. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    41. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    42. kuma.io/service: backend
    43. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    44. value: |
    45. name: envoy.filters.network.local_ratelimit
    46. typedConfig:
    47. '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    48. statPrefix: rateLimit
    49. tokenBucket:
    50. fillInterval: 1s
    51. - networkFilter:
    52. operation: AddAfter
    53. match:
    54. 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.
    55. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    56. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    57. kuma.io/service: backend
    58. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    59. value: |
    60. name: envoy.filters.network.local_ratelimit
    61. typedConfig:
    62. '@type': type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
    63. statPrefix: rateLimit
    64. tokenBucket:
    65. fillInterval: 1s
    66. - networkFilter:
    67. operation: Patch
    68. match:
    69. name: envoy.filters.network.tcp_proxy
    70. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    71. listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
    72. kuma.io/service: backend
    73. origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    74. value: | # you can specify only part of filter definition that will be merged into existing filter
    75. name: envoy.filters.network.tcp_proxy
    76. typedConfig:
    77. '@type': type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
    78. idleTimeout: 10s
    79. - networkFilter:
    80. operation: Remove
    81. match: # optional: if absent, all filters from all listeners will be removed
    82. name: envoy.filters.network.tcp_proxy # optional: if absent, all filters regardless of name will be removed
    83. listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    84. listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    85. kuma.io/service: backend
    86. origin: inbound # optional: if absent, all filters regardless of its origin will be removed

    HTTP Filter

    HTTP Filter modifications can only be applied on services .

    Available operations:

    • AddFirst - add a new filter as a first filter in HTTP Connection Manager.
    • AddLast - add a new filter as a last filter in HTTP Connection Manager.
    • AddAfter - add a new filter after other filter in HTTP Connection Manager that is matched using match section.
    • AddBefore - add a new filter before other filter in HTTP Connection Manager that is matched using match section.
    • Patch - patch a matched filter in HTTP Connection Manager.
    • Remove - remove a filter in HTTP Connection Manager.

    Available matchers:

    • name - name of the HTTP Filter.
    • listenerName - name of the Listener.
    • listenerTags - tags of inbound or outbound Listeners. They match Listener.metadata.filterMetadata[io.kuma.tags] in XDS configuration.
    • origin - origin of the Listener.

    • Kubernetes

    1. apiVersion: kuma.io/v1alpha1
    2. kind: MeshProxyPatch
    3. metadata:
    4. name: custom-template-1
    5. namespace: kuma-system
    6. spec:
    7. targetRef:
    8. kind: MeshService
    9. name: backend_default_svc_80
    10. default:
    11. appendModifications:
    12. - httpFilter:
    13. operation: AddFirst
    14. match: # optional: if absent, filter will be added to all HTTP Connection Managers
    15. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    16. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    17. kuma.io/service: backend
    18. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    19. value: |
    20. name: envoy.filters.http.gzip
    21. typedConfig:
    22. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    23. memoryLevel: 9
    24. - httpFilter:
    25. operation: AddLast
    26. match: # optional: if absent, filter will be added to all HTTP Connection Managers
    27. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    28. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    29. kuma.io/service: backend
    30. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    31. value: |
    32. name: envoy.filters.http.gzip
    33. typedConfig:
    34. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    35. memoryLevel: 9
    36. - httpFilter:
    37. operation: AddBefore
    38. match:
    39. 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.
    40. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    41. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    42. kuma.io/service: backend
    43. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    44. value: |
    45. name: envoy.filters.http.gzip
    46. typedConfig:
    47. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    48. memoryLevel: 9
    49. - httpFilter:
    50. operation: AddAfter
    51. match:
    52. 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.
    53. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    54. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    55. kuma.io/service: backend
    56. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    57. value: |
    58. name: envoy.filters.http.gzip
    59. typedConfig:
    60. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    61. memoryLevel: 9
    62. - httpFilter:
    63. operation: Patch
    64. match:
    65. name: envoy.filters.http.router
    66. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    67. listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
    68. kuma.io/service: backend
    69. origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    70. value: | # you can specify only part of filter definition that will be merged into existing filter
    71. name: envoy.filters.http.router
    72. typedConfig:
    73. '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
    74. dynamicStats: false
    75. - httpFilter:
    76. operation: Remove
    77. match: # optional: if absent, all filters from all listeners will be removed
    78. name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
    79. listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    80. listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    81. kuma.io/service: backend
    82. origin: inbound # optional: if absent, all filters regardless of its origin will be removed
    1. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: backend_default_svc_80
    8. default:
    9. appendModifications:
    10. - httpFilter:
    11. operation: AddFirst
    12. match: # optional: if absent, filter will be added to all HTTP Connection Managers
    13. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    14. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    15. kuma.io/service: backend
    16. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    17. value: |
    18. name: envoy.filters.http.gzip
    19. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    20. memoryLevel: 9
    21. - httpFilter:
    22. operation: AddLast
    23. match: # optional: if absent, filter will be added to all HTTP Connection Managers
    24. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    25. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    26. kuma.io/service: backend
    27. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    28. value: |
    29. name: envoy.filters.http.gzip
    30. typedConfig:
    31. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    32. memoryLevel: 9
    33. - httpFilter:
    34. operation: AddBefore
    35. match:
    36. 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.
    37. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    38. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    39. kuma.io/service: backend
    40. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    41. value: |
    42. name: envoy.filters.http.gzip
    43. typedConfig:
    44. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    45. memoryLevel: 9
    46. - httpFilter:
    47. operation: AddAfter
    48. match:
    49. 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.
    50. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
    51. listenerTags: # optional: if absent, filter will be added to all listeners regardless of listener tags
    52. kuma.io/service: backend
    53. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
    54. value: |
    55. name: envoy.filters.http.gzip
    56. typedConfig:
    57. '@type': type.googleapis.com/envoy.extensions.filters.http.gzip.v3.Gzip
    58. memoryLevel: 9
    59. - httpFilter:
    60. operation: Patch
    61. match:
    62. name: envoy.filters.http.router
    63. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
    64. listenerTags: # optional: if absent, filter will be patched within all listeners regardless of listener tags
    65. kuma.io/service: backend
    66. origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
    67. value: | # you can specify only part of filter definition that will be merged into existing filter
    68. name: envoy.filters.http.router
    69. typedConfig:
    70. '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
    71. dynamicStats: false
    72. - httpFilter:
    73. operation: Remove
    74. match: # optional: if absent, all filters from all listeners will be removed
    75. name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
    76. listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
    77. listenerTags: # optional: if absent, all filters regardless of the listener tags will be removed
    78. kuma.io/service: backend
    79. 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. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: backend
    8. default:
    9. appendModifications:
    10. - virtualHost:
    11. operation: Add
    12. value: |
    13. name: backend
    14. domains:
    15. - "*"
    16. routes:
    17. - match:
    18. prefix: /
    19. route:
    20. cluster: backend
    21. - virtualHost:
    22. operation: Patch
    23. match: # optional: if absent, all listeners will be patched
    24. name: backend # optional: if absent, all virtual hosts regardless of name will be patched
    25. origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be patched
    26. routeConfigurationName: outbound:backend # optional: if absent, all virtual hosts in all route configurations will be patched
    27. value: | # you can specify only part of virtual host definition that will be merged into existing virtual host
    28. retryPolicy:
    29. retryOn: 5xx
    30. numRetries: 3
    31. - virtualHost:
    32. operation: Remove
    33. match: # optional: if absent, all virtual hosts will be removed
    34. name: test-listener # optional: if absent, all virtual hsots regardless of name will be removed
    35. origin: inbound # optional: if absent, all virtual hosts regardless of its origin will be removed

    All modifications from appendModification list are always merged. For example, if there is a policy with targetRef.kind: Mesh and second policy with targetRef.kind: MeshService that matches a data plane proxy, all modifications from both policies will be applied.

    1. apiVersion: kuma.io/v1alpha1
    2. kind: MeshProxyPatch
    3. metadata:
    4. name: custom-template-1
    5. namespace: kuma-system
    6. spec:
    7. targetRef:
    8. kind: MeshService
    9. name: mesh-gateway_gateways_svc
    10. default:
    11. appendModifications:
    12. - networkFilter:
    13. operation: Patch
    14. match:
    15. name: envoy.filters.network.http_connection_manager
    16. origin: gateway # you can also specify the name of the listener
    17. value: |
    18. name: envoy.filters.network.http_connection_manager
    19. typedConfig:
    20. '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
    21. streamIdleTimeout: 15s
    1. type: MeshProxyPatch
    2. mesh: default
    3. name: custom-template-1
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: gateway
    8. default:
    9. appendModifications:
    10. - networkFilter:
    11. operation: Patch
    12. match:
    13. name: envoy.filters.network.http_connection_manager
    14. origin: gateway # you can also specify the name of the listener
    15. value: |
    16. name: envoy.filters.network.http_connection_manager
    17. typedConfig:
    18. '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
    19. streamIdleTimeout: 15s

    Here is and example of Lua filter that adds the new x-header: test header to all outgoing HTTP requests to service offers.

    1. type: MeshProxyPatch
    2. mesh: default
    3. name: backend-lua-filter
    4. spec:
    5. targetRef:
    6. kind: MeshService
    7. name: mesh-gateway_gateways_svc
    8. default:
    9. appendModifications:
    10. - httpFilter:
    11. operation: AddBefore
    12. match:
    13. name: envoy.filters.http.router
    14. origin: outbound
    15. listenerTags:
    16. kuma.io/service: offers
    17. value: |
    18. name: envoy.filters.http.lua
    19. typedConfig:
    20. '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    21. inline_code: |
    22. function envoy_on_request(request_handle)
    23. end