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:

Setup for locality load balancing tasks

Setup for locality load balancing tasks

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:

  1. $ kind create cluster --config=- <<EOF
  2. kind: Cluster
  3. apiVersion: kind.x-k8s.io/v1alpha4
  4. nodes:
  5. - role: control-plane
  6. - role: worker
  7. - role: worker
  8. - role: worker
  9. EOF

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

  1. $ kubectl label node kind-worker topology.kubernetes.io/zone=us-south10
  2. $ kubectl label node kind-worker2 topology.kubernetes.io/zone=us-south12
  3. $ 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:

VariableDescription
CTX_PRIMARYThe context used for applying configuration to the primary cluster.
CTX_R1_Z1The context used to interact with pods in region1.zone1.
CTX_R1_Z2The context used to interact with pods in region1.zone2.
CTX_R2_Z3The context used to interact with pods in region2.zone3.
CTX_R3_Z4The context used to interact with pods in region3.zone4.

Create the sample namespace

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

  1. $ cat <<EOF > sample.yaml
  2. apiVersion: v1
  3. kind: Namespace
  4. metadata:
  5. name: sample
  6. labels:
  7. istio-injection: enabled
  8. EOF

Add the sample namespace to each cluster:

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

Deploy HelloWorld

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

Zip

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

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

  1. $ kubectl apply --context="${CTX_R1_Z1}" -n sample \
  2. -f helloworld-region1.zone1.yaml
  1. $ kubectl apply --context="${CTX_R1_Z2}" -n sample \
  2. -f helloworld-region1.zone2.yaml
  1. $ kubectl apply --context="${CTX_R2_Z3}" -n sample \
  2. -f helloworld-region2.zone3.yaml
  1. $ kubectl apply --context="${CTX_R3_Z4}" -n sample \
  2. -f helloworld-region3.zone4.yaml

Deploy Sleep

Deploy the Sleep application to region1 zone1:

Zip

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

Wait for HelloWorld pods

Wait until the HelloWorld pods in each zone are Running:

  1. $ kubectl get pod --context="${CTX_R1_Z1}" -n sample -l app="helloworld" \
  2. -l version="region1.zone1"
  3. NAME READY STATUS RESTARTS AGE
  4. helloworld-region1.zone1-86f77cd7b-cpxhv 2/2 Running 0 30s
  1. $ kubectl get pod --context="${CTX_R1_Z2}" -n sample -l app="helloworld" \
  2. -l version="region1.zone2"
  3. NAME READY STATUS RESTARTS AGE
  4. helloworld-region1.zone2-86f77cd7b-cpxhv 2/2 Running 0 30s
  1. $ kubectl get pod --context="${CTX_R2_Z3}" -n sample -l app="helloworld" \
  2. -l version="region2.zone3"
  3. NAME READY STATUS RESTARTS AGE
  4. helloworld-region2.zone3-86f77cd7b-cpxhv 2/2 Running 0 30s
  1. $ kubectl get pod --context="${CTX_R3_Z4}" -n sample -l app="helloworld" \
  2. -l version="region3.zone4"
  3. NAME READY STATUS RESTARTS AGE
  4. 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:

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