diff --git a/networking/v1alpha3/gateway.pb.go b/networking/v1alpha3/gateway.pb.go index bb744c66619..53ff90247ba 100644 --- a/networking/v1alpha3/gateway.pb.go +++ b/networking/v1alpha3/gateway.pb.go @@ -7,12 +7,12 @@ // use, SNI configuration for the load balancer, etc. // // For example, the following Gateway configuration sets up a proxy to act -// as a load balancer exposing port 80 and 9080 (http), 443 (https), and -// port 2379 (TCP) for ingress. The gateway will be applied to the proxy -// running on a pod with labels `app: my-gateway-controller`. While Istio -// will configure the proxy to listen on these ports, it is the -// responsibility of the user to ensure that external traffic to these -// ports are allowed into the mesh. +// as a load balancer exposing port 80 and 9080 (http), 443 (https), +// 9443(https) and port 2379 (TCP) for ingress. The gateway will be +// applied to the proxy running on a pod with labels `app: +// my-gateway-controller`. While Istio will configure the proxy to listen +// on these ports, it is the responsibility of the user to ensure that +// external traffic to these ports are allowed into the mesh. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 @@ -45,6 +45,15 @@ // serverCertificate: /etc/certs/servercert.pem // privateKey: /etc/certs/privatekey.pem // - port: +// number: 9443 +// name: https +// protocol: HTTPS +// hosts: +// - "bookinfo-namespace/*.bookinfo.com" +// tls: +// mode: SIMPLE # enables HTTPS on this port +// credentialName: bookinfo-secret # fetches certs from kubernetes secret +// - port: // number: 9080 // name: http-wildcard // protocol: HTTP @@ -57,6 +66,7 @@ // hosts: // - "*" // ``` +// // The Gateway specification above describes the L4-L6 properties of a load // balancer. A `VirtualService` can then be bound to a gateway to control // the forwarding of traffic arriving at a particular host or gateway port. @@ -136,6 +146,32 @@ // port: // number: 5555 // ``` +// +// It is possible to restrict the set of virtual services that can bind to +// a gateway server using the namespace/hostname syntax in the hosts field. +// For example, the following Gateway allows any virtual service in the ns1 +// namespace to bind to it, while restricting only the virtual service with +// foo.bar.com host in the ns2 namespace to bind to it. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Gateway +// metadata: +// name: my-gateway +// namespace: some-config-namespace +// spec: +// selector: +// app: my-gateway-controller +// servers: +// - port: +// number: 80 +// name: http +// protocol: HTTP +// hosts: +// - "ns1/*" +// - "ns2/foo.bar.com" +// ``` +// package v1alpha3 @@ -369,13 +405,13 @@ func (m *Gateway) GetSelector() map[string]string { // ``` type Server struct { // REQUIRED: The Port on which the proxy should listen for incoming - // connections. If using Unix domain socket, use 0 as the port number, - // with a valid protocol and port name, along with the bind parameter. + // connections. Port *Port `protobuf:"bytes,1,opt,name=port,proto3" json:"port,omitempty"` // $hide_from_docs // The ip or the Unix domain socket to which the listener should be bound - // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` (Linux - // abstract namespace). + // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` + // (Linux abstract namespace). When using unix domain sockets, the port + // number should be 0. Bind string `protobuf:"bytes,4,opt,name=bind,proto3" json:"bind,omitempty"` // REQUIRED. One or more hosts exposed by this gateway. // While typically applicable to @@ -502,18 +538,21 @@ type Server_TLSOptions struct { // client side certificate. CaCertificates string `protobuf:"bytes,5,opt,name=ca_certificates,json=caCertificates,proto3" json:"ca_certificates,omitempty"` // The credentialName stands for a unique identifier that can be used - // to identify the serverCertificate and the privateKey. The credentialName - // appended with suffix "-cacert" is used to identify the CaCertificates - // associated with this server. Gateway workloads capable of fetching - // credentials from a remote credential store will be configured to retrieve - // the serverCertificate and the privateKey using credentialName, instead of - // using the file system paths specified above. If using mutual TLS, + // to identify the serverCertificate and the privateKey. The + // credentialName appended with suffix "-cacert" is used to identify + // the CaCertificates associated with this server. Gateway workloads + // capable of fetching credentials from a remote credential store such + // as kubernetes secrets, will be configured to retrieve the + // serverCertificate and the privateKey using credentialName, instead + // of using the file system paths specified above. If using mutual TLS, // gateway workloads will retrieve the CaCertificates using - // credentialName-cacert. The semantics of the name are platform dependent. - // In Kubernetes, the default Istio supplied credential server expects the - // credentialName to match the name of the Kubernetes secret that holds the - // server certificate, the private key, and the CA certificate - // (if using mutual TLS). + // credentialName-cacert. The semantics of the name are platform + // dependent. In Kubernetes, the default Istio supplied credential + // server expects the credentialName to match the name of the + // Kubernetes secret that holds the server certificate, the private + // key, and the CA certificate (if using mutual TLS). Set the + // ISTIO_META_USER_SDS metadata variable in the gateway's proxy to + // enable the dynamic credential fetching feature. CredentialName string `protobuf:"bytes,10,opt,name=credential_name,json=credentialName,proto3" json:"credential_name,omitempty"` // A list of alternate names to verify the subject identity in the // certificate presented by the client. diff --git a/networking/v1alpha3/gateway.pb.html b/networking/v1alpha3/gateway.pb.html index a497747de16..2e8bd131e75 100644 --- a/networking/v1alpha3/gateway.pb.html +++ b/networking/v1alpha3/gateway.pb.html @@ -12,12 +12,12 @@ use, SNI configuration for the load balancer, etc.

