1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package v1beta1 18 19 import ( 20 v1 "k8s.io/api/core/v1" 21 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 22 "k8s.io/apimachinery/pkg/util/intstr" 23 ) 24 25 // +genclient 26 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 27 // +k8s:prerelease-lifecycle-gen:introduced=1.14 28 // +k8s:prerelease-lifecycle-gen:deprecated=1.19 29 // +k8s:prerelease-lifecycle-gen:replacement=networking.k8s.io,v1,Ingress 30 31 // Ingress is a collection of rules that allow inbound connections to reach the 32 // endpoints defined by a backend. An Ingress can be configured to give services 33 // externally-reachable urls, load balance traffic, terminate SSL, offer name 34 // based virtual hosting etc. 35 type Ingress struct { 36 metav1.TypeMeta `json:",inline"` 37 38 // Standard object's metadata. 39 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 40 // +optional 41 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 42 43 // spec is the desired state of the Ingress. 44 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 45 // +optional 46 Spec IngressSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` 47 48 // status is the current state of the Ingress. 49 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 50 // +optional 51 Status IngressStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` 52 } 53 54 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 55 // +k8s:prerelease-lifecycle-gen:introduced=1.14 56 // +k8s:prerelease-lifecycle-gen:deprecated=1.19 57 // +k8s:prerelease-lifecycle-gen:replacement=networking.k8s.io,v1,IngressList 58 59 // IngressList is a collection of Ingress. 60 type IngressList struct { 61 metav1.TypeMeta `json:",inline"` 62 63 // Standard object's metadata. 64 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 65 // +optional 66 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 67 68 // items is the list of Ingress. 69 Items []Ingress `json:"items" protobuf:"bytes,2,rep,name=items"` 70 } 71 72 // IngressSpec describes the Ingress the user wishes to exist. 73 type IngressSpec struct { 74 // ingressClassName is the name of the IngressClass cluster resource. The 75 // associated IngressClass defines which controller will implement the 76 // resource. This replaces the deprecated `kubernetes.io/ingress.class` 77 // annotation. For backwards compatibility, when that annotation is set, it 78 // must be given precedence over this field. The controller may emit a 79 // warning if the field and annotation have different values. 80 // Implementations of this API should ignore Ingresses without a class 81 // specified. An IngressClass resource may be marked as default, which can 82 // be used to set a default value for this field. For more information, 83 // refer to the IngressClass documentation. 84 // +optional 85 IngressClassName *string `json:"ingressClassName,omitempty" protobuf:"bytes,4,opt,name=ingressClassName"` 86 87 // backend is the default backend capable of servicing requests that don't match any 88 // rule. At least one of 'backend' or 'rules' must be specified. This field 89 // is optional to allow the loadbalancer controller or defaulting logic to 90 // specify a global default. 91 // +optional 92 Backend *IngressBackend `json:"backend,omitempty" protobuf:"bytes,1,opt,name=backend"` 93 94 // tls represents the TLS configuration. Currently the Ingress only supports a 95 // single TLS port, 443. If multiple members of this list specify different hosts, 96 // they will be multiplexed on the same port according to the hostname specified 97 // through the SNI TLS extension, if the ingress controller fulfilling the 98 // ingress supports SNI. 99 // +optional 100 // +listType=atomic 101 TLS []IngressTLS `json:"tls,omitempty" protobuf:"bytes,2,rep,name=tls"` 102 103 // rules is a list of host rules used to configure the Ingress. If unspecified, or 104 // no rule matches, all traffic is sent to the default backend. 105 // +optional 106 // +listType=atomic 107 Rules []IngressRule `json:"rules,omitempty" protobuf:"bytes,3,rep,name=rules"` 108 // TODO: Add the ability to specify load-balancer IP through claims 109 } 110 111 // IngressTLS describes the transport layer security associated with an Ingress. 112 type IngressTLS struct { 113 // hosts is a list of hosts included in the TLS certificate. The values in 114 // this list must match the name/s used in the tlsSecret. Defaults to the 115 // wildcard host setting for the loadbalancer controller fulfilling this 116 // Ingress, if left unspecified. 117 // +optional 118 // +listType=atomic 119 Hosts []string `json:"hosts,omitempty" protobuf:"bytes,1,rep,name=hosts"` 120 121 // secretName is the name of the secret used to terminate TLS traffic on 122 // port 443. Field is left optional to allow TLS routing based on SNI 123 // hostname alone. If the SNI host in a listener conflicts with the "Host" 124 // header field used by an IngressRule, the SNI host is used for termination 125 // and value of the Host header is used for routing. 126 // +optional 127 SecretName string `json:"secretName,omitempty" protobuf:"bytes,2,opt,name=secretName"` 128 // TODO: Consider specifying different modes of termination, protocols etc. 129 } 130 131 // IngressStatus describes the current state of the Ingress. 132 type IngressStatus struct { 133 // loadBalancer contains the current status of the load-balancer. 134 // +optional 135 LoadBalancer IngressLoadBalancerStatus `json:"loadBalancer,omitempty" protobuf:"bytes,1,opt,name=loadBalancer"` 136 } 137 138 // LoadBalancerStatus represents the status of a load-balancer. 139 type IngressLoadBalancerStatus struct { 140 // ingress is a list containing ingress points for the load-balancer. 141 // +optional 142 // +listType=atomic 143 Ingress []IngressLoadBalancerIngress `json:"ingress,omitempty" protobuf:"bytes,1,rep,name=ingress"` 144 } 145 146 // IngressLoadBalancerIngress represents the status of a load-balancer ingress point. 147 type IngressLoadBalancerIngress struct { 148 // ip is set for load-balancer ingress points that are IP based. 149 // +optional 150 IP string `json:"ip,omitempty" protobuf:"bytes,1,opt,name=ip"` 151 152 // hostname is set for load-balancer ingress points that are DNS based. 153 // +optional 154 Hostname string `json:"hostname,omitempty" protobuf:"bytes,2,opt,name=hostname"` 155 156 // ports provides information about the ports exposed by this LoadBalancer. 157 // +listType=atomic 158 // +optional 159 Ports []IngressPortStatus `json:"ports,omitempty" protobuf:"bytes,4,rep,name=ports"` 160 } 161 162 // IngressPortStatus represents the error condition of a service port 163 type IngressPortStatus struct { 164 // port is the port number of the ingress port. 165 Port int32 `json:"port" protobuf:"varint,1,opt,name=port"` 166 167 // protocol is the protocol of the ingress port. 168 // The supported values are: "TCP", "UDP", "SCTP" 169 Protocol v1.Protocol `json:"protocol" protobuf:"bytes,2,opt,name=protocol,casttype=Protocol"` 170 171 // error is to record the problem with the service port 172 // The format of the error shall comply with the following rules: 173 // - built-in error values shall be specified in this file and those shall use 174 // CamelCase names 175 // - cloud provider specific error values must have names that comply with the 176 // format foo.example.com/CamelCase. 177 // --- 178 // The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) 179 // +optional 180 // +kubebuilder:validation:Required 181 // +kubebuilder:validation:Pattern=`^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$` 182 // +kubebuilder:validation:MaxLength=316 183 Error *string `json:"error,omitempty" protobuf:"bytes,3,opt,name=error"` 184 } 185 186 // IngressRule represents the rules mapping the paths under a specified host to 187 // the related backend services. Incoming requests are first evaluated for a host 188 // match, then routed to the backend associated with the matching IngressRuleValue. 189 type IngressRule struct { 190 // host is the fully qualified domain name of a network host, as defined by RFC 3986. 191 // Note the following deviations from the "host" part of the 192 // URI as defined in RFC 3986: 193 // 1. IPs are not allowed. Currently an IngressRuleValue can only apply to 194 // the IP in the Spec of the parent Ingress. 195 // 2. The `:` delimiter is not respected because ports are not allowed. 196 // Currently the port of an Ingress is implicitly :80 for http and 197 // :443 for https. 198 // Both these may change in the future. 199 // Incoming requests are matched against the host before the 200 // IngressRuleValue. If the host is unspecified, the Ingress routes all 201 // traffic based on the specified IngressRuleValue. 202 // 203 // host can be "precise" which is a domain name without the terminating dot of 204 // a network host (e.g. "foo.bar.com") or "wildcard", which is a domain name 205 // prefixed with a single wildcard label (e.g. "*.foo.com"). 206 // The wildcard character '*' must appear by itself as the first DNS label and 207 // matches only a single label. You cannot have a wildcard label by itself (e.g. Host == "*"). 208 // Requests will be matched against the Host field in the following way: 209 // 1. If Host is precise, the request matches this rule if the http host header is equal to Host. 210 // 2. If Host is a wildcard, then the request matches this rule if the http host header 211 // is to equal to the suffix (removing the first label) of the wildcard rule. 212 // +optional 213 Host string `json:"host,omitempty" protobuf:"bytes,1,opt,name=host"` 214 215 // IngressRuleValue represents a rule to route requests for this IngressRule. 216 // If unspecified, the rule defaults to a http catch-all. Whether that sends 217 // just traffic matching the host to the default backend or all traffic to the 218 // default backend, is left to the controller fulfilling the Ingress. Http is 219 // currently the only supported IngressRuleValue. 220 // +optional 221 IngressRuleValue `json:",inline,omitempty" protobuf:"bytes,2,opt,name=ingressRuleValue"` 222 } 223 224 // IngressRuleValue represents a rule to apply against incoming requests. If the 225 // rule is satisfied, the request is routed to the specified backend. Currently 226 // mixing different types of rules in a single Ingress is disallowed, so exactly 227 // one of the following must be set. 228 type IngressRuleValue struct { 229 //TODO: 230 // 1. Consider renaming this resource and the associated rules so they 231 // aren't tied to Ingress. They can be used to route intra-cluster traffic. 232 // 2. Consider adding fields for ingress-type specific global options 233 // usable by a loadbalancer, like http keep-alive. 234 235 // +optional 236 HTTP *HTTPIngressRuleValue `json:"http,omitempty" protobuf:"bytes,1,opt,name=http"` 237 } 238 239 // HTTPIngressRuleValue is a list of http selectors pointing to backends. 240 // In the example: http://<host>/<path>?<searchpart> -> backend where 241 // where parts of the url correspond to RFC 3986, this resource will be used 242 // to match against everything after the last '/' and before the first '?' 243 // or '#'. 244 type HTTPIngressRuleValue struct { 245 // paths is a collection of paths that map requests to backends. 246 // +listType=atomic 247 Paths []HTTPIngressPath `json:"paths" protobuf:"bytes,1,rep,name=paths"` 248 // TODO: Consider adding fields for ingress-type specific global 249 // options usable by a loadbalancer, like http keep-alive. 250 } 251 252 // PathType represents the type of path referred to by a HTTPIngressPath. 253 type PathType string 254 255 const ( 256 // PathTypeExact matches the URL path exactly and with case sensitivity. 257 PathTypeExact = PathType("Exact") 258 259 // PathTypePrefix matches based on a URL path prefix split by '/'. Matching 260 // is case sensitive and done on a path element by element basis. A path 261 // element refers to the list of labels in the path split by the '/' 262 // separator. A request is a match for path p if every p is an element-wise 263 // prefix of p of the request path. Note that if the last element of the 264 // path is a substring of the last element in request path, it is not a 265 // match (e.g. /foo/bar matches /foo/bar/baz, but does not match 266 // /foo/barbaz). If multiple matching paths exist in an Ingress spec, the 267 // longest matching path is given priority. 268 // Examples: 269 // - /foo/bar does not match requests to /foo/barbaz 270 // - /foo/bar matches request to /foo/bar and /foo/bar/baz 271 // - /foo and /foo/ both match requests to /foo and /foo/. If both paths are 272 // present in an Ingress spec, the longest matching path (/foo/) is given 273 // priority. 274 PathTypePrefix = PathType("Prefix") 275 276 // PathTypeImplementationSpecific matching is up to the IngressClass. 277 // Implementations can treat this as a separate PathType or treat it 278 // identically to Prefix or Exact path types. 279 PathTypeImplementationSpecific = PathType("ImplementationSpecific") 280 ) 281 282 // HTTPIngressPath associates a path with a backend. Incoming urls matching the 283 // path are forwarded to the backend. 284 type HTTPIngressPath struct { 285 // path is matched against the path of an incoming request. Currently it can 286 // contain characters disallowed from the conventional "path" part of a URL 287 // as defined by RFC 3986. Paths must begin with a '/' and must be present 288 // when using PathType with value "Exact" or "Prefix". 289 // +optional 290 Path string `json:"path,omitempty" protobuf:"bytes,1,opt,name=path"` 291 292 // pathType determines the interpretation of the path matching. PathType can 293 // be one of the following values: 294 // * Exact: Matches the URL path exactly. 295 // * Prefix: Matches based on a URL path prefix split by '/'. Matching is 296 // done on a path element by element basis. A path element refers is the 297 // list of labels in the path split by the '/' separator. A request is a 298 // match for path p if every p is an element-wise prefix of p of the 299 // request path. Note that if the last element of the path is a substring 300 // of the last element in request path, it is not a match (e.g. /foo/bar 301 // matches /foo/bar/baz, but does not match /foo/barbaz). 302 // * ImplementationSpecific: Interpretation of the Path matching is up to 303 // the IngressClass. Implementations can treat this as a separate PathType 304 // or treat it identically to Prefix or Exact path types. 305 // Implementations are required to support all path types. 306 // Defaults to ImplementationSpecific. 307 PathType *PathType `json:"pathType,omitempty" protobuf:"bytes,3,opt,name=pathType"` 308 309 // backend defines the referenced service endpoint to which the traffic 310 // will be forwarded to. 311 Backend IngressBackend `json:"backend" protobuf:"bytes,2,opt,name=backend"` 312 } 313 314 // IngressBackend describes all endpoints for a given service and port. 315 type IngressBackend struct { 316 // serviceName specifies the name of the referenced service. 317 // +optional 318 ServiceName string `json:"serviceName,omitempty" protobuf:"bytes,1,opt,name=serviceName"` 319 320 // servicePort Specifies the port of the referenced service. 321 // +optional 322 ServicePort intstr.IntOrString `json:"servicePort,omitempty" protobuf:"bytes,2,opt,name=servicePort"` 323 324 // resource is an ObjectRef to another Kubernetes resource in the namespace 325 // of the Ingress object. If resource is specified, serviceName and servicePort 326 // must not be specified. 327 // +optional 328 Resource *v1.TypedLocalObjectReference `json:"resource,omitempty" protobuf:"bytes,3,opt,name=resource"` 329 } 330 331 // +genclient 332 // +genclient:nonNamespaced 333 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 334 // +k8s:prerelease-lifecycle-gen:introduced=1.18 335 // +k8s:prerelease-lifecycle-gen:deprecated=1.19 336 // +k8s:prerelease-lifecycle-gen:replacement=networking.k8s.io,v1,IngressClassList 337 338 // IngressClass represents the class of the Ingress, referenced by the Ingress 339 // Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be 340 // used to indicate that an IngressClass should be considered default. When a 341 // single IngressClass resource has this annotation set to true, new Ingress 342 // resources without a class specified will be assigned this default class. 343 type IngressClass struct { 344 metav1.TypeMeta `json:",inline"` 345 346 // Standard object's metadata. 347 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 348 // +optional 349 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 350 351 // spec is the desired state of the IngressClass. 352 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 353 // +optional 354 Spec IngressClassSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` 355 } 356 357 // IngressClassSpec provides information about the class of an Ingress. 358 type IngressClassSpec struct { 359 // controller refers to the name of the controller that should handle this 360 // class. This allows for different "flavors" that are controlled by the 361 // same controller. For example, you may have different parameters for the 362 // same implementing controller. This should be specified as a 363 // domain-prefixed path no more than 250 characters in length, e.g. 364 // "acme.io/ingress-controller". This field is immutable. 365 Controller string `json:"controller,omitempty" protobuf:"bytes,1,opt,name=controller"` 366 367 // parameters is a link to a custom resource containing additional 368 // configuration for the controller. This is optional if the controller does 369 // not require extra parameters. 370 // +optional 371 Parameters *IngressClassParametersReference `json:"parameters,omitempty" protobuf:"bytes,2,opt,name=parameters"` 372 } 373 374 const ( 375 // IngressClassParametersReferenceScopeNamespace indicates that the 376 // referenced Parameters resource is namespace-scoped. 377 IngressClassParametersReferenceScopeNamespace = "Namespace" 378 // IngressClassParametersReferenceScopeCluster indicates that the 379 // referenced Parameters resource is cluster-scoped. 380 IngressClassParametersReferenceScopeCluster = "Cluster" 381 ) 382 383 // IngressClassParametersReference identifies an API object. This can be used 384 // to specify a cluster or namespace-scoped resource. 385 type IngressClassParametersReference struct { 386 // apiGroup is the group for the resource being referenced. If APIGroup is 387 // not specified, the specified Kind must be in the core API group. For any 388 // other third-party types, APIGroup is required. 389 // +optional 390 APIGroup *string `json:"apiGroup,omitempty" protobuf:"bytes,1,opt,name=aPIGroup"` 391 392 // kind is the type of resource being referenced. 393 Kind string `json:"kind" protobuf:"bytes,2,opt,name=kind"` 394 395 // name is the name of resource being referenced. 396 Name string `json:"name" protobuf:"bytes,3,opt,name=name"` 397 398 // scope represents if this refers to a cluster or namespace scoped resource. 399 // This may be set to "Cluster" (default) or "Namespace". 400 Scope *string `json:"scope" protobuf:"bytes,4,opt,name=scope"` 401 402 // namespace is the namespace of the resource being referenced. This field is 403 // required when scope is set to "Namespace" and must be unset when scope is set to 404 // "Cluster". 405 // +optional 406 Namespace *string `json:"namespace,omitempty" protobuf:"bytes,5,opt,name=namespace"` 407 } 408 409 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 410 // +k8s:prerelease-lifecycle-gen:introduced=1.18 411 // +k8s:prerelease-lifecycle-gen:deprecated=1.19 412 // +k8s:prerelease-lifecycle-gen:replacement=networking.k8s.io,v1,IngressClassList 413 414 // IngressClassList is a collection of IngressClasses. 415 type IngressClassList struct { 416 metav1.TypeMeta `json:",inline"` 417 // Standard list metadata. 418 // +optional 419 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 420 421 // items is the list of IngressClasses. 422 Items []IngressClass `json:"items" protobuf:"bytes,2,rep,name=items"` 423 } 424