Merge 1.1 to master

authentication/v1alpha1/policy.proto

@@ -368,7 +368,7 @@ message TargetSelector {
 
   // Specifies the ports. Note that this is the port(s) exposed by the service, not workload ports.
   // For example, if a service is defined as below, then `8000` should be used, not `9000`.
-  // ```
+  // ```yaml
   // kind: Service
   // metadata:
   //   ...

mesh/v1alpha1/config.proto

@@ -21,9 +21,8 @@ import "networking/v1alpha3/destination_rule.proto";
 // $title: Service Mesh
 // $description: Configuration affecting the service mesh as a whole.
 // $location: https://istio.io/docs/reference/config/istio.mesh.v1alpha1.html
-// $aliases:
-// $  - /docs/reference/config/service-mesh.html
 
+// Configuration affecting the service mesh as a whole.
 package istio.mesh.v1alpha1;
 
 option go_package="istio.io/api/mesh/v1alpha1";
@@ -195,9 +194,6 @@ message MeshConfig {
   // can be configured for a single control plane.
   repeated ConfigSource config_sources = 22;
 
-  // Locality based load balancing distribution or failover settings.
-  LocalityLoadBalancerSetting locality_lb_setting = 31;
-
   // $hide_from_docs
   // This flag is used by secret discovery service(SDS).
   // If set to true(prerequisite: https://kubernetes.io/docs/concepts/storage/volumes/#projected), Istio will inject volumes mount
@@ -221,7 +217,71 @@ message MeshConfig {
   string trust_domain = 26;
 
   // $hide_from_docs
-  // Next available field number: 32
+  // The default value for the ServiceEntry.export_to field and services
+  // imported through container registry integrations, e.g. this applies to
+  // Kubernetes Service resources. The value is a list of namespace names and
+  // reserved namespace aliases. The allowed namespace aliases are:
+  //
+  // * - All Namespaces
+  // . - Current Namespace
+  // ~ - No Namespace
+  //
+  // If not set the system will use "*" as the default value which implies that
+  // services are exported to all namespaces.
+  //
+  // 'All namespaces' is a reasonable default for implementations that don't
+  // need to restrict access or visibility of services across namespace
+  // boundaries. If that requirement is present it is generally good practice to
+  // make the default 'Current namespace' so that services are only visible
+  // within their own namespaces by default. Operators can then expand the
+  // visibility of services to other namespaces as needed. Use of 'No Namespace'
+  // is expected to be rare but can have utility for deployments where
+  // dependency management needs to be precise even within the scope of a single
+  // namespace.
+  //
+  // For further discussion see the reference documentation for ServiceEntry,
+  // Sidecar, and Gateway.
+  repeated string default_service_export_to = 31;
+
+  // $hide_from_docs
+  // The default value for the VirtualService.export_to field. Has the same
+  // syntax as 'default_service_export_to'.
+  //
+  // If not set the system will use "*" as the default value which implies that
+  // virtual services are exported to all namespaces
+  repeated string default_virtual_service_export_to = 32;
+
+  // $hide_from_docs
+  // The default value for the DestinationRule.export_to field. Has the same
+  // syntax as 'default_service_export_to'.
+  //
+  // If not set the system will use "*" as the default value which implies that
+  // destination rules are exported to all namespaces
+  repeated string default_destination_rule_export_to = 33;
+
+  // $hide_from_docs
+  // The namespace to treat as the administrative root namespace for
+  // istio configuration. When processing a leaf namespace Istio will search for
+  // declarations in that namespace first and if none are found it will
+  // search in the root namespace. Any matching declaration found in the root
+  // namespace is processed as if it were declared in the leaf namespace.
+  //
+  // The precise semantics of this processing are documented on each resource
+  // type.
+  //
+  // There is no default value for this flag in 1.1 but in later releases it
+  // is expected to default to a new namespace, "istio-config", which is
+  // maintained separately from the "istio-system" namespace where an instance
+  // of the control plane runtime is deployed. This separates the concerns of
+  // configuring the control-plane runtime from configuration of the mesh.
+  string root_namespace = 34;
+
+  // Locality based load balancing distribution or failover settings.
+  LocalityLoadBalancerSetting locality_lb_setting = 35;
+
+
+  // $hide_from_docs
+  // Next available field number: 36
 }
 
 // ConfigSource describes information about a configuration store inside a
@@ -240,60 +300,88 @@ message ConfigSource {
 }
 
 
-// The following example sets up locality weight for mesh wide service
-// Assume a service resides in "region1/zone1/*" and "region1/zone2/*",
-// and originating clusters also reside in "region1/zone1/*" and "region1/zone2/*".
-// This example specifies when clusters from "region1/zone1/*" accessing the service, 80% of the traffic
-// is shipped to "region1/zone1/*" ratings service endpoints, and the rest 20% to "region1/zone2/*".
+// Locality-weighted load balancing allows administrators to control the
+// distribution of traffic to endpoints based on the localities of where the
+// traffic originates and where it will terminate. These localities are
+// specified using arbitrary labels that designate a hierarchy of localities in
+// {region}/{zone}/{sub-zone} form. For additional detail refer to
+// https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/load_balancing/locality_weight
+// The following example shows how to setup locality weights mesh-wide.
+//
+// Given a mesh with workloads and their service deployed to "us-west/zone1/*"
+// and "us-west/zone2/*". This example specifies that when traffic accessing a
+// service originates from workloads in "us-west/zone1/*", 80% of the traffic
+// will be sent to endpoints in "us-west/zone1/*", i.e the same zone, and the
+// remaining 20% will go to endpoints in "us-west/zone2/*". This setup is
+// intended to favor routing traffic to endpoints in the same locality.
+// A similar setting is specified for traffic originating in "us-west/zone2/*".
 //
 // ```yaml
 //   distribute:
-//     - from: region1/zone1/*
+//     - from: us-west/zone1/*
 //       to:
-//         "region1/zone1/*": 80
-//         "region1/zone2/*": 20
-//     - from: region1/zone2/*
+//         "us-west/zone1/*": 80
+//         "us-west/zone2/*": 20
+//     - from: us-west/zone2/*
 //       to:
-//         "region1/zone1/*": 20
-//         "region1/zone2/*": 80
+//         "us-west/zone1/*": 20
+//         "us-west/zone2/*": 80
 // ```
 //
-// The following example sets up locality failover policy for the ratings service
-// Assume a service resides in "region1" "region2" and "region3",
-// This example specifies when clusters from "region1/zone1" accessing the service,
-// if endpoints in "region1" becomes unhealthy, traffic will begin to trickle to "region2".
+// If the goal of the operator is not to distribute load across zones and
+// regions but rather to restrict the regionality of failover to meet other
+// operational requirements an operator can set a 'failover' policy instead of
+// a 'distribute' policy.
+//
+// The following example sets up a locality failover policy for regions.
+// Assume a service resides in zones within us-east, us-west & eu-west
+// this example specifies that when endpoints within us-east become unhealthy
+// traffic should failover to endpoints in any zone or sub-zone within eu-west
+// and similarly us-west should failover to us-east.
 //
 // ```yaml
 //  failover:
-//    - from: region1
-//      to: region2
+//    - from: us-east
+//      to: eu-west
+//    - from: us-west
+//      to: us-east
 // ```
 // Locality load balancing settings.
 message LocalityLoadBalancerSetting{
-  // Originating -> upstream cluster locality weight set, support wildcard matching '*'
-  // '*' matches all localities
-  // 'region1/*' matches all zones in region1
+  // Describes how traffic originating in the 'from' zone or sub-zone is
+  // distributed over a set of 'to' zones. Syntax for specifying a zone is
+  // {region}/{zone}/{sub-zone} and terminal wildcards are allowed on any
+  // segment of the specification. Examples:
+  // * - matches all localities
+  // us-west/* - all zones and sub-zones within the us-west region
+  // us-west/zone-1/* - all sub-zones within us-west/zone-1
   message Distribute{
       // Originating locality, '/' separated, e.g. 'region/zone/sub_zone'.
       string from = 1;
 
-      // Upstream locality to loadbalancing weight map. The sum of all weights should be == 100.
-      // Should assign load balancing weight for all localities, otherwise the traffic are not routed
-      // following the percentage of weight.
+      // Map of upstream localities to traffic distribution weights. The sum of
+      // all weights should be == 100. Any locality not assigned a weight will
+      // receive no traffic.
       map<string, uint32> to = 2;
   };
 
-  // Specify the traffic failover policy.
-  // As zone and sub_zone failover is supported by default, only region can be specified here.
+  // Specify the traffic failover policy across regions. Since zone and sub-zone
+  // failover is supported by default this only needs to be specified for
+  // regions when the operator needs to constrain traffic failover so that
+  // the default behavior of failing over to any endpoint globally does not
+  // apply. This is useful when failing over traffic across regions would not
+  // improve service health or may need to be restricted for other reasons
+  // like regulatory controls.
   message Failover{
       // Originating region.
       string from = 1;
 
-      // Destination region the traffic will fail over to when endpoints in local region becomes unhealthy.
+      // Destination region the traffic will fail over to when endpoints in
+      // the 'from' region becomes unhealthy.
       string to = 2;
   };
 
-  // Optional: only distribute or failover can be set.
+  // Optional: only one of distribute or failover can be set.
   // Explicitly specify loadbalancing weight across different zones and geographical locations.
   // Refer to [Locality weighted load balancing](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/load_balancing.html?highlight=load_balancing_weight#locality-weighted-load-balancing)
   // If empty, the locality weight is set according to the endpoints number within it.