Multi-Cluster topologies | Installing | Red Hat OpenShift Service Mesh 3.0.0tp1

About multi-cluster mesh topologies
- Control plane topology models
- Network topology models
Multi-Cluster configuration overview
- Creating certificates for a multi-cluster topology
- Applying certificates to a multi-cluster topology

Multi-Cluster topologies are useful for organizations with distributed systems or environments seeking enhanced scalability, fault tolerance, and regional redundancy.

About multi-cluster mesh topologies

In a multi-cluster mesh topology, you install and manage a single Istio mesh across multiple OpenShift Container Platform clusters, enabling communication and service discovery between the services. Two factors determine the multi-cluster mesh topology: control plane topology and network topology. There are two options for each topology. Therefore, there are four possible multi-cluster mesh topology configurations.

Multi-Primary Single Network: Combines the multi-primary control plane topology and the single network network topology models.
Multi-Primary Multi-Network: Combines the Combines the multi-primary control plane topology and the multi-network network topology models.
Primary-Remote Single Network: Combines the primary-remote control plane topology and the single network network topology models.
Primary-Remote Multi-Network: Combines the primary-remote control plane topology and the multi-network network topology models.

Control plane topology models

A multi-cluster mesh must use one of the following control plane topologies:

Multi-Primary: In this configuration, a control plane resides on every cluster. Each control plane observes the API servers in all of the other clusters for services and endpoints.
Primary-Remote: In this configuration, the control plane resides only on one cluster, called the primary cluster. No control plane runs on any of the other clusters, called remote clusters. The control plane on the primary cluster discovers services and endpoints and configures the sidecar proxies for the workloads in all clusters.

Network topology models

A multi-cluster mesh must use one of the following network topologies:

Single Network: All clusters reside on the same network and there is direct connectivity between the services in all the clusters. There is no need to use gateways for communication between the services across cluster boundaries.
Multi-Network: Clusters reside on different networks and there is no direct connectivity between services. Gateways must be used to enable communication across network boundaries.

Multi-Cluster configuration overview

To configure a multi-cluster topology you must perform the following actions:

Install the OpenShift Service Mesh Operator for each cluster.
Create or have access to root and intermediate certificates for each cluster.
Apply the security certificates for each cluster.
Install Istio for each cluster.

Creating certificates for a multi-cluster topology

Create the root and intermediate certificate authority (CA) certificates for two clusters.

Prerequisites

You have OpenSSL installed locally.

Procedure

Create the root CA certificate:

Create a key for the root certificate by running the following command:
```
$ openssl genrsa -out root-key.pem 4096
```

Create an OpenSSL configuration certificate file named root-ca.conf for the root CA certificates:

Example root certificate configuration file

encrypt_key = no
prompt = no
utf8 = yes
default_md = sha256
default_bits = 4096
req_extensions = req_ext
x509_extensions = req_ext
distinguished_name = req_dn
[ req_ext ]
subjectKeyIdentifier = hash
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, nonRepudiation, keyEncipherment, keyCertSign
[ req_dn ]
O = Istio
CN = Root CA

Create the certificate signing request by running the following command:

$ openssl req -sha256 -new -key root-key.pem \
  -config root-ca.conf \
  -out root-cert.csr

Create a shared root certificate by running the following command:

$ openssl x509 -req -sha256 -days 3650 \
  -signkey root-key.pem \
  -extensions req_ext -extfile root-ca.conf \
  -in root-cert.csr \
  -out root-cert.pem

Create the intermediate CA certificate for the East cluster:

Create a directory named east by running the following command:
```
$ mkdir east
```
Create a key for the intermediate certificate for the East cluster by running the following command:
```
$ openssl genrsa -out east/ca-key.pem 4096
```

Create an OpenSSL configuration file named intermediate.conf in the east/ directory for the intermediate certificate of the East cluster. Copy the following example file and save it locally:

Example configuration file

[ req ]
encrypt_key = no
prompt = no
utf8 = yes
default_md = sha256
default_bits = 4096
req_extensions = req_ext
x509_extensions = req_ext
distinguished_name = req_dn
[ req_ext ]
subjectKeyIdentifier = hash
basicConstraints = critical, CA:true, pathlen:0
keyUsage = critical, digitalSignature, nonRepudiation, keyEncipherment, keyCertSign
subjectAltName=@san
[ san ]
DNS.1 = istiod.istio-system.svc
[ req_dn ]
O = Istio
CN = Intermediate CA
L = east

Create a certificate signing request by running the following command:

$ openssl req -new -config east/intermediate.conf \
   -key east/ca-key.pem \
   -out east/cluster-ca.csr

Create the intermediate CA certificate for the East cluster by running the following command:

$ openssl x509 -req -sha256 -days 3650 \
   -CA root-cert.pem \
   -CAkey root-key.pem -CAcreateserial \
   -extensions req_ext -extfile east/intermediate.conf \
   -in east/cluster-ca.csr \
   -out east/ca-cert.pem

