1
2// This file was autogenerated by go-to-protobuf. Do not edit it manually!
3
4syntax = "proto2";
5
6package github.com.openshift.api.route.v1;
7
8import "k8s.io/api/core/v1/generated.proto";
9import "k8s.io/apimachinery/pkg/apis/meta/v1/generated.proto";
10import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
11import "k8s.io/apimachinery/pkg/util/intstr/generated.proto";
12
13// Package-wide variables from generator "generated".
14option go_package = "github.com/openshift/api/route/v1";
15
16// A route allows developers to expose services through an HTTP(S) aware load balancing and proxy
17// layer via a public DNS entry. The route may further specify TLS options and a certificate, or
18// specify a public CNAME that the router should also accept for HTTP and HTTPS traffic. An
19// administrator typically configures their router to be visible outside the cluster firewall, and
20// may also add additional security, caching, or traffic controls on the service content. Routers
21// usually talk directly to the service endpoints.
22//
23// Once a route is created, the `host` field may not be changed. Generally, routers use the oldest
24// route with a given host when resolving conflicts.
25//
26// Routers are subject to additional customization and may support additional controls via the
27// annotations field.
28//
29// Because administrators may configure multiple routers, the route status field is used to
30// return information to clients about the names and states of the route under each router.
31// If a client chooses a duplicate name, for instance, the route status conditions are used
32// to indicate the route cannot be chosen.
33//
34// To enable HTTP/2 ALPN on a route it requires a custom
35// (non-wildcard) certificate. This prevents connection coalescing by
36// clients, notably web browsers. We do not support HTTP/2 ALPN on
37// routes that use the default certificate because of the risk of
38// connection re-use/coalescing. Routes that do not have their own
39// custom certificate will not be HTTP/2 ALPN-enabled on either the
40// frontend or the backend.
41//
42// Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
43// +openshift:compatibility-gen:level=1
44message Route {
45 // metadata is the standard object's metadata.
46 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
47 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
48
49 // spec is the desired state of the route
50 optional RouteSpec spec = 2;
51
52 // status is the current state of the route
53 // +optional
54 optional RouteStatus status = 3;
55}
56
57// RouteIngress holds information about the places where a route is exposed.
58message RouteIngress {
59 // Host is the host string under which the route is exposed; this value is required
60 optional string host = 1;
61
62 // Name is a name chosen by the router to identify itself; this value is required
63 optional string routerName = 2;
64
65 // Conditions is the state of the route, may be empty.
66 repeated RouteIngressCondition conditions = 3;
67
68 // Wildcard policy is the wildcard policy that was allowed where this route is exposed.
69 optional string wildcardPolicy = 4;
70
71 // CanonicalHostname is the external host name for the router that can be used as a CNAME
72 // for the host requested for this route. This value is optional and may not be set in all cases.
73 optional string routerCanonicalHostname = 5;
74}
75
76// RouteIngressCondition contains details for the current condition of this route on a particular
77// router.
78message RouteIngressCondition {
79 // Type is the type of the condition.
80 // Currently only Admitted.
81 optional string type = 1;
82
83 // Status is the status of the condition.
84 // Can be True, False, Unknown.
85 optional string status = 2;
86
87 // (brief) reason for the condition's last transition, and is usually a machine and human
88 // readable constant
89 optional string reason = 3;
90
91 // Human readable message indicating details about last transition.
92 optional string message = 4;
93
94 // RFC 3339 date and time when this condition last transitioned
95 optional k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 5;
96}
97
98// RouteList is a collection of Routes.
99//
100// Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
101// +openshift:compatibility-gen:level=1
102message RouteList {
103 // metadata is the standard list's metadata.
104 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
105 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
106
107 // items is a list of routes
108 repeated Route items = 2;
109}
110
111// RoutePort defines a port mapping from a router to an endpoint in the service endpoints.
112message RoutePort {
113 // The target port on pods selected by the service this route points to.
114 // If this is a string, it will be looked up as a named port in the target
115 // endpoints port list. Required
116 optional k8s.io.apimachinery.pkg.util.intstr.IntOrString targetPort = 1;
117}
118
119// RouteSpec describes the hostname or path the route exposes, any security information,
120// and one to four backends (services) the route points to. Requests are distributed
121// among the backends depending on the weights assigned to each backend. When using
122// roundrobin scheduling the portion of requests that go to each backend is the backend
123// weight divided by the sum of all of the backend weights. When the backend has more than
124// one endpoint the requests that end up on the backend are roundrobin distributed among
125// the endpoints. Weights are between 0 and 256 with default 100. Weight 0 causes no requests
126// to the backend. If all weights are zero the route will be considered to have no backends
127// and return a standard 503 response.
128//
129// The `tls` field is optional and allows specific certificates or behavior for the
130// route. Routers typically configure a default certificate on a wildcard domain to
131// terminate routes without explicit certificates, but custom hostnames usually must
132// choose passthrough (send traffic directly to the backend via the TLS Server-Name-
133// Indication field) or provide a certificate.
134message RouteSpec {
135 // host is an alias/DNS that points to the service. Optional.
136 // If not specified a route name will typically be automatically
137 // chosen.
138 // Must follow DNS952 subdomain conventions.
139 //
140 // +optional
141 // +kubebuilder:validation:MaxLength=253
142 // +kubebuilder:validation:Pattern=`^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*$`
143 optional string host = 1;
144
145 // subdomain is a DNS subdomain that is requested within the ingress controller's
146 // domain (as a subdomain). If host is set this field is ignored. An ingress
147 // controller may choose to ignore this suggested name, in which case the controller
148 // will report the assigned name in the status.ingress array or refuse to admit the
149 // route. If this value is set and the server does not support this field host will
150 // be populated automatically. Otherwise host is left empty. The field may have
151 // multiple parts separated by a dot, but not all ingress controllers may honor
152 // the request. This field may not be changed after creation except by a user with
153 // the update routes/custom-host permission.
154 //
155 // Example: subdomain `frontend` automatically receives the router subdomain
156 // `apps.mycluster.com` to have a full hostname `frontend.apps.mycluster.com`.
157 //
158 // +optional
159 // +kubebuilder:validation:MaxLength=253
160 // +kubebuilder:validation:Pattern=`^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*$`
161 optional string subdomain = 8;
162
163 // path that the router watches for, to route traffic for to the service. Optional
164 //
165 // +optional
166 // +kubebuilder:validation:Pattern=`^/`
167 optional string path = 2;
168
169 // to is an object the route should use as the primary backend. Only the Service kind
170 // is allowed, and it will be defaulted to Service. If the weight field (0-256 default 100)
171 // is set to zero, no traffic will be sent to this backend.
172 optional RouteTargetReference to = 3;
173
174 // alternateBackends allows up to 3 additional backends to be assigned to the route.
175 // Only the Service kind is allowed, and it will be defaulted to Service.
176 // Use the weight field in RouteTargetReference object to specify relative preference.
177 //
178 // +kubebuilder:validation:MaxItems=3
179 repeated RouteTargetReference alternateBackends = 4;
180
181 // If specified, the port to be used by the router. Most routers will use all
182 // endpoints exposed by the service by default - set this value to instruct routers
183 // which port to use.
184 optional RoutePort port = 5;
185
186 // The tls field provides the ability to configure certificates and termination for the route.
187 optional TLSConfig tls = 6;
188
189 // Wildcard policy if any for the route.
190 // Currently only 'Subdomain' or 'None' is allowed.
191 //
192 // +kubebuilder:validation:Enum=None;Subdomain;""
193 // +kubebuilder:default=None
194 optional string wildcardPolicy = 7;
195}
196
197// RouteStatus provides relevant info about the status of a route, including which routers
198// acknowledge it.
199message RouteStatus {
200 // ingress describes the places where the route may be exposed. The list of
201 // ingress points may contain duplicate Host or RouterName values. Routes
202 // are considered live once they are `Ready`
203 repeated RouteIngress ingress = 1;
204}
205
206// RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service'
207// kind is allowed. Use 'weight' field to emphasize one over others.
208message RouteTargetReference {
209 // The kind of target that the route is referring to. Currently, only 'Service' is allowed
210 //
211 // +kubebuilder:validation:Enum=Service;""
212 // +kubebuilder:default=Service
213 optional string kind = 1;
214
215 // name of the service/target that is being referred to. e.g. name of the service
216 //
217 // +kubebuilder:validation:MinLength=1
218 optional string name = 2;
219
220 // weight as an integer between 0 and 256, default 100, that specifies the target's relative weight
221 // against other target reference objects. 0 suppresses requests to this backend.
222 //
223 // +optional
224 // +kubebuilder:validation:Minimum=0
225 // +kubebuilder:validation:Maximum=256
226 // +kubebuilder:default=100
227 optional int32 weight = 3;
228}
229
230// RouterShard has information of a routing shard and is used to
231// generate host names and routing table entries when a routing shard is
232// allocated for a specific route.
233// Caveat: This is WIP and will likely undergo modifications when sharding
234// support is added.
235message RouterShard {
236 // shardName uniquely identifies a router shard in the "set" of
237 // routers used for routing traffic to the services.
238 optional string shardName = 1;
239
240 // dnsSuffix for the shard ala: shard-1.v3.openshift.com
241 optional string dnsSuffix = 2;
242}
243
244// TLSConfig defines config used to secure a route and provide termination
245message TLSConfig {
246 // termination indicates termination type.
247 //
248 // * edge - TLS termination is done by the router and http is used to communicate with the backend (default)
249 // * passthrough - Traffic is sent straight to the destination without the router providing TLS termination
250 // * reencrypt - TLS termination is done by the router and https is used to communicate with the backend
251 //
252 // +kubebuilder:validation:Enum=edge;reencrypt;passthrough
253 optional string termination = 1;
254
255 // certificate provides certificate contents. This should be a single serving certificate, not a certificate
256 // chain. Do not include a CA certificate.
257 optional string certificate = 2;
258
259 // key provides key file contents
260 optional string key = 3;
261
262 // caCertificate provides the cert authority certificate contents
263 optional string caCertificate = 4;
264
265 // destinationCACertificate provides the contents of the ca certificate of the final destination. When using reencrypt
266 // termination this file should be provided in order to have routers use it for health checks on the secure connection.
267 // If this field is not specified, the router may provide its own destination CA and perform hostname validation using
268 // the short service name (service.namespace.svc), which allows infrastructure generated certificates to automatically
269 // verify.
270 optional string destinationCACertificate = 5;
271
272 // insecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. While
273 // each router may make its own decisions on which ports to expose, this is normally port 80.
274 //
275 // * Allow - traffic is sent to the server on the insecure port (default)
276 // * Disable - no traffic is allowed on the insecure port.
277 // * Redirect - clients are redirected to the secure port.
278 optional string insecureEdgeTerminationPolicy = 6;
279}
280
View as plain text