For example, the following Gateway configuration sets up a proxy to act -as a load balancer exposing port 80 and 9080 (http), 443 (https), and -port 2379 (TCP) for ingress. The gateway will be applied to the proxy -running on a pod with labels app: my-gateway-controller. While Istio -will configure the proxy to listen on these ports, it is the -responsibility of the user to ensure that external traffic to these -ports are allowed into the mesh.

+as a load balancer exposing port 80 and 9080 (http), 443 (https), +9443(https) and port 2379 (TCP) for ingress. The gateway will be +applied to the proxy running on a pod with labels app: +my-gateway-controller. While Istio will configure the proxy to listen +on these ports, it is the responsibility of the user to ensure that +external traffic to these ports are allowed into the mesh.

apiVersion: networking.istio.io/v1alpha3
 kind: Gateway
@@ -48,6 +48,15 @@
       mode: SIMPLE # enables HTTPS on this port
       serverCertificate: /etc/certs/servercert.pem
       privateKey: /etc/certs/privatekey.pem
+  - port:
+      number: 9443
+      name: https
+      protocol: HTTPS
+    hosts:
+    - "bookinfo-namespace/*.bookinfo.com"
+    tls:
+      mode: SIMPLE # enables HTTPS on this port
+      credentialName: bookinfo-secret # fetches certs from kubernetes secret
   - port:
       number: 9080
       name: http-wildcard
@@ -140,6 +149,30 @@
           number: 5555
+

It is possible to restrict the set of virtual services that can bind to +a gateway server using the namespace/hostname syntax in the hosts field. +For example, the following Gateway allows any virtual service in the ns1 +namespace to bind to it, while restricting only the virtual service with +foo.bar.com host in the ns2 namespace to bind to it.

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: my-gateway
+  namespace: some-config-namespace
+spec:
+  selector:
+    app: my-gateway-controller
+  servers:
+  - port:
+      number: 80
+      name: http
+      protocol: HTTP
+    hosts:
+    - "ns1/*"
+    - "ns2/foo.bar.com"
+
+

Gateway

@@ -292,8 +325,7 @@

Server

@@ -414,18 +446,21 @@

Server.TLSOptions

