Add a Primary Cluster

To build a multicluster deployment, you can add primary clusters to your service mesh.

To give you clean instructions, this section starts right after you complete the initial configuration, and assumes that Cluster_1 and Cluster_2 reside on the same network. However, you can add primary clusters to your existing mesh regardless of your current deployment model.

Add primary clusters to your deployment to improve the availability of your mesh. To keep multiple control planes in sync, apply your configuration to each cluster. Production systems employ continuous integration and continuous deployment (CI/CD) pipelines to apply configurations since they typically have at least one control plane per region. Administrators use these pipelines to manage configuration rollouts. Apply new configurations to one primary cluster at a time to help minimize troubleshooting.

The following diagram shows a multicluster deployment with two primary clusters:

Complete the initial configuration instructions before you continue.

Configure Trust

For CLUSTER_2 to participate in cross-cluster load balancing with your first cluster, in this case CLUSTER_1, establish trust between the clusters and generate a Certificate Authority (CA) certificate for CLUSTER_2 that the common root CA signed. Using the set environment variables, configure trust with the following steps:

1. Go to the ${WORK_DIR} folder with the following command:

$ cd ${WORK_DIR}

1. Generate the intermediate CA files for Cluster_2 with the following command:

$ make -f ${ISTIO}/tools/certs/Makefile ${CLUSTER_2}-cacerts-k8s

1. To ensure that the Istio control plane and the secret share the same namespace, create the istio-system namespace in Cluster_2 with the following command:

$ kubectl create namespace istio-system --context=${CTX_2}

1. Push the secret with the generated CA files to Cluster_2 with the following command:

$ kubectl create secret generic cacerts --context=${CTX_2} \
  -n istio-system \
  --from-file=${WORK_DIR}/${CLUSTER_2}/ca-cert.pem \
  --from-file=${WORK_DIR}/${CLUSTER_2}/ca-key.pem \
  --from-file=${WORK_DIR}/${CLUSTER_2}/root-cert.pem \
  --from-file=${WORK_DIR}/${CLUSTER_2}/cert-chain.pem

Congratulations!

You configured trust in Cluster_2 to enable workloads in different clusters to trust each other in your multicluster mesh. Next, deploy an Istio control plane on Cluster_2.

Deploy Istio

Next, deploy a full Istio control plane on Cluster_2. The new control plane requires the following configurations to enable a multicluster deployment:

Using the previously set environment variables, deploy an Istio control plane with the following steps:

1. To pass configuration values to the Istio operator for installation, define a custom resource (CR). Define and save the install.yaml CR with the following command:

$ cat <<EOF> ${WORK_DIR}/${CLUSTER_2}/install.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  values:
    global:
      meshID: ${MESH}
      multiCluster:
        clusterName: ${CLUSTER_2}
      network: ${NETWORK_1}

      meshNetworks:
        ${NETWORK_1}:
          endpoints:
          # Always use ‘Kubernetes' as the registry name for
          # endpoints that reside on the same network as this
          # instance of the Istio control plane.
          - fromRegistry: Kubernetes
          gateways:
          - registry_service_name: istio-ingressgateway.istio-system.svc.cluster.local
            port: 443
      # Expose the control plane through istio-ingressgateway.
      meshExpansion:
        enabled: true
EOF

1. Install Istio on Cluster-2 with the following command:

   $ istioctl --context=${CTX_2} manifest apply -f \
   ${WORK_DIR}/${CLUSTER_2}/install.yaml
   

2. Verify that the control plane is ready with the following command:

   $ kubectl --context=${CTX_2} -n istio-system get pod
   NAME                                    READY   STATUS    RESTARTS   AGE
   istiod-f756bbfc4-thkmk                  1/1     Running   0          136m
   prometheus-b54c6f66b-q8hbt              2/2     Running   0          136m
   

3. After the status of all pods is Running, you can continue configuring your deployment.

Congratulations!

You successfully added a control plane to your primary cluster.

Next, configure endpoint discovery to support cross-cluster load balancing.

Configure endpoint discovery

To enable cross-cluster load balancing in your mesh, configure endpoint discovery. This feature requires that clusters share secrets between them. If the shared secrets provide the needed trust, each cluster in the mesh can access the API server in the other clusters directly. Using the previously set environment variables, configure endpoint discovery with the following steps:

1. Share the secret of Cluster_1 with Cluster_2:

   $ istioctl x create-remote-secret \
     --context=${CTX_1} \
     --name=${CLUSTER_1} | \
     kubectl apply -f - --context=${CTX_2}
   

2. Share the secret of Cluster_2 with Cluster_1:

   $ istioctl x create-remote-secret \
     --context=${CTX_2} \
     --name=${CLUSTER_2} | \
     kubectl apply -f - --context=${CTX_1}
   

Congratulations!

You successfully added a primary cluster to your mesh!

Now, you can verify that your newly deployed cluster works as intended.

Next, continue to add clusters until you complete your deployment. You can add the following types of clusters to your mesh:

• Add a primary cluster
• Add a remote cluster

If you completed your deployment, what comes next?

The following sections provide you possible next steps:

• To configure additional Istio features, go to our Tasks section.

• To operate your service mesh, go to our Operations section.

• To deploy example applications, go to our Examples section.

• To troubleshoot your service mesh, go to our Common problems and Diagnostic tools sections.