Create a certificate chain from the intermediate and root CA certificate for the east cluster by running the following command:
```
$ cat east/ca-cert.pem root-cert.pem > east/cert-chain.pem && cp root-cert.pem east
```

Create the intermediate CA certificate for the West cluster:

Create a directory named west by running the following command:
```
$ mkdir west
```
Create a key for the intermediate certificate for the West cluster by running the following command:
```
$ openssl genrsa -out west/ca-key.pem 4096
```

Create an OpenSSL configuration file named intermediate.conf in the west/ directory for for the intermediate certificate of the West cluster. Copy the following example file and save it locally:

Example configuration file

[ req ]
encrypt_key = no
prompt = no
utf8 = yes
default_md = sha256
default_bits = 4096
req_extensions = req_ext
x509_extensions = req_ext
distinguished_name = req_dn
[ req_ext ]
subjectKeyIdentifier = hash
basicConstraints = critical, CA:true, pathlen:0
keyUsage = critical, digitalSignature, nonRepudiation, keyEncipherment, keyCertSign
subjectAltName=@san
[ san ]
DNS.1 = istiod.istio-system.svc
[ req_dn ]
O = Istio
CN = Intermediate CA
L = west

Create a certificate signing request by running the following command:

$ openssl req -new -config west/intermediate.conf \
   -key west/ca-key.pem \
   -out west/cluster-ca.csr

Create the certificate by running the following command:

$ openssl x509 -req -sha256 -days 3650 \
   -CA root-cert.pem \
   -CAkey root-key.pem -CAcreateserial \
   -extensions req_ext -extfile west/intermediate.conf \
   -in west/cluster-ca.csr \
   -out west/ca-cert.pem

Create the certificate chain by running the following command:

$ cat west/ca-cert.pem root-cert.pem > west/cert-chain.pem && cp root-cert.pem west

Applying certificates to a multi-cluster topology

Apply root and intermediate certificate authority (CA) certificates to the clusters in a multi-cluster topology.

In this procedure, CLUSTER1 is the East cluster and CLUSTER2 is the West cluster.

Prerequisites

You have access to two OpenShift Container Platform clusters with external load balancer support.
You have created the root CA certificate and intermediate CA certificates for each cluster or someone has made them available for you.

Procedure

Apply the certificates to the East cluster of the multi-cluster topology:

Log in to East cluster by running the following command:
```
$ oc login -u https://<east_cluster_api_server_url>
```
Set up the environment variable that contains the oc command context for the East cluster by running the following command:
```
$ export CTX_CLUSTER1=$(oc config current-context)
```

Create a project called istio-system by running the following command:

$ oc get project istio-system --context "${CTX_CLUSTER1}" || oc new-project istio-system --context "${CTX_CLUSTER1}"

Configure Istio to use network1 as the default network for the pods on the East cluster by running the following command:
```
$ oc --context "${CTX_CLUSTER1}" label namespace istio-system topology.istio.io/network=network1
```

Create the CA certificates, certificate chain, and the private key for Istio on the East cluster by running the following command:

$ oc get secret -n istio-system --context "${CTX_CLUSTER1}" cacerts || oc create secret generic cacerts -n istio-system --context "${CTX_CLUSTER1}" \
  --from-file=east/ca-cert.pem \
  --from-file=east/ca-key.pem \
  --from-file=east/root-cert.pem \
  --from-file=east/cert-chain.pem

If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will reside in the east/ directory. If your certificates reside in a different directory, modify the syntax accordingly.

Apply the certificates to the West cluster of the multi-cluster topology:

Log in to the West cluster by running the following command:
```
$ oc login -u https://<west_cluster_api_server_url>
```
Set up the environment variable that contains the oc command context for the West cluster by running the following command:
```
$ export CTX_CLUSTER2=$(oc config current-context)
```

Create a project called istio-system by running the following command:

$ oc get project istio-system --context "${CTX_CLUSTER2}" || oc new-project istio-system --context "${CTX_CLUSTER2}"

Configure Istio to use network2 as the default network for the pods on the West cluster by running the following command:
```
$ oc --context "${CTX_CLUSTER2}" label namespace istio-system topology.istio.io/network=network2
```

Create the CA certificate secret for Istio on the West cluster by running the following command:

$ oc get secret -n istio-system --context "${CTX_CLUSTER2}" cacerts || oc create secret generic cacerts -n istio-system --context "${CTX_CLUSTER2}" \
  --from-file=west/ca-cert.pem \
  --from-file=west/ca-key.pem \
  --from-file=west/root-cert.pem \
  --from-file=west/cert-chain.pem

If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will reside in the west/ directory. If the certificates reside in a different directory, modify the syntax accordingly.

Next steps

Install Istio on all the clusters comprising the mesh topology.