diff --git a/networking/v1alpha3/gateway.proto b/networking/v1alpha3/gateway.proto index c943b3ff2ce..ea314aa192c 100644 --- a/networking/v1alpha3/gateway.proto +++ b/networking/v1alpha3/gateway.proto @@ -24,12 +24,12 @@ syntax = "proto3"; // use, SNI configuration for the load balancer, etc. // // For example, the following Gateway configuration sets up a proxy to act -// as a load balancer exposing port 80 and 9080 (http), 443 (https), and -// port 2379 (TCP) for ingress. The gateway will be applied to the proxy -// running on a pod with labels `app: my-gateway-controller`. While Istio -// will configure the proxy to listen on these ports, it is the -// responsibility of the user to ensure that external traffic to these -// ports are allowed into the mesh. +// as a load balancer exposing port 80 and 9080 (http), 443 (https), +// 9443(https) and port 2379 (TCP) for ingress. The gateway will be +// applied to the proxy running on a pod with labels `app: +// my-gateway-controller`. While Istio will configure the proxy to listen +// on these ports, it is the responsibility of the user to ensure that +// external traffic to these ports are allowed into the mesh. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 @@ -62,6 +62,15 @@ syntax = "proto3"; // serverCertificate: /etc/certs/servercert.pem // privateKey: /etc/certs/privatekey.pem // - port: +// number: 9443 +// name: https +// protocol: HTTPS +// hosts: +// - "bookinfo-namespace/*.bookinfo.com" +// tls: +// mode: SIMPLE # enables HTTPS on this port +// credentialName: bookinfo-secret # fetches certs from kubernetes secret +// - port: // number: 9080 // name: http-wildcard // protocol: HTTP @@ -74,6 +83,7 @@ syntax = "proto3"; // hosts: // - "*" // ``` +// // The Gateway specification above describes the L4-L6 properties of a load // balancer. A `VirtualService` can then be bound to a gateway to control // the forwarding of traffic arriving at a particular host or gateway port. @@ -153,6 +163,32 @@ syntax = "proto3"; // port: // number: 5555 // ``` +// +// It is possible to restrict the set of virtual services that can bind to +// a gateway server using the namespace/hostname syntax in the hosts field. +// For example, the following Gateway allows any virtual service in the ns1 +// namespace to bind to it, while restricting only the virtual service with +// foo.bar.com host in the ns2 namespace to bind to it. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Gateway +// metadata: +// name: my-gateway +// namespace: some-config-namespace +// spec: +// selector: +// app: my-gateway-controller +// servers: +// - port: +// number: 80 +// name: http +// protocol: HTTP +// hosts: +// - "ns1/*" +// - "ns2/foo.bar.com" +// ``` +// package istio.networking.v1alpha3; option go_package = "istio.io/api/networking/v1alpha3"; @@ -232,14 +268,14 @@ message Gateway { // ``` message Server { // REQUIRED: The Port on which the proxy should listen for incoming - // connections. If using Unix domain socket, use 0 as the port number, - // with a valid protocol and port name, along with the bind parameter. + // connections. Port port = 1; // $hide_from_docs // The ip or the Unix domain socket to which the listener should be bound - // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` (Linux - // abstract namespace). + // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` + // (Linux abstract namespace). When using unix domain sockets, the port + // number should be 0. string bind = 4; // REQUIRED. One or more hosts exposed by this gateway. @@ -319,18 +355,21 @@ message Server { string ca_certificates = 5; // The credentialName stands for a unique identifier that can be used - // to identify the serverCertificate and the privateKey. The credentialName - // appended with suffix "-cacert" is used to identify the CaCertificates - // associated with this server. Gateway workloads capable of fetching - // credentials from a remote credential store will be configured to retrieve - // the serverCertificate and the privateKey using credentialName, instead of - // using the file system paths specified above. If using mutual TLS, + // to identify the serverCertificate and the privateKey. The + // credentialName appended with suffix "-cacert" is used to identify + // the CaCertificates associated with this server. Gateway workloads + // capable of fetching credentials from a remote credential store such + // as kubernetes secrets, will be configured to retrieve the + // serverCertificate and the privateKey using credentialName, instead + // of using the file system paths specified above. If using mutual TLS, // gateway workloads will retrieve the CaCertificates using - // credentialName-cacert. The semantics of the name are platform dependent. - // In Kubernetes, the default Istio supplied credential server expects the - // credentialName to match the name of the Kubernetes secret that holds the - // server certificate, the private key, and the CA certificate - // (if using mutual TLS). + // credentialName-cacert. The semantics of the name are platform + // dependent. In Kubernetes, the default Istio supplied credential + // server expects the credentialName to match the name of the + // Kubernetes secret that holds the server certificate, the private + // key, and the CA certificate (if using mutual TLS). Set the + // ISTIO_META_USER_SDS metadata variable in the gateway's proxy to + // enable the dynamic credential fetching feature. string credential_name = 10; // A list of alternate names to verify the subject identity in the diff --git a/networking/v1alpha3/service_entry.pb.go b/networking/v1alpha3/service_entry.pb.go index b1f3d9d3a9f..97d37b99a75 100644 --- a/networking/v1alpha3/service_entry.pb.go +++ b/networking/v1alpha3/service_entry.pb.go @@ -9,6 +9,28 @@ // APIs) or mesh-internal services that are not part of the platform's // service registry (e.g., a set of VMs talking to services in Kubernetes). // +// The following example declares a few external APIs accessed by internal +// applications over HTTPS. The sidecar inspects the SNI value in the +// ClientHello message to route to the appropriate external service. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: ServiceEntry +// metadata: +// name: external-svc-https +// spec: +// hosts: +// - api.dropboxapi.com +// - www.googleapis.com +// - api.facebook.com +// location: MESH_EXTERNAL +// ports: +// - number: 443 +// name: https +// protocol: TLS +// resolution: DNS +// ``` +// // The following configuration adds a set of MongoDB instances running on // unmanaged VMs to Istio's registry, so that these services can be treated // as any other service in the mesh. The associated DestinationRule is used @@ -53,27 +75,24 @@ // ``` // // The following example uses a combination of service entry and TLS -// routing in virtual service to demonstrate the use of SNI routing to -// forward unterminated TLS traffic from the application to external -// services via the sidecar. The sidecar inspects the SNI value in the -// ClientHello message to route to the appropriate external service. +// routing in a virtual service to steer traffic based on the SNI value to +// an internal egress firewall. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 // kind: ServiceEntry // metadata: -// name: external-svc-https +// name: external-svc-redirect // spec: // hosts: -// - api.dropboxapi.com -// - www.googleapis.com -// - api.facebook.com +// - wikipedia.org +// - "*.wikipedia.org" // location: MESH_EXTERNAL // ports: // - number: 443 // name: https // protocol: TLS -// resolution: DNS +// resolution: NONE // ``` // // And the associated VirtualService to route based on the SNI value. @@ -85,34 +104,22 @@ // name: tls-routing // spec: // hosts: -// - api.dropboxapi.com -// - www.googleapis.com -// - api.facebook.com +// - wikipedia.org +// - "*.wikipedia.org" // tls: // - match: -// - port: 443 -// sniHosts: -// - api.dropboxapi.com +// - sniHosts: +// - wikipedia.org +// - "*.wikipedia.org" // route: // - destination: -// host: api.dropboxapi.com -// - match: -// - port: 443 -// sniHosts: -// - www.googleapis.com -// route: -// - destination: -// host: www.googleapis.com -// - match: -// - port: 443 -// sniHosts: -// - api.facebook.com -// route: -// - destination: -// host: api.facebook.com -// +// host: internal-egress-firewall.ns1.svc.cluster.local // ``` // +// The virtual service with TLS match serves to override the default SNI +// match. In the absence of a virtual service, traffic will be forwarded to +// the wikipedia domains. +// // The following example demonstrates the use of a dedicated egress gateway // through which all external service traffic is forwarded. // The 'exportTo' field allows for control over the visibility of a service diff --git a/networking/v1alpha3/service_entry.pb.html b/networking/v1alpha3/service_entry.pb.html index 486603eafa3..8aaf60b847f 100644 --- a/networking/v1alpha3/service_entry.pb.html +++ b/networking/v1alpha3/service_entry.pb.html @@ -14,6 +14,27 @@ APIs) or mesh-internal services that are not part of the platform’s service registry (e.g., a set of VMs talking to services in Kubernetes).

