Proxy Template

This policy allows to configure low-level Envoy resourcesProxy Template - 图1 (opens new window) directly in those situations where Kuma-native policies do not expose the Envoy functionality we are looking for.

Please open a new issue on GitHubProxy Template - 图2 (opens new window) 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:

  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` allows us to reuse the dataplane configuration that Kuma
  12. # generates automatically and add more customizations on top of it
  13. imports:
  14. # `default-proxy` is a reference name for the default
  15. # data plane proxy configuration generated by Kuma
  16. - default-proxy
  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 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 ClustersProxy Template - 图8 (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.
  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
  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 ListenersProxy Template - 图9 (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.
  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
  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. 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: 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. - listener:
  12. operation: add
  13. value: |
  14. name: test-listener
  15. address:
  16. socketAddress:
  17. address: 192.168.0.1
  18. portValue: 8080
  19. - listener:
  20. operation: patch
  21. match: # optional: if absent, all listeners will be patched
  22. name: test-listener # optional: if absent, all listeners regardless of name will be patched
  23. origin: inbound # optional: if absent, all listeners regardless of its origin will be patched
  24. value: | # you can specify only part of listener definition that will be merged into existing listener
  25. continueOnListenerFiltersTimeout: true
  26. - listener:
  27. operation: remove
  28. match: # optional: if absent, all listeners will be removed
  29. name: test-listener # optional: if absent, all listeners regardless of name will be removed
  30. origin: inbound # optional: if absent, all listeners regardless of its origin will be removed

Network Filter

Modifications that are applied on Network FiltersProxy Template - 图10 (opens new window) that are part of ListenersProxy Template - 图11 (opens new window) resource. Modifications are applied on all Filter ChainsProxy Template - 图12 (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.
  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
  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. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  19. value: |
  20. name: envoy.filters.network.local_ratelimit
  21. typedConfig:
  22. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  23. statPrefix: rateLimit
  24. tokenBucket:
  25. fillInterval: 1s
  26. - networkFilter:
  27. operation: addLast
  28. match: # optional: if absent, filter will be added to all listeners
  29. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  30. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  31. value: |
  32. name: envoy.filters.network.local_ratelimit
  33. typedConfig:
  34. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  35. statPrefix: rateLimit
  36. tokenBucket:
  37. fillInterval: 1s
  38. - networkFilter:
  39. operation: addBefore
  40. match:
  41. 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.
  42. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  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/config.filter.network.local_rate_limit.v2alpha.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. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  57. value: |
  58. name: envoy.filters.network.local_ratelimit
  59. typedConfig:
  60. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  61. statPrefix: rateLimit
  62. tokenBucket:
  63. fillInterval: 1s
  64. - networkFilter:
  65. operation: patch
  66. match:
  67. name: envoy.filters.network.tcp_proxy
  68. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  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.network.tcp_proxy
  72. typedConfig:
  73. '@type': type.googleapis.com/envoy.config.filter.network.tcp_proxy.v2.TcpProxy
  74. idleTimeout: 10s
  75. - networkFilter:
  76. operation: remove
  77. match: # optional: if absent, all filters from all listeners will be removed
  78. name: envoy.filters.network.tcp_proxy # 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. 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. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  16. value: |
  17. name: envoy.filters.network.local_ratelimit
  18. typedConfig:
  19. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  20. statPrefix: rateLimit
  21. tokenBucket:
  22. fillInterval: 1s
  23. - networkFilter:
  24. operation: addLast
  25. match: # optional: if absent, filter will be added to all listeners
  26. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  27. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  28. value: |
  29. name: envoy.filters.network.local_ratelimit
  30. typedConfig:
  31. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  32. statPrefix: rateLimit
  33. tokenBucket:
  34. fillInterval: 1s
  35. - networkFilter:
  36. operation: addBefore
  37. match:
  38. 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.
  39. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  40. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  41. value: |
  42. name: envoy.filters.network.local_ratelimit
  43. typedConfig:
  44. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  45. statPrefix: rateLimit
  46. tokenBucket:
  47. fillInterval: 1s
  48. - networkFilter:
  49. operation: addAfter
  50. match:
  51. 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.
  52. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  53. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  54. value: |
  55. name: envoy.filters.network.local_ratelimit
  56. typedConfig:
  57. '@type': type.googleapis.com/config.filter.network.local_rate_limit.v2alpha.LocalRateLimit
  58. statPrefix: rateLimit
  59. tokenBucket:
  60. fillInterval: 1s
  61. - networkFilter:
  62. operation: patch
  63. match:
  64. name: envoy.filters.network.tcp_proxy
  65. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  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.network.tcp_proxy
  69. typedConfig:
  70. '@type': type.googleapis.com/envoy.config.filter.network.tcp_proxy.v2.TcpProxy
  71. idleTimeout: 10s
  72. - networkFilter:
  73. operation: remove
  74. match: # optional: if absent, all filters from all listeners will be removed
  75. name: envoy.filters.network.tcp_proxy # 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. origin: inbound # optional: if absent, all filters regardless of its origin will be removed

HTTP Filter

Modifications that are applied on HTTP FiltersProxy Template - 图13 (opens new window) that are part of ListenersProxy Template - 图14 (opens new window) resource. Modifications are applied on all HTTP Connection ManagersProxy Template - 图15 (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
  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
  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. 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.config.filter.http.gzip.v2.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. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  29. value: |
  30. name: envoy.filters.http.gzip
  31. typedConfig:
  32. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  33. memoryLevel: 9
  34. - httpFilter:
  35. operation: addBefore
  36. match:
  37. 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.
  38. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  39. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  40. value: |
  41. name: envoy.filters.http.gzip
  42. typedConfig:
  43. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  44. memoryLevel: 9
  45. - httpFilter:
  46. operation: addAfter
  47. match:
  48. 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.
  49. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  50. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  51. value: |
  52. name: envoy.filters.http.gzip
  53. typedConfig:
  54. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  55. memoryLevel: 9
  56. - httpFilter:
  57. operation: patch
  58. match:
  59. name: envoy.filters.http.router
  60. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  61. origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  62. value: | # you can specify only part of filter definition that will be merged into existing filter
  63. name: envoy.filters.http.router
  64. typedConfig:
  65. '@type': type.googleapis.com/envoy.config.filter.http.router.v2.Router
  66. dynamicStats: false
  67. - httpFilter:
  68. operation: remove
  69. match: # optional: if absent, all filters from all listeners will be removed
  70. name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
  71. listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  72. 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. - httpFilter:
  12. operation: addFirst
  13. match: # optional: if absent, filter will be added to all HTTP Connection Managers
  14. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  15. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  16. value: |
  17. name: envoy.filters.http.gzip
  18. typedConfig:
  19. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.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. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  26. value: |
  27. name: envoy.filters.http.gzip
  28. typedConfig:
  29. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  30. memoryLevel: 9
  31. - httpFilter:
  32. operation: addBefore
  33. match:
  34. 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.
  35. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  36. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  37. value: |
  38. name: envoy.filters.http.gzip
  39. typedConfig:
  40. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  41. memoryLevel: 9
  42. - httpFilter:
  43. operation: addAfter
  44. match:
  45. 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.
  46. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be added to all listeners regardless of name
  47. origin: inbound # optional: if absent, filter will be added to all listeners regardless of its origin
  48. value: |
  49. name: envoy.filters.http.gzip
  50. typedConfig:
  51. '@type': type.googleapis.com/envoy.config.filter.http.gzip.v2.Gzip
  52. memoryLevel: 9
  53. - httpFilter:
  54. operation: patch
  55. match:
  56. name: envoy.filters.http.router
  57. listenerName: inbound:127.0.0.0:80 # optional: if absent, filter will be patched within all listeners regardless of name
  58. origin: inbound # optional: if absent, filter will be patched within all listeners regardless of its origin
  59. value: | # you can specify only part of filter definition that will be merged into existing filter
  60. name: envoy.filters.http.router
  61. typedConfig:
  62. '@type': type.googleapis.com/envoy.config.filter.http.router.v2.Router
  63. dynamicStats: false
  64. - httpFilter:
  65. operation: remove
  66. match: # optional: if absent, all filters from all listeners will be removed
  67. name: envoy.filters.http.gzip # optional: if absent, all filters regardless of name will be removed
  68. listenerName: inbound:127.0.0.0:80 # optional: if absent, all filters regardless of the listener name will be removed
  69. origin: inbound # optional: if absent, all filters regardless of its origin will be removed

VirtualHost

Modifications that are applied on VirtualHostProxy Template - 图16 (opens new window) resources.

Available operations:

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

Available matchers:

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

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: ProxyTemplate
  3. mesh: default
  4. metadata:
  5. name: backend-timeouts
  6. spec:
  7. selectors:
  8. - match:
  9. kuma.io/service: backend
  10. conf:
  11. imports:
  12. - default-proxy # apply modifications on top of resources generated by Kuma
  13. modifications:
  14. - cluster:
  15. operation: patch
  16. match:
  17. origin: outbound
  18. value: |
  19. connectTimeout: 5s
  20. - networkFilter:
  21. operation: patch
  22. match:
  23. name: envoy.filters.network.http_connection_manager
  24. origin: outbound
  25. value: |
  26. name: envoy.filters.network.http_connection_manager
  27. typedConfig:
  28. '@type': type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
  29. streamIdleTimeout: 5s
  30. requestTimeout: 2s
  31. drainTimeout: 10s
  1. type: ProxyTemplate
  2. mesh: default
  3. name: backend-timeouts
  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. - cluster:
  12. operation: patch
  13. match:
  14. origin: outbound
  15. value: |
  16. connectTimeout: 5s
  17. - networkFilter:
  18. operation: patch
  19. match:
  20. name: envoy.filters.network.http_connection_manager
  21. origin: outbound
  22. value: |
  23. name: envoy.filters.network.http_connection_manager
  24. typedConfig:
  25. '@type': type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
  26. streamIdleTimeout: 5s
  27. requestTimeout: 2s
  28. drainTimeout: 10s

Lua filter

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

  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
  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. value: |
  20. name: envoy.filters.http.lua
  21. typedConfig:
  22. '@type': type.googleapis.com/envoy.config.filter.http.lua.v2.Lua
  23. inline_code: |
  24. function envoy_on_request(request_handle)
  25. request_handle:headers():add("x-header", "test")
  26. 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. value: |
  17. name: envoy.filters.http.lua
  18. typedConfig:
  19. '@type': type.googleapis.com/envoy.config.filter.http.lua.v2.Lua
  20. inline_code: |
  21. function envoy_on_request(request_handle)
  22. request_handle:headers():add("x-header", "test")
  23. end

Retries

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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: ProxyTemplate
  3. mesh: default
  4. metadata:
  5. name: retries
  6. spec:
  7. selectors:
  8. - match:
  9. kuma.io/service: backend
  10. conf:
  11. imports:
  12. - default-proxy # apply modifications on top of resources generated by Kuma
  13. modifications:
  14. - virtualHost:
  15. operation: patch
  16. match:
  17. origin: outbound
  18. value: |
  19. retryPolicy:
  20. retryOn: 5xx
  21. numRetries: 3
  22. - networkFilter:
  23. operation: patch
  24. match:
  25. name: envoy.filters.network.tcp_proxy
  26. origin: outbound
  27. value: |
  28. name: envoy.filters.network.tcp_proxy
  29. typedConfig:
  30. '@type': type.googleapis.com/envoy.config.filter.network.tcp_proxy.v2.TcpProxy
  31. maxConnectAttempts: 3
  1. type: ProxyTemplate
  2. mesh: default
  3. name: retries
  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. - virtualHost:
  12. operation: patch
  13. match:
  14. origin: outbound
  15. value: |
  16. retryPolicy:
  17. retryOn: 5xx
  18. numRetries: 3
  19. - networkFilter:
  20. operation: patch
  21. match:
  22. name: envoy.filters.network.tcp_proxy
  23. origin: outbound
  24. value: |
  25. name: envoy.filters.network.tcp_proxy
  26. typedConfig:
  27. '@type': type.googleapis.com/envoy.config.filter.network.tcp_proxy.v2.TcpProxy
  28. maxConnectAttempts: 3