Initial Configuration

4 minute read

To build a multicluster deployment, configure a single cluster service mesh as your starting point.

The single cluster mesh you deploy in this section, serves as a model for the configuration of the first primary cluster. You need at least one primary cluster to complete the different multicluster deployments.

Each cluster in a multicluster deployment needs a unique identifier. Using CLUSTER_1 as a unique identifier for the first cluster, the following diagram shows a service mesh spanning a single primary cluster.

A service mesh with a single primary cluster

Complete the Before you begin instructions before you continue.

To set up a cluster as the primary cluster of a multicluster service mesh, complete the following configuration steps:

Configure trust for the cluster
Deploy Istio to the cluster

Configure trust

A multicluster service mesh deployment requires that you establish trust between the clusters in the mesh. To authenticate workloads across clusters, Istio requires that only one root Certificate Authority (CA) is active in the mesh. To establish shared trust, generate a single root CA for the entire mesh, and an intermediate CA for each cluster. Then, the shared root CA can sign the intermediate CA of each cluster.

Production environments should use your organization’s root CA whenever possible, or set up a secure PKI like Vault PKI to generate the common root certificate.

The Makefile in install/certs is a simple tool that helps generate the root certificate and intermediate certificates, but do not use it as a production-ready root CA. The tool lacks the following critical features:

Private key protection
Access control
Auditing
Monitoring

Use the Makefile to generate the common root and the intermediate certificates only for tests or demos. All of the files needed for a cluster CA are stored under the subdirectory <CLUSTER_NAME>.

Using the set environment variables, configure trust with the following steps:

Go to the WORK_DIR directory with the following command:
```
$ cd ${WORK_DIR}
```
Generate the root CA and the intermediate CA for the cluster with the following command:
```
$ make -f ${ISTIO}/tools/certs/Makefile ${CLUSTER_1}-cacerts-k8s
```
To ensure that the Istio control plane and the secret share the same namespace, create the istio-system namespace with the following command:
```
$ kubectl create namespace istio-system --context=${CTX_1}
```

Push the secret with the generated CA files to the cluster with the following command:

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

Pushing the secret to the cluster overrides Istio’s default CA, allowing you to establish trust between clusters using intermediate CAs that are signed by the shared root CA.

Congratulations!

You configured trust in the cluster to enable a multicluster deployment.

Deploy Istio

Next, you must deploy Istio to the cluster if you hadn’t already, or update your Istio configuration for multicluster. Istio requires the following configuration values to enable a multicluster deployment:

Configuration field	Description	Value
`clusterName`	Specifies a human-readable cluster name.	`${CLUSTER_1}`
`network`	Specifies a network ID as an arbitrary string. All clusters in your mesh must be on the same network, and have the same network ID.	`${NETWORK_1}`
`meshID`	Specifies a mesh ID as an arbitrary string. All clusters in your mesh share the same mesh ID.	`${MESH}`
`meshExpansion`	Recommended: Exposes the Istio control plane through the ingress gateway of the mesh. Enable this option to connect remote clusters to a control plane.	`enabled: true`

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

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_1}/install.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
    values:
        global:
            meshID: ${MESH}
            multiCluster:
                clusterName: ${CLUSTER_1}
            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

Install Istio on the first cluster with the following command:

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

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

$ kubectl --context=${CTX_1} -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

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

Congratulations, you successfully configured the first cluster of your multicluster 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:

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.