+

The following example declares a few external APIs accessed by internal +applications over HTTPS. The sidecar inspects the SNI value in the +ClientHello message to route to the appropriate external service.

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: ServiceEntry
+metadata:
+  name: external-svc-https
+spec:
+  hosts:
+  - api.dropboxapi.com
+  - www.googleapis.com
+  - api.facebook.com
+  location: MESH_EXTERNAL
+  ports:
+  - number: 443
+    name: https
+    protocol: TLS
+  resolution: DNS
+
+

The following configuration adds a set of MongoDB instances running on unmanaged VMs to Istio’s registry, so that these services can be treated as any other service in the mesh. The associated DestinationRule is used @@ -56,26 +77,23 @@

The following example uses a combination of service entry and TLS -routing in virtual service to demonstrate the use of SNI routing to -forward unterminated TLS traffic from the application to external -services via the sidecar. The sidecar inspects the SNI value in the -ClientHello message to route to the appropriate external service.

+routing in a virtual service to steer traffic based on the SNI value to +an internal egress firewall.

apiVersion: networking.istio.io/v1alpha3
 kind: ServiceEntry
 metadata:
-  name: external-svc-https
+  name: external-svc-redirect
 spec:
   hosts:
-  - api.dropboxapi.com
-  - www.googleapis.com
-  - api.facebook.com
+  - wikipedia.org
+  - "*.wikipedia.org"
   location: MESH_EXTERNAL
   ports:
   - number: 443
     name: https
     protocol: TLS
