Before you begin

Before you begin the locality load balancing tasks, you must first install Istio on multiple clusters. The clusters must span three regions, containing four availability zones. The number of clusters required may vary based on the capabilities offered by your cloud provider.

For simplicity, we will assume that there is only a single primary cluster in the mesh. This simplifies the process of configuring the control plane, since changes only need to be applied to one cluster.

We will deploy several instances of the HelloWorld application as follows:

In a single multi-zone cluster environment, locality load balancing can also be configured for failover to a different zone within the same cluster. To test it, you will need to create a cluster with multiple worker zones and deploy an istiod instance and the app to each zone.

1: If you don’t have a multi-zone Kubernetes cluster, you can deploy one locally using kind with the following command:

$ kind create cluster --config=- <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
- role: worker
EOF

2: Use topology.kubernetes.io/zone to label each worker with a zone name:

$ kubectl label node kind-worker topology.kubernetes.io/zone=us-south10
$ kubectl label node kind-worker2 topology.kubernetes.io/zone=us-south12
$ kubectl label node kind-worker3 topology.kubernetes.io/zone=us-south13

3: Deploy istiod to the control-plane node and the helloworld app to each of the worker nodes.

Environment Variables

This guide assumes that all clusters will be accessed through contexts in the default Kubernetes configuration file. The following environment variables will be used for the various contexts:

Create the sample namespace

To begin, generate yaml for the sample namespace with automatic sidecar injection enabled:

$ cat <<EOF > sample.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: sample
  labels:
    istio-injection: enabled
EOF

Add the sample namespace to each cluster:

$ for CTX in "$CTX_PRIMARY" "$CTX_R1_Z1" "$CTX_R1_Z2" "$CTX_R2_Z3" "$CTX_R3_Z4"; \
  do \
    kubectl --context="$CTX" apply -f sample.yaml; \
  done

Deploy HelloWorld

Generate the HelloWorld YAML for each locality, using the locality as the version string:

Zip

$ for LOC in "region1.zone1" "region1.zone2" "region2.zone3" "region3.zone4"; \
  do \
    ./@samples/helloworld/gen-helloworld.sh@ \
      --version "$LOC" > "helloworld-${LOC}.yaml"; \
  done

Apply the HelloWorld YAML to the appropriate cluster for each locality:

$ kubectl apply --context="${CTX_R1_Z1}" -n sample \
  -f helloworld-region1.zone1.yaml

$ kubectl apply --context="${CTX_R1_Z2}" -n sample \
  -f helloworld-region1.zone2.yaml

$ kubectl apply --context="${CTX_R2_Z3}" -n sample \
  -f helloworld-region2.zone3.yaml

$ kubectl apply --context="${CTX_R3_Z4}" -n sample \
  -f helloworld-region3.zone4.yaml

Deploy curl

Deploy the curl application to region1 zone1:

Zip

$ kubectl apply --context="${CTX_R1_Z1}" \
  -f @samples/curl/curl.yaml@ -n sample

Wait for HelloWorld pods

Wait until the HelloWorld pods in each zone are Running:

$ kubectl get pod --context="${CTX_R1_Z1}" -n sample -l app="helloworld" \
  -l version="region1.zone1"
NAME                                       READY   STATUS    RESTARTS   AGE
helloworld-region1.zone1-86f77cd7b-cpxhv   2/2     Running   0          30s

$ kubectl get pod --context="${CTX_R1_Z2}" -n sample -l app="helloworld" \
  -l version="region1.zone2"
NAME                                       READY   STATUS    RESTARTS   AGE
helloworld-region1.zone2-86f77cd7b-cpxhv   2/2     Running   0          30s

$ kubectl get pod --context="${CTX_R2_Z3}" -n sample -l app="helloworld" \
  -l version="region2.zone3"
NAME                                       READY   STATUS    RESTARTS   AGE
helloworld-region2.zone3-86f77cd7b-cpxhv   2/2     Running   0          30s

$ kubectl get pod --context="${CTX_R3_Z4}" -n sample -l app="helloworld" \
  -l version="region3.zone4"
NAME                                       READY   STATUS    RESTARTS   AGE
helloworld-region3.zone4-86f77cd7b-cpxhv   2/2     Running   0          30s

Congratulations! You successfully configured the system and are now ready to begin the locality load balancing tasks!

Next steps

You can now configure one of the following load balancing options:

• Locality failover

• Locality weighted distribution

Only one of the load balancing options should be configured, as they are mutually exclusive. Attempting to configure both may lead to unexpected behavior.