diff --git a/.spelling b/.spelling index 2561250e5c..11b171d9c2 100644 --- a/.spelling +++ b/.spelling @@ -579,6 +579,7 @@ mysql mysqldb Nambiar namespace +namespaced namespaces Naser natively diff --git a/content/en/docs/ops/configuration/traffic-management/multicluster/index.md b/content/en/docs/ops/configuration/traffic-management/multicluster/index.md new file mode 100644 index 0000000000..133fa45e4b --- /dev/null +++ b/content/en/docs/ops/configuration/traffic-management/multicluster/index.md @@ -0,0 +1,124 @@ +--- +title: Multi-cluster Traffic Management +description: How to configure how traffic is distributed among clusters in the mesh. +weight: 70 +keywords: [traffic-management,multicluster] +owner: istio/wg-networking-maintainers +test: no +--- + +Within a multicluster mesh, traffic rules specific to the cluster topology may be desirable. This document describes +a few ways to manage traffic in a multicluster mesh. Before reading this guide: + +1. Read [Deployment Models](/docs/ops/deployment/deployment-models/#multiple-clusters) +1. Make sure your deployed services follow the concept of {{< gloss "namespace sameness" >}}namespace sameness{{< /gloss >}}. + +## Keeping traffic in-cluster + +In some cases the default cross-cluster load balancing behavior is not desirable. To keep traffic "cluster-local" (i.e. +traffic sent from `cluster-a` will only reach destinations in `cluster-a`), mark hostnames or wildcards as `clusterLocal` +using [`MeshConfig.serviceSettings`](/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig-ServiceSettings-Settings). + +For example, you can enforce cluster-local traffic for an individual service, all services in a particular namespace, or globally for all services in the mesh, as follows: + +{{< tabset category-name="meshconfig" >}} + +{{< tab name="per-service" category-value="service" >}} + +{{< text yaml >}} +serviceSettings: +- settings: + clusterLocal: true + hosts: + - "mysvc.myns.svc.cluster.local" +{{< /text >}} + +{{< /tab >}} + +{{< tab name="per-namespace" category-value="namespace" >}} + +{{< text yaml >}} +serviceSettings: +- settings: + clusterLocal: true + hosts: + - "*.myns.svc.cluster.local" +{{< /text >}} + +{{< /tab >}} + +{{< tab name="global" category-value="global" >}} + +{{< text yaml >}} +serviceSettings: +- settings: + clusterLocal: true + hosts: + - "*" +{{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + +## Partitioning Services {#partitioning-services} + +[`DestinationRule.subsets`](/docs/reference/config/networking/destination-rule/#Subset) allows partitioning a service +by selecting labels. These labels can be the labels from Kubernetes metadata, or from [built-in labels](/docs/reference/config/labels/). +One of these built-in labels, `topology.istio.io/cluster`, in the subset selector for a `DestinationRule` allows +creating per-cluster subsets. + +{{< text yaml >}} +apiVersion: networking.istio.io/v1beta1 +kind: DestinationRule +metadata: + name: mysvc-per-cluster-dr +spec: + host: mysvc.myns.svc.cluster.local + subsets: + - name: cluster-1 + labels: + topology.istio.io/cluster: cluster-1 + - name: cluster-2 + labels: + topology.istio.io/cluster: cluster-2 +{{< /text >}} + +Using these subsets you can create various routing rules based on the cluster such as [mirroring](/docs/tasks/traffic-management/mirroring/) +or [shifting](/docs/tasks/traffic-management/traffic-shifting/). + +This provides another option to create cluster-local traffic rules by restricting the destination subset in a `VirtualService`: + +{{< text yaml >}} +apiVersion: networking.istio.io/v1beta1 +kind: VirtualService +metadata: + name: mysvc-cluster-local-vs +spec: + hosts: + - mysvc.myns.svc.cluster.local + http: + - name: "cluster-1-local" + match: + - sourceLabels: + topology.istio.io/cluster: "cluster-1" + route: + - destination: + host: mysvc.myns.svc.cluster.local + subset: cluster-1 + - name: "cluster-2-local" + match: + - sourceLabels: + topology.istio.io/cluster: "cluster-2" + route: + - destination: + host: mysvc.myns.svc.cluster.local + subset: cluster-2 +{{< /text >}} + +Using subset-based routing this way to control cluster-local traffic, as opposed to +[`MeshConfig.serviceSettings`](/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig-ServiceSettings-Settings), +has the downside of mixing service-level policy with topology-level policy. +For example, a rule that sends 10% of traffic to `v2` of a service will need twice the +number of subsets (e.g., `cluster-1-v2`, `cluster-2-v2`). +This approach is best limited to situations where more granular control of cluster-based routing is needed. diff --git a/content/en/docs/ops/deployment/deployment-models/index.md b/content/en/docs/ops/deployment/deployment-models/index.md index 423bba75c7..74397ca8eb 100644 --- a/content/en/docs/ops/deployment/deployment-models/index.md +++ b/content/en/docs/ops/deployment/deployment-models/index.md @@ -120,6 +120,11 @@ You can configure inter-cluster communication based on the example, if two clusters reside on the same underlying network, you can enable cross-cluster communication by simply configuring firewall rules. +Within a multicluster mesh, all services are shared by default, according to the +concept of {{< gloss "namespace sameness" >}}namespace sameness{{< /gloss >}}. +[Traffic management rules](/docs/ops/configuration/traffic-management/multicluster) +provide fine-grained control over the behavior of multicluster traffic. + ### DNS with multiple clusters When a client application makes a request to some host, it must first perform a diff --git a/content/en/docs/reference/glossary/namespace-sameness.md b/content/en/docs/reference/glossary/namespace-sameness.md new file mode 100644 index 0000000000..f4b54c737f --- /dev/null +++ b/content/en/docs/reference/glossary/namespace-sameness.md @@ -0,0 +1,9 @@ +--- +title: Namespace Sameness +test: n/a +--- + +Within a multicluster mesh, [namespace sameness](https://github.com/kubernetes/community/blob/master/sig-multicluster/namespace-sameness-position-statement.md) +applies and all namespaces with a given name are considered to be the same namespace. If multiple clusters contain a +`Service` with the same namespaced name, they will be recognized as a single combined service. By default, traffic is +load-balanced across all clusters in the mesh for a given service. \ No newline at end of file diff --git a/content/en/docs/releases/bugs/index.md b/content/en/docs/releases/bugs/index.md index 5f137b155e..72b0667c0b 100644 --- a/content/en/docs/releases/bugs/index.md +++ b/content/en/docs/releases/bugs/index.md @@ -38,6 +38,9 @@ all of the relevant state from your Kubernetes cluster: Then attach the produced `bug-report.tgz` with your reported problem. +If your mesh spans multiple clusters, run `istioctl bug-report` against each cluster, specifying the `--context` +or `--kubeconfig` flags. + {{< tip >}} The `istioctl bug-report` command is only available with `istioctl` version `1.8.0` and higher but it can be used to also collect the information from an older Istio version installed in your cluster. {{< /tip >}}