-  resolution: DNS
+  resolution: NONE

And the associated VirtualService to route based on the SNI value.

@@ -86,34 +104,22 @@ name: tls-routing spec: hosts: - - api.dropboxapi.com - - www.googleapis.com - - api.facebook.com + - wikipedia.org + - "*.wikipedia.org" tls: - match: - - port: 443 - sniHosts: - - api.dropboxapi.com + - sniHosts: + - wikipedia.org + - "*.wikipedia.org" route: - destination: - host: api.dropboxapi.com - - match: - - port: 443 - sniHosts: - - www.googleapis.com - route: - - destination: - host: www.googleapis.com - - match: - - port: 443 - sniHosts: - - api.facebook.com - route: - - destination: - host: api.facebook.com - + host: internal-egress-firewall.ns1.svc.cluster.local +

The virtual service with TLS match serves to override the default SNI +match. In the absence of a virtual service, traffic will be forwarded to +the wikipedia domains.

+

The following example demonstrates the use of a dedicated egress gateway through which all external service traffic is forwarded. The ‘exportTo’ field allows for control over the visibility of a service diff --git a/networking/v1alpha3/service_entry.proto b/networking/v1alpha3/service_entry.proto index a9de02c6067..8db08dff8f4 100644 --- a/networking/v1alpha3/service_entry.proto +++ b/networking/v1alpha3/service_entry.proto @@ -28,6 +28,28 @@ import "networking/v1alpha3/gateway.proto"; // APIs) or mesh-internal services that are not part of the platform's // service registry (e.g., a set of VMs talking to services in Kubernetes). // +// The following example declares a few external APIs accessed by internal +// applications over HTTPS. The sidecar inspects the SNI value in the +// ClientHello message to route to the appropriate external service. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: ServiceEntry +// metadata: +// name: external-svc-https +// spec: +// hosts: +// - api.dropboxapi.com +// - www.googleapis.com +// - api.facebook.com +// location: MESH_EXTERNAL +// ports: +// - number: 443 +// name: https +// protocol: TLS +// resolution: DNS +// ``` +// // The following configuration adds a set of MongoDB instances running on // unmanaged VMs to Istio's registry, so that these services can be treated // as any other service in the mesh. The associated DestinationRule is used @@ -72,27 +94,24 @@ import "networking/v1alpha3/gateway.proto"; // ``` // // The following example uses a combination of service entry and TLS -// routing in virtual service to demonstrate the use of SNI routing to -// forward unterminated TLS traffic from the application to external -// services via the sidecar. The sidecar inspects the SNI value in the -// ClientHello message to route to the appropriate external service. +// routing in a virtual service to steer traffic based on the SNI value to +// an internal egress firewall. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 // kind: ServiceEntry // metadata: -// name: external-svc-https +// name: external-svc-redirect // spec: // hosts: -// - api.dropboxapi.com -// - www.googleapis.com -// - api.facebook.com +// - wikipedia.org +// - "*.wikipedia.org" // location: MESH_EXTERNAL // ports: // - number: 443 // name: https // protocol: TLS -// resolution: DNS +// resolution: NONE // ``` // // And the associated VirtualService to route based on the SNI value. @@ -104,34 +123,22 @@ import "networking/v1alpha3/gateway.proto"; // name: tls-routing // spec: // hosts: -// - api.dropboxapi.com -// - www.googleapis.com -// - api.facebook.com +// - wikipedia.org +// - "*.wikipedia.org" // tls: // - match: -// - port: 443 -// sniHosts: -// - api.dropboxapi.com +// - sniHosts: +// - wikipedia.org +// - "*.wikipedia.org" // route: // - destination: -// host: api.dropboxapi.com -// - match: -// - port: 443 -// sniHosts: -// - www.googleapis.com -// route: -// - destination: -// host: www.googleapis.com -// - match: -// - port: 443 -// sniHosts: -// - api.facebook.com -// route: -// - destination: -// host: api.facebook.com -// +// host: internal-egress-firewall.ns1.svc.cluster.local // ``` // +// The virtual service with TLS match serves to override the default SNI +// match. In the absence of a virtual service, traffic will be forwarded to +// the wikipedia domains. +// // The following example demonstrates the use of a dedicated egress gateway // through which all external service traffic is forwarded. // The 'exportTo' field allows for control over the visibility of a service diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go index df36f1e0fd7..9224c76070a 100644 --- a/networking/v1alpha3/sidecar.pb.go +++ b/networking/v1alpha3/sidecar.pb.go @@ -78,6 +78,106 @@ // - "prod-us1/*" // ``` // +// If the workload is deployed without IP tables based traffic capture, the +// Sidecar resource is the only way to configure the ports on the proxy +// attached to the workload. The following example declares a Sidecar +// resource in the prod-us1 namespace for all pods with labels "app: +// productpage" belonging to the productpage.prod-us1 service. Assuming +// that these pods are deployed without IPtable rules (i.e. the Istio init +// container) and the proxy metadata ISTIO_META_INTERCEPTION_MODE is set to +// NONE, the specification below allows such pods to receive HTTP traffic +// on port 9080 and forward it to the application listening on +// 127.0.0.1:8080. It also allows the application to communicate with a +// backing MySQL database on 127.0.0.1:3306, that then gets proxied to the +// externally hosted MySQL service at mysql.foo.com:3306. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: no-ip-tables +// namespace: prod-us1 +// spec: +// workloadSelector: +// labels: +// app: productpage +// ingress: +// - port: +// number: 9080 # binds to 0.0.0.0:9080 +// protocol: HTTP +// name: somename +// defaultEndpoint: 127.0.0.1:8080 +// captureMode: NONE # not needed if metadata is set for entire proxy +// egress: +// - port: +// number: 3306 +// protocol: MYSQL +// name: egressmysql +// captureMode: NONE # not needed if metadata is set for entire proxy +// bind: 127.0.0.1 +// hosts: +// - "*/mysql.foo.com" +// ``` +// +// And the associated service entry for routing to mysql.foo.com:3306 +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: ServiceEntry +// metadata: +// name: external-svc-mysql +// namespace: ns1 +// spec: +// hosts: +// - mysql.foo.com +// ports: +// - number: 3306 +// name: mysql +// protocol: MYSQL +// location: MESH_EXTERNAL +// resolution: DNS +// ``` +// +// It is also possible to mix and match traffic capture modes in a single +// proxy. For example, consider a setup where internal services are on the +// 192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture all +// outbound traffic on 192.168.0.0/16 subnet. Assume that the VM has an +// additional network interface on 172.16.0.0/16 subnet for inbound +// traffic. The following Sidecar configuration allows the VM to expose a +// listener on 172.16.1.32:80 (the VM's IP) for traffic arriving from the +// 172.16.0.0/16 subnet. Note that in this scenario, the +// ISTIO_META_INTERCEPTION_MODE metadata on the proxy in the VM should +// contain "REDIRECT" or "TPROXY" as its value, implying that IP tables +// based traffic capture is active. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: partial-ip-tables +// namespace: prod-us1 +// spec: +// workloadSelector: +// labels: +// app: productpage +// ingress: +// - bind: 172.16.1.32 +// port: +// number: 80 # binds to 172.16.1.32:80 +// protocol: HTTP +// name: somename +// defaultEndpoint: 127.0.0.1:8080 +// captureMode: NONE +// egress: +// # use the system detected defaults +// # sets up configuration to handle outbound traffic to services +// # in 192.168.0.0/16 subnet, based on information provided by the +// # service registry +// - captureMode: IPTABLES +// hosts: +// - "*/*" +// ``` +// package v1alpha3 @@ -146,7 +246,8 @@ type Sidecar struct { // inbound traffic to the attached workload. If omitted, Istio will // automatically configure the sidecar based on the information about the workload // obtained from the orchestration platform (e.g., exposed ports, services, - // etc.). + // etc.). If specified, inbound ports are configured if and only if the + // workload is associated with a service. Ingress []*IstioIngressListener `protobuf:"bytes,2,rep,name=ingress,proto3" json:"ingress,omitempty"` // Egress specifies the configuration of the sidecar for processing // outbound traffic from the attached workload to other services in the diff --git a/networking/v1alpha3/sidecar.pb.html b/networking/v1alpha3/sidecar.pb.html index 0fc965186e5..c7cbb3970f2 100644 --- a/networking/v1alpha3/sidecar.pb.html +++ b/networking/v1alpha3/sidecar.pb.html @@ -81,6 +81,103 @@ - "prod-us1/*" +

