1// Copyright 2017 Istio Authors 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17import "google/api/field_behavior.proto"; 18 19// $schema: istio.networking.v1alpha3.Gateway 20// $title: Gateway 21// $description: Configuration affecting edge load balancer. 22// $location: https://istio.io/docs/reference/config/networking/gateway.html 23// $aliases: [/docs/reference/config/networking/v1alpha3/gateway] 24 25// `Gateway` describes a load balancer operating at the edge of the mesh 26// receiving incoming or outgoing HTTP/TCP connections. The specification 27// describes a set of ports that should be exposed, the type of protocol to 28// use, SNI configuration for the load balancer, etc. 29// 30// For example, the following Gateway configuration sets up a proxy to act 31// as a load balancer exposing port 80 and 9080 (http), 443 (https), 32// 9443(https) and port 2379 (TCP) for ingress. The gateway will be 33// applied to the proxy running on a pod with labels `app: 34// my-gateway-controller`. While Istio will configure the proxy to listen 35// on these ports, it is the responsibility of the user to ensure that 36// external traffic to these ports are allowed into the mesh. 37// 38// {{<tabset category-name="example">}} 39// {{<tab name="v1alpha3" category-value="v1alpha3">}} 40// ```yaml 41// apiVersion: networking.istio.io/v1alpha3 42// kind: Gateway 43// metadata: 44// name: my-gateway 45// namespace: some-config-namespace 46// spec: 47// selector: 48// app: my-gateway-controller 49// servers: 50// - port: 51// number: 80 52// name: http 53// protocol: HTTP 54// hosts: 55// - uk.bookinfo.com 56// - eu.bookinfo.com 57// tls: 58// httpsRedirect: true # sends 301 redirect for http requests 59// - port: 60// number: 443 61// name: https-443 62// protocol: HTTPS 63// hosts: 64// - uk.bookinfo.com 65// - eu.bookinfo.com 66// tls: 67// mode: SIMPLE # enables HTTPS on this port 68// serverCertificate: /etc/certs/servercert.pem 69// privateKey: /etc/certs/privatekey.pem 70// - port: 71// number: 9443 72// name: https-9443 73// protocol: HTTPS 74// hosts: 75// - "bookinfo-namespace/*.bookinfo.com" 76// tls: 77// mode: SIMPLE # enables HTTPS on this port 78// credentialName: bookinfo-secret # fetches certs from Kubernetes secret 79// - port: 80// number: 9080 81// name: http-wildcard 82// protocol: HTTP 83// hosts: 84// - "*" 85// - port: 86// number: 2379 # to expose internal service via external port 2379 87// name: mongo 88// protocol: MONGO 89// hosts: 90// - "*" 91// ``` 92// {{</tab>}} 93// 94// {{<tab name="v1beta1" category-value="v1beta1">}} 95// ```yaml 96// apiVersion: networking.istio.io/v1beta1 97// kind: Gateway 98// metadata: 99// name: my-gateway 100// namespace: some-config-namespace 101// spec: 102// selector: 103// app: my-gateway-controller 104// servers: 105// - port: 106// number: 80 107// name: http 108// protocol: HTTP 109// hosts: 110// - uk.bookinfo.com 111// - eu.bookinfo.com 112// tls: 113// httpsRedirect: true # sends 301 redirect for http requests 114// - port: 115// number: 443 116// name: https-443 117// protocol: HTTPS 118// hosts: 119// - uk.bookinfo.com 120// - eu.bookinfo.com 121// tls: 122// mode: SIMPLE # enables HTTPS on this port 123// serverCertificate: /etc/certs/servercert.pem 124// privateKey: /etc/certs/privatekey.pem 125// - port: 126// number: 9443 127// name: https-9443 128// protocol: HTTPS 129// hosts: 130// - "bookinfo-namespace/*.bookinfo.com" 131// tls: 132// mode: SIMPLE # enables HTTPS on this port 133// credentialName: bookinfo-secret # fetches certs from Kubernetes secret 134// - port: 135// number: 9080 136// name: http-wildcard 137// protocol: HTTP 138// hosts: 139// - "*" 140// - port: 141// number: 2379 # to expose internal service via external port 2379 142// name: mongo 143// protocol: MONGO 144// hosts: 145// - "*" 146// ``` 147// {{</tab>}} 148// {{</tabset>}} 149// 150// The Gateway specification above describes the L4-L6 properties of a load 151// balancer. A `VirtualService` can then be bound to a gateway to control 152// the forwarding of traffic arriving at a particular host or gateway port. 153// 154// For example, the following VirtualService splits traffic for 155// `https://uk.bookinfo.com/reviews`, `https://eu.bookinfo.com/reviews`, 156// `http://uk.bookinfo.com:9080/reviews`, 157// `http://eu.bookinfo.com:9080/reviews` into two versions (prod and qa) of 158// an internal reviews service on port 9080. In addition, requests 159// containing the cookie "user: dev-123" will be sent to special port 7777 160// in the qa version. The same rule is also applicable inside the mesh for 161// requests to the "reviews.prod.svc.cluster.local" service. This rule is 162// applicable across ports 443, 9080. Note that `http://uk.bookinfo.com` 163// gets redirected to `https://uk.bookinfo.com` (i.e. 80 redirects to 443). 164// 165// {{<tabset category-name="example">}} 166// {{<tab name="v1alpha3" category-value="v1alpha3">}} 167// ```yaml 168// apiVersion: networking.istio.io/v1alpha3 169// kind: VirtualService 170// metadata: 171// name: bookinfo-rule 172// namespace: bookinfo-namespace 173// spec: 174// hosts: 175// - reviews.prod.svc.cluster.local 176// - uk.bookinfo.com 177// - eu.bookinfo.com 178// gateways: 179// - some-config-namespace/my-gateway 180// - mesh # applies to all the sidecars in the mesh 181// http: 182// - match: 183// - headers: 184// cookie: 185// exact: "user=dev-123" 186// route: 187// - destination: 188// port: 189// number: 7777 190// host: reviews.qa.svc.cluster.local 191// - match: 192// - uri: 193// prefix: /reviews/ 194// route: 195// - destination: 196// port: 197// number: 9080 # can be omitted if it's the only port for reviews 198// host: reviews.prod.svc.cluster.local 199// weight: 80 200// - destination: 201// host: reviews.qa.svc.cluster.local 202// weight: 20 203// ``` 204// {{</tab>}} 205// 206// {{<tab name="v1beta1" category-value="v1beta1">}} 207// ```yaml 208// apiVersion: networking.istio.io/v1beta1 209// kind: VirtualService 210// metadata: 211// name: bookinfo-rule 212// namespace: bookinfo-namespace 213// spec: 214// hosts: 215// - reviews.prod.svc.cluster.local 216// - uk.bookinfo.com 217// - eu.bookinfo.com 218// gateways: 219// - some-config-namespace/my-gateway 220// - mesh # applies to all the sidecars in the mesh 221// http: 222// - match: 223// - headers: 224// cookie: 225// exact: "user=dev-123" 226// route: 227// - destination: 228// port: 229// number: 7777 230// host: reviews.qa.svc.cluster.local 231// - match: 232// - uri: 233// prefix: /reviews/ 234// route: 235// - destination: 236// port: 237// number: 9080 # can be omitted if it's the only port for reviews 238// host: reviews.prod.svc.cluster.local 239// weight: 80 240// - destination: 241// host: reviews.qa.svc.cluster.local 242// weight: 20 243// ``` 244// {{</tab>}} 245// {{</tabset>}} 246// 247// The following VirtualService forwards traffic arriving at (external) 248// port 27017 to internal Mongo server on port 5555. This rule is not 249// applicable internally in the mesh as the gateway list omits the 250// reserved name `mesh`. 251// 252// {{<tabset category-name="example">}} 253// {{<tab name="v1alpha3" category-value="v1alpha3">}} 254// ```yaml 255// apiVersion: networking.istio.io/v1alpha3 256// kind: VirtualService 257// metadata: 258// name: bookinfo-Mongo 259// namespace: bookinfo-namespace 260// spec: 261// hosts: 262// - mongosvr.prod.svc.cluster.local # name of internal Mongo service 263// gateways: 264// - some-config-namespace/my-gateway # can omit the namespace if gateway is in same 265// namespace as virtual service. 266// tcp: 267// - match: 268// - port: 27017 269// route: 270// - destination: 271// host: mongo.prod.svc.cluster.local 272// port: 273// number: 5555 274// ``` 275// {{</tab>}} 276// 277// {{<tab name="v1beta1" category-value="v1beta1">}} 278// ```yaml 279// apiVersion: networking.istio.io/v1beta1 280// kind: VirtualService 281// metadata: 282// name: bookinfo-Mongo 283// namespace: bookinfo-namespace 284// spec: 285// hosts: 286// - mongosvr.prod.svc.cluster.local # name of internal Mongo service 287// gateways: 288// - some-config-namespace/my-gateway # can omit the namespace if gateway is in same 289// namespace as virtual service. 290// tcp: 291// - match: 292// - port: 27017 293// route: 294// - destination: 295// host: mongo.prod.svc.cluster.local 296// port: 297// number: 5555 298// ``` 299// {{</tab>}} 300// {{</tabset>}} 301// 302// It is possible to restrict the set of virtual services that can bind to 303// a gateway server using the namespace/hostname syntax in the hosts field. 304// For example, the following Gateway allows any virtual service in the ns1 305// namespace to bind to it, while restricting only the virtual service with 306// foo.bar.com host in the ns2 namespace to bind to it. 307// 308// {{<tabset category-name="example">}} 309// {{<tab name="v1alpha3" category-value="v1alpha3">}} 310// ```yaml 311// apiVersion: networking.istio.io/v1alpha3 312// kind: Gateway 313// metadata: 314// name: my-gateway 315// namespace: some-config-namespace 316// spec: 317// selector: 318// app: my-gateway-controller 319// servers: 320// - port: 321// number: 80 322// name: http 323// protocol: HTTP 324// hosts: 325// - "ns1/*" 326// - "ns2/foo.bar.com" 327// ``` 328// {{</tab>}} 329// 330// {{<tab name="v1beta1" category-value="v1beta1">}} 331// ```yaml 332// apiVersion: networking.istio.io/v1beta1 333// kind: Gateway 334// metadata: 335// name: my-gateway 336// namespace: some-config-namespace 337// spec: 338// selector: 339// app: my-gateway-controller 340// servers: 341// - port: 342// number: 80 343// name: http 344// protocol: HTTP 345// hosts: 346// - "ns1/*" 347// - "ns2/foo.bar.com" 348// ``` 349// {{</tab>}} 350// {{</tabset>}} 351// 352package istio.networking.v1alpha3; 353 354option go_package = "istio.io/api/networking/v1alpha3"; 355 356// Gateway describes a load balancer operating at the edge of the mesh 357// receiving incoming or outgoing HTTP/TCP connections. 358// 359// <!-- crd generation tags 360// +cue-gen:Gateway:groupName:networking.istio.io 361// +cue-gen:Gateway:version:v1alpha3 362// +cue-gen:Gateway:storageVersion 363// +cue-gen:Gateway:annotations:helm.sh/resource-policy=keep 364// +cue-gen:Gateway:labels:app=istio-pilot,chart=istio,heritage=Tiller,release=istio 365// +cue-gen:Gateway:subresource:status 366// +cue-gen:Gateway:scope:Namespaced 367// +cue-gen:Gateway:resource:categories=istio-io,networking-istio-io,shortNames=gw 368// +cue-gen:Gateway:preserveUnknownFields:false 369// --> 370// 371// <!-- go code generation tags 372// +kubetype-gen 373// +kubetype-gen:groupVersion=networking.istio.io/v1alpha3 374// +genclient 375// +k8s:deepcopy-gen=true 376// --> 377message Gateway { 378 // A list of server specifications. 379 repeated Server servers = 1 [(google.api.field_behavior) = REQUIRED]; 380 381 // One or more labels that indicate a specific set of pods/VMs 382 // on which this gateway configuration should be applied. The scope of 383 // label search is restricted to the configuration namespace in which the 384 // the resource is present. In other words, the Gateway resource must 385 // reside in the same namespace as the gateway workload instance. 386 map<string, string> selector = 2 [(google.api.field_behavior) = REQUIRED]; 387} 388 389// `Server` describes the properties of the proxy on a given load balancer 390// port. For example, 391// 392// {{<tabset category-name="example">}} 393// {{<tab name="v1alpha3" category-value="v1alpha3">}} 394// ```yaml 395// apiVersion: networking.istio.io/v1alpha3 396// kind: Gateway 397// metadata: 398// name: my-ingress 399// spec: 400// selector: 401// app: my-ingress-gateway 402// servers: 403// - port: 404// number: 80 405// name: http2 406// protocol: HTTP2 407// hosts: 408// - "*" 409// ``` 410// {{</tab>}} 411// 412// {{<tab name="v1beta1" category-value="v1beta1">}} 413// ```yaml 414// apiVersion: networking.istio.io/v1beta1 415// kind: Gateway 416// metadata: 417// name: my-ingress 418// spec: 419// selector: 420// app: my-ingress-gateway 421// servers: 422// - port: 423// number: 80 424// name: http2 425// protocol: HTTP2 426// hosts: 427// - "*" 428// ``` 429// {{</tab>}} 430// {{</tabset>}} 431// 432// Another example 433// 434// {{<tabset category-name="example">}} 435// {{<tab name="v1alpha3" category-value="v1alpha3">}} 436// ```yaml 437// apiVersion: networking.istio.io/v1alpha3 438// kind: Gateway 439// metadata: 440// name: my-tcp-ingress 441// spec: 442// selector: 443// app: my-tcp-ingress-gateway 444// servers: 445// - port: 446// number: 27018 447// name: mongo 448// protocol: MONGO 449// hosts: 450// - "*" 451// ``` 452// {{</tab>}} 453// 454// {{<tab name="v1beta1" category-value="v1beta1">}} 455// ```yaml 456// apiVersion: networking.istio.io/v1beta1 457// kind: Gateway 458// metadata: 459// name: my-tcp-ingress 460// spec: 461// selector: 462// app: my-tcp-ingress-gateway 463// servers: 464// - port: 465// number: 27018 466// name: mongo 467// protocol: MONGO 468// hosts: 469// - "*" 470// ``` 471// {{</tab>}} 472// {{</tabset>}} 473// 474// The following is an example of TLS configuration for port 443 475// 476// {{<tabset category-name="example">}} 477// {{<tab name="v1alpha3" category-value="v1alpha3">}} 478// ```yaml 479// apiVersion: networking.istio.io/v1alpha3 480// kind: Gateway 481// metadata: 482// name: my-tls-ingress 483// spec: 484// selector: 485// app: my-tls-ingress-gateway 486// servers: 487// - port: 488// number: 443 489// name: https 490// protocol: HTTPS 491// hosts: 492// - "*" 493// tls: 494// mode: SIMPLE 495// serverCertificate: /etc/certs/server.pem 496// privateKey: /etc/certs/privatekey.pem 497// ``` 498// {{</tab>}} 499// 500// {{<tab name="v1beta1" category-value="v1beta1">}} 501// ```yaml 502// apiVersion: networking.istio.io/v1beta1 503// kind: Gateway 504// metadata: 505// name: my-tls-ingress 506// spec: 507// selector: 508// app: my-tls-ingress-gateway 509// servers: 510// - port: 511// number: 443 512// name: https 513// protocol: HTTPS 514// hosts: 515// - "*" 516// tls: 517// mode: SIMPLE 518// serverCertificate: /etc/certs/server.pem 519// privateKey: /etc/certs/privatekey.pem 520// ``` 521// {{</tab>}} 522// {{</tabset>}} 523// 524message Server { 525 // The Port on which the proxy should listen for incoming 526 // connections. 527 Port port = 1 [(google.api.field_behavior) = REQUIRED]; 528 529 // $hide_from_docs 530 // The ip or the Unix domain socket to which the listener should be bound 531 // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` 532 // (Linux abstract namespace). When using Unix domain sockets, the port 533 // number should be 0. 534 string bind = 4; 535 536 // One or more hosts exposed by this gateway. 537 // While typically applicable to 538 // HTTP services, it can also be used for TCP services using TLS with SNI. 539 // A host is specified as a `dnsName` with an optional `namespace/` prefix. 540 // The `dnsName` should be specified using FQDN format, optionally including 541 // a wildcard character in the left-most component (e.g., `prod/*.example.com`). 542 // Set the `dnsName` to `*` to select all `VirtualService` hosts from the 543 // specified namespace (e.g.,`prod/*`). 544 // 545 // The `namespace` can be set to `*` or `.`, representing any or the current 546 // namespace, respectively. For example, `*/foo.example.com` selects the 547 // service from any available namespace while `./foo.example.com` only selects 548 // the service from the namespace of the sidecar. The default, if no `namespace/` 549 // is specified, is `*/`, that is, select services from any namespace. 550 // Any associated `DestinationRule` in the selected namespace will also be used. 551 // 552 // A `VirtualService` must be bound to the gateway and must have one or 553 // more hosts that match the hosts specified in a server. The match 554 // could be an exact match or a suffix match with the server's hosts. For 555 // example, if the server's hosts specifies `*.example.com`, a 556 // `VirtualService` with hosts `dev.example.com` or `prod.example.com` will 557 // match. However, a `VirtualService` with host `example.com` or 558 // `newexample.com` will not match. 559 // 560 // NOTE: Only virtual services exported to the gateway's namespace 561 // (e.g., `exportTo` value of `*`) can be referenced. 562 // Private configurations (e.g., `exportTo` set to `.`) will not be 563 // available. Refer to the `exportTo` setting in `VirtualService`, 564 // `DestinationRule`, and `ServiceEntry` configurations for details. 565 repeated string hosts = 2 [(google.api.field_behavior) = REQUIRED]; 566 567 // Set of TLS related options that govern the server's behavior. Use 568 // these options to control if all http requests should be redirected to 569 // https, and the TLS modes to use. 570 ServerTLSSettings tls = 3; 571 572 // The loopback IP endpoint or Unix domain socket to which traffic should 573 // be forwarded to by default. Format should be `127.0.0.1:PORT` or 574 // `unix:///path/to/socket` or `unix://@foobar` (Linux abstract namespace). 575 // NOT IMPLEMENTED. 576 // $hide_from_docs 577 string default_endpoint = 5; 578} 579 580// Port describes the properties of a specific port of a service. 581message Port { 582 // A valid non-negative integer port number. 583 uint32 number = 1 [(google.api.field_behavior) = REQUIRED]; 584 585 // The protocol exposed on the port. 586 // MUST BE one of HTTP|HTTPS|GRPC|HTTP2|MONGO|TCP|TLS. 587 // TLS implies the connection will be routed based on the SNI header to 588 // the destination without terminating the TLS connection. 589 string protocol = 2 [(google.api.field_behavior) = REQUIRED]; 590 591 // Label assigned to the port. 592 string name = 3 [(google.api.field_behavior) = REQUIRED]; 593} 594 595message ServerTLSSettings { 596 // If set to true, the load balancer will send a 301 redirect for 597 // all http connections, asking the clients to use HTTPS. 598 bool https_redirect = 1; 599 600 // TLS modes enforced by the proxy 601 enum TLSmode { 602 // The SNI string presented by the client will be used as the 603 // match criterion in a VirtualService TLS route to determine 604 // the destination service from the service registry. 605 PASSTHROUGH = 0; 606 607 // Secure connections with standard TLS semantics. 608 SIMPLE = 1; 609 610 // Secure connections to the downstream using mutual TLS by 611 // presenting server certificates for authentication. 612 MUTUAL = 2; 613 614 // Similar to the passthrough mode, except servers with this TLS 615 // mode do not require an associated VirtualService to map from 616 // the SNI value to service in the registry. The destination 617 // details such as the service/subset/port are encoded in the 618 // SNI value. The proxy will forward to the upstream (Envoy) 619 // cluster (a group of endpoints) specified by the SNI 620 // value. This server is typically used to provide connectivity 621 // between services in disparate L3 networks that otherwise do 622 // not have direct connectivity between their respective 623 // endpoints. Use of this mode assumes that both the source and 624 // the destination are using Istio mTLS to secure traffic. 625 AUTO_PASSTHROUGH = 3; 626 627 // Secure connections from the downstream using mutual TLS by 628 // presenting server certificates for authentication. Compared 629 // to Mutual mode, this mode uses certificates, representing 630 // gateway workload identity, generated automatically by Istio 631 // for mTLS authentication. When this mode is used, all other 632 // fields in `TLSOptions` should be empty. 633 ISTIO_MUTUAL = 4; 634 }; 635 636 // Optional: Indicates whether connections to this port should be 637 // secured using TLS. The value of this field determines how TLS is 638 // enforced. 639 TLSmode mode = 2; 640 641 // REQUIRED if mode is `SIMPLE` or `MUTUAL`. The path to the file 642 // holding the server-side TLS certificate to use. 643 string server_certificate = 3; 644 645 // REQUIRED if mode is `SIMPLE` or `MUTUAL`. The path to the file 646 // holding the server's private key. 647 string private_key = 4; 648 649 // REQUIRED if mode is `MUTUAL`. The path to a file containing 650 // certificate authority certificates to use in verifying a presented 651 // client side certificate. 652 string ca_certificates = 5; 653 654 // For gateways running on Kubernetes, the name of the secret that 655 // holds the TLS certs including the CA certificates. Applicable 656 // only on Kubernetes, and only if the dynamic credential fetching 657 // feature is enabled in the proxy by setting 658 // `ISTIO_META_USER_SDS` metadata variable. The secret (of type 659 // `generic`) should contain the following keys and values: `key: 660 // <privateKey>`, `cert: <serverCert>`, `cacert: <CACertificate>`. 661 string credential_name = 10; 662 663 // A list of alternate names to verify the subject identity in the 664 // certificate presented by the client. 665 repeated string subject_alt_names = 6; 666 667 // An optional list of base64-encoded SHA-256 hashes of the SKPIs of 668 // authorized client certificates. 669 // Note: When both verify_certificate_hash and verify_certificate_spki 670 // are specified, a hash matching either value will result in the 671 // certificate being accepted. 672 repeated string verify_certificate_spki = 11; 673 674 // An optional list of hex-encoded SHA-256 hashes of the 675 // authorized client certificates. Both simple and colon separated 676 // formats are acceptable. 677 // Note: When both verify_certificate_hash and verify_certificate_spki 678 // are specified, a hash matching either value will result in the 679 // certificate being accepted. 680 repeated string verify_certificate_hash = 12; 681 682 // TLS protocol versions. 683 enum TLSProtocol { 684 // Automatically choose the optimal TLS version. 685 TLS_AUTO = 0; 686 687 // TLS version 1.0 688 TLSV1_0 = 1; 689 690 // TLS version 1.1 691 TLSV1_1 = 2; 692 693 // TLS version 1.2 694 TLSV1_2 = 3; 695 696 // TLS version 1.3 697 TLSV1_3 = 4; 698 } 699 700 // Optional: Minimum TLS protocol version. 701 TLSProtocol min_protocol_version = 7; 702 703 // Optional: Maximum TLS protocol version. 704 TLSProtocol max_protocol_version = 8; 705 706 // Optional: If specified, only support the specified cipher list. 707 // Otherwise default to the default cipher list supported by Envoy. 708 repeated string cipher_suites = 9; 709} 710