1syntax = "proto3";
2
3package envoy.extensions.filters.http.fault.v3;
4
5import "envoy/config/route/v3/route_components.proto";
6import "envoy/extensions/filters/common/fault/v3/fault.proto";
7import "envoy/type/v3/percent.proto";
8
9import "google/protobuf/wrappers.proto";
10
11import "udpa/annotations/status.proto";
12import "udpa/annotations/versioning.proto";
13import "validate/validate.proto";
14
15option java_package = "io.envoyproxy.envoy.extensions.filters.http.fault.v3";
16option java_outer_classname = "FaultProto";
17option java_multiple_files = true;
18option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/fault/v3;faultv3";
19option (udpa.annotations.file_status).package_version_status = ACTIVE;
20
21// [#protodoc-title: Fault Injection]
22// Fault Injection :ref:`configuration overview <config_http_filters_fault_injection>`.
23// [#extension: envoy.filters.http.fault]
24
25// [#next-free-field: 6]
26message FaultAbort {
27  option (udpa.annotations.versioning).previous_message_type =
28      "envoy.config.filter.http.fault.v2.FaultAbort";
29
30  // Fault aborts are controlled via an HTTP header (if applicable). See the
31  // :ref:`HTTP fault filter <config_http_filters_fault_injection_http_header>` documentation for
32  // more information.
33  message HeaderAbort {
34    option (udpa.annotations.versioning).previous_message_type =
35        "envoy.config.filter.http.fault.v2.FaultAbort.HeaderAbort";
36  }
37
38  reserved 1;
39
40  oneof error_type {
41    option (validate.required) = true;
42
43    // HTTP status code to use to abort the HTTP request.
44    uint32 http_status = 2 [(validate.rules).uint32 = {lt: 600 gte: 200}];
45
46    // gRPC status code to use to abort the gRPC request.
47    uint32 grpc_status = 5;
48
49    // Fault aborts are controlled via an HTTP header (if applicable).
50    HeaderAbort header_abort = 4;
51  }
52
53  // The percentage of requests/operations/connections that will be aborted with the error code
54  // provided.
55  type.v3.FractionalPercent percentage = 3;
56}
57
58// [#next-free-field: 16]
59message HTTPFault {
60  option (udpa.annotations.versioning).previous_message_type =
61      "envoy.config.filter.http.fault.v2.HTTPFault";
62
63  // If specified, the filter will inject delays based on the values in the
64  // object.
65  common.fault.v3.FaultDelay delay = 1;
66
67  // If specified, the filter will abort requests based on the values in
68  // the object. At least ``abort`` or ``delay`` must be specified.
69  FaultAbort abort = 2;
70
71  // Specifies the name of the (destination) upstream cluster that the
72  // filter should match on. Fault injection will be restricted to requests
73  // bound to the specific upstream cluster.
74  string upstream_cluster = 3;
75
76  // Specifies a set of headers that the filter should match on. The fault
77  // injection filter can be applied selectively to requests that match a set of
78  // headers specified in the fault filter config. The chances of actual fault
79  // injection further depend on the value of the :ref:`percentage
80  // <envoy_v3_api_field_extensions.filters.http.fault.v3.FaultAbort.percentage>` field.
81  // The filter will check the request's headers against all the specified
82  // headers in the filter config. A match will happen if all the headers in the
83  // config are present in the request with the same values (or based on
84  // presence if the ``value`` field is not in the config).
85  repeated config.route.v3.HeaderMatcher headers = 4;
86
87  // Faults are injected for the specified list of downstream hosts. If this
88  // setting is not set, faults are injected for all downstream nodes.
89  // Downstream node name is taken from :ref:`the HTTP
90  // x-envoy-downstream-service-node
91  // <config_http_conn_man_headers_downstream-service-node>` header and compared
92  // against downstream_nodes list.
93  repeated string downstream_nodes = 5;
94
95  // The maximum number of faults that can be active at a single time via the configured fault
96  // filter. Note that because this setting can be overridden at the route level, it's possible
97  // for the number of active faults to be greater than this value (if injected via a different
98  // route). If not specified, defaults to unlimited. This setting can be overridden via
99  // ``runtime <config_http_filters_fault_injection_runtime>`` and any faults that are not injected
100  // due to overflow will be indicated via the ``faults_overflow
101  // <config_http_filters_fault_injection_stats>`` stat.
102  //
103  // .. attention::
104  //   Like other :ref:`circuit breakers <arch_overview_circuit_break>` in Envoy, this is a fuzzy
105  //   limit. It's possible for the number of active faults to rise slightly above the configured
106  //   amount due to the implementation details.
107  google.protobuf.UInt32Value max_active_faults = 6;
108
109  // The response rate limit to be applied to the response body of the stream. When configured,
110  // the percentage can be overridden by the :ref:`fault.http.rate_limit.response_percent
111  // <config_http_filters_fault_injection_runtime>` runtime key.
112  //
113  // .. attention::
114  //  This is a per-stream limit versus a connection level limit. This means that concurrent streams
115  //  will each get an independent limit.
116  common.fault.v3.FaultRateLimit response_rate_limit = 7;
117
118  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
119  // runtime. The default is: fault.http.delay.fixed_delay_percent
120  string delay_percent_runtime = 8;
121
122  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
123  // runtime. The default is: fault.http.abort.abort_percent
124  string abort_percent_runtime = 9;
125
126  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
127  // runtime. The default is: fault.http.delay.fixed_duration_ms
128  string delay_duration_runtime = 10;
129
130  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
131  // runtime. The default is: fault.http.abort.http_status
132  string abort_http_status_runtime = 11;
133
134  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
135  // runtime. The default is: fault.http.max_active_faults
136  string max_active_faults_runtime = 12;
137
138  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
139  // runtime. The default is: fault.http.rate_limit.response_percent
140  string response_rate_limit_percent_runtime = 13;
141
142  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
143  // runtime. The default is: fault.http.abort.grpc_status
144  string abort_grpc_status_runtime = 14;
145
146  // To control whether stats storage is allocated dynamically for each downstream server.
147  // If set to true, "x-envoy-downstream-service-cluster" field of header will be ignored by this filter.
148  // If set to false, dynamic stats storage will be allocated for the downstream cluster name.
149  // Default value is false.
150  bool disable_downstream_cluster_stats = 15;
151}
152