If the workload is deployed without IP tables based traffic capture, the +Sidecar resource is the only way to configure the ports on the proxy +attached to the workload. The following example declares a Sidecar +resource in the prod-us1 namespace for all pods with labels “app: +productpage” belonging to the productpage.prod-us1 service. Assuming +that these pods are deployed without IPtable rules (i.e. the Istio init +container) and the proxy metadata ISTIOMETAINTERCEPTION_MODE is set to +NONE, the specification below allows such pods to receive HTTP traffic +on port 9080 and forward it to the application listening on +127.0.0.1:8080. It also allows the application to communicate with a +backing MySQL database on 127.0.0.1:3306, that then gets proxied to the +externally hosted MySQL service at mysql.foo.com:3306.

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: Sidecar
+metadata:
+  name: no-ip-tables
+  namespace: prod-us1
+spec:
+  workloadSelector:
+    labels:
+      app: productpage
+  ingress:
+  - port:
+      number: 9080 # binds to 0.0.0.0:9080
+      protocol: HTTP
+      name: somename
+    defaultEndpoint: 127.0.0.1:8080
+    captureMode: NONE # not needed if metadata is set for entire proxy
+  egress:
+  - port:
+      number: 3306
+      protocol: MYSQL
+      name: egressmysql
+    captureMode: NONE # not needed if metadata is set for entire proxy
+    bind: 127.0.0.1
+    hosts:
+    - "*/mysql.foo.com"
+
+ +

