generated from kubernetes/kubernetes-template-project
-
Notifications
You must be signed in to change notification settings - Fork 433
/
grpcroute_types.go
461 lines (426 loc) · 17.3 KB
/
grpcroute_types.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
/*
Copyright 2022 The Kubernetes Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package v1alpha2
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
// +genclient
// +kubebuilder:object:root=true
// +kubebuilder:resource:categories=gateway-api
// +kubebuilder:subresource:status
// +kubebuilder:storageversion
// +kubebuilder:printcolumn:name="Hostnames",type=string,JSONPath=`.spec.hostnames`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
// GRPCRoute provides a way to route gRPC requests. This includes the capability
// to match requests by hostname, gRPC service, gRPC method, or HTTP/2 header. Filters can be
// used to specify additional processing steps. Backends specify where matching
// requests should be routed.
//
// Implementations supporting `GRPCRoute` with the `HTTPS` `ProtocolType` must
// accept HTTP/2 connections without an initial upgrade from HTTP/1.1. If the
// implementation does not support this, then it should raise a "Detached"
// condition for the affected listener with a reason of "UnsupportedProtocol"
//
// Implementations supporting `GRPCRoute` with the `HTTP` `ProtocolType` must
// support cleartext HTTP/2 without an initial upgrade from HTTP/1.1. If the
// implementation does not support this, then it should raise a "Detached"
// condition for the affected listener with a reason of "UnsupportedProtocol"
//
// Support: Extended
type GRPCRoute struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
// Spec defines the desired state of GRPCRoute.
Spec GRPCRouteSpec `json:"spec,omitempty"`
// Status defines the current state of GRPCRoute.
Status GRPCRouteStatus `json:"status,omitempty"`
}
// +kubebuilder:object:root=true
// GRPCRouteList contains a list of GRPCRoute.
type GRPCRouteList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []GRPCRoute `json:"items"`
}
// GRPCRouteStatus defines the observed state of GRPCRoute.
type GRPCRouteStatus struct {
RouteStatus `json:",inline"`
}
// GRPCRouteSpec defines the desired state of GRPCRoute
type GRPCRouteSpec struct {
CommonRouteSpec `json:",inline"`
// Hostnames defines a set of hostname that should match against the GRPC
// Host header to select a GRPCRoute to process the request. This matches
// the RFC 1123 definition of a hostname with 2 notable exceptions:
//
// 1. IPs are not allowed.
// 2. A hostname may be prefixed with a wildcard label (`*.`). The wildcard
// label must appear by itself as the first label.
//
// If a hostname is specified by both the Listener and GRPCRoute, there
// must be at least one intersecting hostname for the GRPCRoute to be
// attached to the Listener. For example:
//
// * A Listener with `test.example.com` as the hostname matches GRPCRoutes
// that have either not specified any hostnames, or have specified at
// least one of `test.example.com` or `*.example.com`.
// * A Listener with `*.example.com` as the hostname matches GRPCRoutes
// that have either not specified any hostnames or have specified at least
// one hostname that matches the Listener hostname. For example,
// `test.example.com` and `*.example.com` would both match. On the other
// hand, `example.com` and `test.example.net` would not match.
//
// Hostnames that are prefixed with a wildcard label (`*.`) are interpreted
// as a suffix match. That means that a match for `*.example.com` would match
// both `test.example.com`, and `foo.test.example.com`, but not `example.com`.
//
// If both the Listener and GRPCRoute have specified hostnames, any
// GRPCRoute hostnames that do not match the Listener hostname MUST be
// ignored. For example, if a Listener specified `*.example.com`, and the
// GRPCRoute specified `test.example.com` and `test.example.net`,
// `test.example.net` must not be considered for a match.
//
// If both the Listener and GRPCRoute have specified hostnames, and none
// match with the criteria above, then the GRPCRoute is not accepted. The
// implementation must raise an 'Accepted' Condition with a status of
// `False` in the corresponding RouteParentStatus.
//
// If a Route (A) of type HTTPRoute or GRPCRoute is attached to a
// Listener and that listener already has another Route (B) of the other
// type attached and the intersection of the hostnames of A and B is
// non-empty, then the implementation must reject Route A. That is, the
// implementation must raise an 'Accepted' condition with a status of
// 'False' in the corresponding RouteParentStatus.
//
// Support: Core
//
// +optional
// +kubebuilder:validation:MaxItems=16
Hostnames []Hostname `json:"hostnames,omitempty"`
// Rules are a list of GRPC matchers, filters and actions.
//
// +optional
// +kubebuilder:validation:MaxItems=16
// +kubebuilder:default={{matches: {{method: {type: "Exact"}}}}}
Rules []GRPCRouteRule `json:"rules,omitempty"`
}
// GRPCRouteRule defines semantics for matching an gRPC request based on
// conditions (matches), processing it (filters), and forwarding the request to
// an API object (backendRefs).
type GRPCRouteRule struct {
// Matches define conditions used for matching the rule against incoming
// gRPC requests. Each match is independent, i.e. this rule will be matched
// if **any** one of the matches is satisfied.
//
// For example, take the following matches configuration:
//
// ```
// matches:
// - method:
// service: foo.bar
// headers:
// values:
// version: 2
// - method:
// service: foo.bar.v2
// ```
//
// For a request to match against this rule, a request should satisfy
// EITHER of the two conditions:
//
// - service of foo.bar AND contains the header `version: 2`
// - service of foo.bar.v2
//
// See the documentation for GRPCRouteMatch on how to specify multiple
// match conditions that should be ANDed together.
//
// If no matches are specified, the implementation must match every gRPC request.
//
// Proxy or Load Balancer routing configuration generated from GRPCRoutes
// MUST prioritize rules based on the following criteria, continuing on
// ties. Merging must not be done between GRPCRoutes and HTTPRoutes.
// Precedence must be given to the rule with the largest number of:
//
// * Characters in a matching non-wildcard hostname.
// * Characters in a matching hostname.
// * Characters in a matching service.
// * Characters in a matching method.
// * Header matches.
//
// If ties still exist across multiple Routes, matching precedence MUST be
// determined in order of the following criteria, continuing on ties:
//
// * The oldest Route based on creation timestamp.
// * The Route appearing first in alphabetical order by
// "{namespace}/{name}".
//
// If ties still exist within the Route that has been given precedence,
// matching precedence MUST be granted to the first matching rule meeting
// the above criteria.
//
// +optional
// +kubebuilder:validation:MaxItems=8
// +kubebuilder:default={{method: {type: "Exact"}}}
Matches []GRPCRouteMatch `json:"matches,omitempty"`
// Filters define the filters that are applied to requests that match
// this rule.
//
// The effects of ordering of multiple behaviors are currently unspecified.
// This can change in the future based on feedback during the alpha stage.
//
// Conformance-levels at this level are defined based on the type of filter:
//
// - ALL core filters MUST be supported by all implementations.
// - Implementers are encouraged to support extended filters.
// - Implementation-specific custom filters have no API guarantees across
// implementations.
//
// Specifying a core filter multiple times has unspecified or custom
// conformance.
// Support: Core
//
// +optional
// +kubebuilder:validation:MaxItems=16
Filters []GRPCRouteFilter `json:"filters,omitempty"`
// BackendRefs defines the backend(s) where matching requests should be
// sent.
//
// An `UNIMPLEMENTED` status MUST be returned if there are no BackendRefs or filters
// specified that would result in a response being sent.
//
// A BackendRef is considered invalid when it refers to:
//
// * an unknown or unsupported kind of resource
// * a resource that does not exist
// * a resource in another namespace when the reference has not been
// explicitly allowed by a ReferenceGrant (or equivalent concept).
//
// When a BackendRef is invalid, `UNIMPLEMENTED` statuses MUST be returned for
// requests that would have otherwise been routed to an invalid backend. If
// multiple backends are specified, and some are invalid, the proportion of
// requests that would otherwise have been routed to an invalid backend
// MUST receive an `UNIMPLEMENTED` status.
//
// When a BackendRef refers to a Service that has no ready endpoints, it is
// recommended to return an `UNAVAILABLE` status.
//
// Support: Core for Kubernetes Service
// Support: Custom for any other resource
//
// Support for weight: Core
//
// +optional
// +kubebuilder:validation:MaxItems=16
BackendRefs []GRPCBackendRef `json:"backendRefs,omitempty"`
}
// GRPCRouteMatch defines the predicate used to match requests to a given
// action. Multiple match types are ANDed together, i.e. the match will
// evaluate to true only if all conditions are satisfied.
//
// For example, the match below will match a gRPC request only if its service
// is `foo` AND it contains the `version: v1` header:
//
// “`
// matches:
// - method:
//
// type: Exact
// service: "foo"
// headers:
// - name: "version"
// value "v1"
//
// “`
type GRPCRouteMatch struct {
// Path specifies a gRPC request service/method matcher. If this field is not
// specified, all services and methods will match.
//
// +optional
// +kubebuilder:default={type: "Exact"}
Method *GRPCMethodMatch `json:"method,omitempty"`
// Headers specifies gRPC request header matchers. Multiple match values are
// ANDed together, meaning, a request must match all the specified headers
// to select the route.
//
// +listType=map
// +listMapKey=name
// +optional
// +kubebuilder:validation:MaxItems=16
Headers []GRPCHeaderMatch `json:"headers,omitempty"`
}
// GRPCMethodMatch describes how to select a gRPC route by matching the gRPC
// request service and/or method.
//
// At least one of Service and Method must be a non-empty string.
type GRPCMethodMatch struct {
// Type specifies how to match against the service and/or method.
// Support: Core (Exact with service and method specified)
//
// Support Custom (Exact with method specified but no service specified)
//
// Support: Custom (RegularExpression)
//
// +optional
// +kubebuilder:default=Exact
Type *GRPCMethodMatchType `json:"type,omitempty"`
// Value of the service to match against. If left empty or omitted, will
// match all services.
//
// At least one of Service and Method must be a non-empty string.
// +optional
// +kubebuilder:default=""
// +kubebuilder:validation:MaxLength=1024
Service *string `json:"service,omitempty"`
// Value of the method to match against. If left empty or omitted, will
// match all services.
//
// At least one of Service and Method must be a non-empty string.
// +optional
// +kubebuilder:default=""
// +kubebuilder:validation:MaxLength=1024
Method *string `json:"method,omitempty"`
}
// MethodMatchType specifies the semantics of how gRPC methods and services should be compared.
// Valid MethodMatchType values are:
//
// * "Exact"
// * "RegularExpression"
//
// Exact paths must be syntactically valid:
//
// - Must not contain `/` character
//
// +kubebuilder:validation:Enum=Exact;PathPrefix;RegularExpression
// +kubebuilder:validation:Enum=Exact;RegularExpression
type GRPCMethodMatchType string
// GRPCHeaderMatch describes how to select a gRPC route by matching gRPC request
// headers.
type GRPCHeaderMatch struct {
// Type specifies how to match against the value of the header.
//
// +optional
// +kubebuilder:default=Exact
Type *HeaderMatchType `json:"type,omitempty"`
// Name is the name of the gRPC Header to be matched.
//
// If multiple entries specify equivalent header names, only the first
// entry with an equivalent name MUST be considered for a match. Subsequent
// entries with an equivalent header name MUST be ignored. Due to the
// case-insensitivity of header names, "foo" and "Foo" are considered
// equivalent.
Name HeaderName `json:"name"`
// Value is the value of the gRPC Header to be matched.
//
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=4096
Value string `json:"value"`
}
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=256
// +kubebuilder:validation:Pattern=`^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$`
type HeaderName string
// GRPCRouteFilterType identifies a type of GRPCRoute filter.
type GRPCRouteFilterType string
// GRPCRouteFilter defines processing steps that must be completed during the
// request or response lifecycle. GRPCRouteFilters are meant as an extension
// point to express processing that may be done in Gateway implementations. Some
// examples include request or response modification, implementing
// authentication strategies, rate-limiting, and traffic shaping. API
// guarantee/conformance is defined based on the type of the filter.
type GRPCRouteFilter struct {
// Type identifies the type of filter to apply. As with other API fields,
// types are classified into three conformance levels:
//
// - Core: Filter types and their corresponding configuration defined by
// "Support: Core" in this package, e.g. "RequestHeaderModifier". All
// implementations must support core filters.
//
// - Extended: Filter types and their corresponding configuration defined by
// "Support: Extended" in this package, e.g. "RequestMirror". Implementers
// are encouraged to support extended filters.
//
// - Custom: Filters that are defined and supported by specific vendors.
// In the future, filters showing convergence in behavior across multiple
// implementations will be considered for inclusion in extended or core
// conformance levels. Filter-specific configuration for such filters
// is specified using the ExtensionRef field. `Type` should be set to
// "ExtensionRef" for custom filters.
//
// Implementers are encouraged to define custom implementation types to
// extend the core API with implementation-specific behavior.
//
// If a reference to a custom filter type cannot be resolved, the filter
// MUST NOT be skipped. Instead, requests that would have been processed by
// that filter MUST receive a HTTP error response.
//
// +unionDiscriminator
// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;ExtensionRef
// <gateway:experimental:validation:Enum=RequestHeaderModifier;RequestMirror;ExtensionRef>
Type GRPCRouteFilterType `json:"type"`
// RequestHeaderModifier defines a schema for a filter that modifies request
// headers.
//
// Support: Core
//
// +optional
RequestHeaderModifier *HTTPRequestHeaderFilter `json:"requestHeaderModifier,omitempty"`
// RequestMirror defines a schema for a filter that mirrors requests.
// Requests are sent to the specified destination, but responses from
// that destination are ignored.
//
// Support: Extended
//
// +optional
RequestMirror *HTTPRequestMirrorFilter `json:"requestMirror,omitempty"`
// ExtensionRef is an optional, implementation-specific extension to the
// "filter" behavior. For example, resource "myroutefilter" in group
// "networking.example.net"). ExtensionRef MUST NOT be used for core and
// extended filters.
//
// Support: Implementation-specific
//
// +optional
ExtensionRef *LocalObjectReference `json:"extensionRef,omitempty"`
}
// GRPCBackendRef defines how a GRPCRoute should forward a gRPC request.
type GRPCBackendRef struct {
// BackendRef is a reference to a backend to forward matched requests to.
//
// If the referent cannot be found, this GRPCBackendRef is invalid and must
// be dropped from the Gateway. The controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False` and not
// configure this backend in the underlying implementation.
//
// If there is a cross-namespace reference to an *existing* object
// that is not covered by a ReferencePolicy, the controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False`,
// with the "RefNotPermitted" reason and not configure this backend in the
// underlying implementation.
//
// In either error case, the Message of the `ResolvedRefs` Condition
// should be used to provide more detail about the problem.
//
// Support: Custom
//
// +optional
BackendRefs BackendRef `json:",inline"`
// Filters defined at this level should be executed if and only if the
// request is being forwarded to the backend defined here.
//
// Support: Custom (For broader support of filters, use the Filters field
// in GRPCRouteRule.)
//
// +optional
// +kubebuilder:validation:MaxItems=16
Filters []GRPCRouteFilter `json:"filters,omitempty"`
}