And the associated service entry for routing to mysql.foo.com:3306

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: ServiceEntry
+metadata:
+  name: external-svc-mysql
+  namespace: ns1
+spec:
+  hosts:
+  - mysql.foo.com
+  ports:
+  - number: 3306
+    name: mysql
+    protocol: MYSQL
+  location: MESH_EXTERNAL
+  resolution: DNS
+
+ +

It is also possible to mix and match traffic capture modes in a single +proxy. For example, consider a setup where internal services are on the +192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture all +outbound traffic on 192.168.0.0/16 subnet. Assume that the VM has an +additional network interface on 172.16.0.0/16 subnet for inbound +traffic. The following Sidecar configuration allows the VM to expose a +listener on 172.16.1.32:80 (the VM’s IP) for traffic arriving from the +172.16.0.0/16 subnet. Note that in this scenario, the +ISTIOMETAINTERCEPTION_MODE metadata on the proxy in the VM should +contain “REDIRECT” or “TPROXY” as its value, implying that IP tables +based traffic capture is active.

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: Sidecar
+metadata:
+  name: partial-ip-tables
+  namespace: prod-us1
+spec:
+  workloadSelector:
+    labels:
+      app: productpage
+  ingress:
+  - bind: 172.16.1.32
+    port:
+      number: 80 # binds to 172.16.1.32:80
+      protocol: HTTP
+      name: somename
+    defaultEndpoint: 127.0.0.1:8080
+    captureMode: NONE
+  egress:
+    # use the system detected defaults
+    # sets up configuration to handle outbound traffic to services
+    # in 192.168.0.0/16 subnet, based on information provided by the
+    # service registry
+  - captureMode: IPTABLES
+    hosts:
+    - "*/*"
+
+

CaptureMode

CaptureMode describes how traffic to a listener is expected to be @@ -296,7 +393,8 @@

Sidecar

inbound traffic to the attached workload. If omitted, Istio will automatically configure the sidecar based on the information about the workload obtained from the orchestration platform (e.g., exposed ports, services, -etc.).

+etc.). If specified, inbound ports are configured if and only if the +workload is associated with a service.

diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto index eb45b8b5be4..e3a5be25453 100644 --- a/networking/v1alpha3/sidecar.proto +++ b/networking/v1alpha3/sidecar.proto @@ -97,6 +97,106 @@ import "networking/v1alpha3/gateway.proto"; // - "prod-us1/*" // ``` // +// If the workload is deployed without IP tables based traffic capture, the +// Sidecar resource is the only way to configure the ports on the proxy +// attached to the workload. The following example declares a Sidecar +// resource in the prod-us1 namespace for all pods with labels "app: +// productpage" belonging to the productpage.prod-us1 service. Assuming +// that these pods are deployed without IPtable rules (i.e. the Istio init +// container) and the proxy metadata ISTIO_META_INTERCEPTION_MODE is set to +// NONE, the specification below allows such pods to receive HTTP traffic +// on port 9080 and forward it to the application listening on +// 127.0.0.1:8080. It also allows the application to communicate with a +// backing MySQL database on 127.0.0.1:3306, that then gets proxied to the +// externally hosted MySQL service at mysql.foo.com:3306. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: no-ip-tables +// namespace: prod-us1 +// spec: +// workloadSelector: +// labels: +// app: productpage +// ingress: +// - port: +// number: 9080 # binds to 0.0.0.0:9080 +// protocol: HTTP +// name: somename +// defaultEndpoint: 127.0.0.1:8080 +// captureMode: NONE # not needed if metadata is set for entire proxy +// egress: +// - port: +// number: 3306 +// protocol: MYSQL +// name: egressmysql +// captureMode: NONE # not needed if metadata is set for entire proxy +// bind: 127.0.0.1 +// hosts: +// - "*/mysql.foo.com" +// ``` +// +// And the associated service entry for routing to mysql.foo.com:3306 +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: ServiceEntry +// metadata: +// name: external-svc-mysql +// namespace: ns1 +// spec: +// hosts: +// - mysql.foo.com +// ports: +// - number: 3306 +// name: mysql +// protocol: MYSQL +// location: MESH_EXTERNAL +// resolution: DNS +// ``` +// +// It is also possible to mix and match traffic capture modes in a single +// proxy. For example, consider a setup where internal services are on the +// 192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture all +// outbound traffic on 192.168.0.0/16 subnet. Assume that the VM has an +// additional network interface on 172.16.0.0/16 subnet for inbound +// traffic. The following Sidecar configuration allows the VM to expose a +// listener on 172.16.1.32:80 (the VM's IP) for traffic arriving from the +// 172.16.0.0/16 subnet. Note that in this scenario, the +// ISTIO_META_INTERCEPTION_MODE metadata on the proxy in the VM should +// contain "REDIRECT" or "TPROXY" as its value, implying that IP tables +// based traffic capture is active. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: partial-ip-tables +// namespace: prod-us1 +// spec: +// workloadSelector: +// labels: +// app: productpage +// ingress: +// - bind: 172.16.1.32 +// port: +// number: 80 # binds to 172.16.1.32:80 +// protocol: HTTP +// name: somename +// defaultEndpoint: 127.0.0.1:8080 +// captureMode: NONE +// egress: +// # use the system detected defaults +// # sets up configuration to handle outbound traffic to services +// # in 192.168.0.0/16 subnet, based on information provided by the +// # service registry +// - captureMode: IPTABLES +// hosts: +// - "*/*" +// ``` +// package istio.networking.v1alpha3; option go_package = "istio.io/api/networking/v1alpha3"; @@ -112,7 +212,8 @@ message Sidecar { // inbound traffic to the attached workload. If omitted, Istio will // automatically configure the sidecar based on the information about the workload // obtained from the orchestration platform (e.g., exposed ports, services, - // etc.). + // etc.). If specified, inbound ports are configured if and only if the + // workload is associated with a service. repeated IstioIngressListener ingress = 2; // Egress specifies the configuration of the sidecar for processing
Port

REQUIRED: The Port on which the proxy should listen for incoming -connections. If using Unix domain socket, use 0 as the port number, -with a valid protocol and port name, along with the bind parameter.

+connections.
string

The credentialName stands for a unique identifier that can be used -to identify the serverCertificate and the privateKey. The credentialName -appended with suffix “-cacert” is used to identify the CaCertificates -associated with this server. Gateway workloads capable of fetching -credentials from a remote credential store will be configured to retrieve -the serverCertificate and the privateKey using credentialName, instead of -using the file system paths specified above. If using mutual TLS, +to identify the serverCertificate and the privateKey. The +credentialName appended with suffix “-cacert” is used to identify +the CaCertificates associated with this server. Gateway workloads +capable of fetching credentials from a remote credential store such +as kubernetes secrets, will be configured to retrieve the +serverCertificate and the privateKey using credentialName, instead +of using the file system paths specified above. If using mutual TLS, gateway workloads will retrieve the CaCertificates using -credentialName-cacert. The semantics of the name are platform dependent. -In Kubernetes, the default Istio supplied credential server expects the -credentialName to match the name of the Kubernetes secret that holds the -server certificate, the private key, and the CA certificate -(if using mutual TLS).

+credentialName-cacert. The semantics of the name are platform +dependent. In Kubernetes, the default Istio supplied credential +server expects the credentialName to match the name of the +Kubernetes secret that holds the server certificate, the private +key, and the CA certificate (if using mutual TLS). Set the +ISTIOMETAUSER_SDS metadata variable in the gateway’s proxy to +enable the dynamic credential fetching feature.