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
Installing a multi-primary multi-network mesh
- Verifying a multi-cluster topology
- Removing a multi-cluster topology from a development environment
Installing a primary-remote multi-network mesh

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.

Installing a multi-primary multi-network mesh

Install Istio in the multi-primary multi-network topology on two OpenShift Container Platform clusters.

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

You can adapt these instructions for a mesh spanning more than two clusters.

Prerequisites

You have installed the OpenShift Service Mesh 3 Operator on all of the clusters that comprise the mesh.
You have completed "Creating certificates for a multi-cluster mesh".
You have completed "Applying certificates to a multi-cluster topology".
You have created an Istio Container Network Interface (CNI) resource.
You have istioctl installed on the laptop you can use to run these instructions.

Procedure

Create an ISTIO_VERSION environment variable that defines the Istio version to install by running the following command:
```
$ export ISTIO_VERSION=1.24.1
```

Install Istio on the East cluster:

Create an Istio resource on the East cluster by running the following command:

$ cat <<EOF | oc --context "${CTX_CLUSTER1}" apply -f -
apiVersion: sailoperator.io/v1alpha1
kind: Istio
metadata:
  name: default
spec:
  version: v${ISTIO_VERSION}
  namespace: istio-system
  values:
    global:
      meshID: mesh1
      multiCluster:
        clusterName: cluster1
      network: network1
EOF

Wait for the control plane to return the Ready status condition by running the following command:
```
$ oc --context "${CTX_CLUSTER1}" wait --for condition=Ready istio/default --timeout=3m
```

Create an East-West gateway on the East cluster by running the following command:

$ oc --context "${CTX_CLUSTER1}" apply -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/east-west-gateway-net1.yaml

Expose the services through the gateway by running the following command:

$ oc --context "${CTX_CLUSTER1}" apply -n istio-system -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/expose-services.yaml

Install Istio on the West cluster:

Create an Istio resource on the West cluster by running the following command:

$ cat <<EOF | oc --context "${CTX_CLUSTER2}" apply -f -
apiVersion: sailoperator.io/v1alpha1
kind: Istio
metadata:
  name: default
spec:
  version: v${ISTIO_VERSION}
  namespace: istio-system
  values:
    global:
      meshID: mesh1
      multiCluster:
        clusterName: cluster2
      network: network2
EOF

Wait for the control plane to return the Ready status condition by running the following command:
```
$ oc --context "${CTX_CLUSTER2}" wait --for condition=Ready istio/default --timeout=3m
```

Create an East-West gateway on the West cluster by running the following command:

$ oc --context "${CTX_CLUSTER2}" apply -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/east-west-gateway-net2.yaml

Expose the services through the gateway by running the following command:

$ oc --context "${CTX_CLUSTER2}" apply -n istio-system -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/expose-services.yaml

Install a remote secret on the East cluster that provides access to the API server on the West cluster by running the following command:

$ istioctl create-remote-secret \
  --context="${CTX_CLUSTER2}" \
  --name=cluster2 | \
  oc --context="${CTX_CLUSTER1}" apply -f -

Install a remote secret on the West cluster that provides access to the API server on the East cluster by running the following command:

$ istioctl create-remote-secret \
  --context="${CTX_CLUSTER1}" \
  --name=cluster1 | \
  oc --context="${CTX_CLUSTER2}" apply -f -

Verifying a multi-cluster topology

Deploy sample applications and verify traffic on a multi-cluster topology on two OpenShift Container Platform clusters.

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

Prerequisites

You have installed the OpenShift Service Mesh Operator on all of the clusters that comprise the mesh.
You have completed "Creating certificates for a multi-cluster mesh".
You have completed "Applying certificates to a multi-cluster topology".
You have created an Istio Container Network Interface (CNI) resource.
You have istioctl installed on the laptop you will use to run these instructions.
You have installed a multi-cluster topology.

Procedure

Deploy sample applications on the East cluster:

Create a sample application namespace on the East cluster by running the following command:

$ oc --context "${CTX_CLUSTER1}" get project sample || oc --context="${CTX_CLUSTER1}" new-project sample

Label the application namespace to support sidecar injection by running the following command:
```
$ oc --context="${CTX_CLUSTER1}" label namespace sample istio-injection=enabled
```

Deploy the helloworld application:

Create the helloworld service by running the following command:

$ oc --context="${CTX_CLUSTER1}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml \
  -l service=helloworld -n sample

Create the helloworld-v1 deployment by running the following command:

$ oc --context="${CTX_CLUSTER1}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml \
  -l version=v1 -n sample

Deploy the sleep application by running the following command:

$ oc --context="${CTX_CLUSTER1}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/sleep/sleep.yaml -n sample

Wait for the helloworld application on the East cluster to return the Ready status condition by running the following command:
```
$ oc --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/helloworld-v1
```
Wait for the sleep application on the East cluster to return the Ready status condition by running the following command:
```
$ oc --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/sleep
```

Deploy the sample applications on the West cluster:

Create a sample application namespace on the West cluster by running the following command:

$ oc --context "${CTX_CLUSTER2}" get project sample || oc --context="${CTX_CLUSTER2}" new-project sample

Label the application namespace to support sidecar injection by running the following command:
```
$ oc --context="${CTX_CLUSTER2}" label namespace sample istio-injection=enabled
```

Deploy the helloworld application:

Create the helloworld service by running the following command:

$ oc --context="${CTX_CLUSTER2}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml \
  -l service=helloworld -n sample

Create the helloworld-v2 deployment by running the following command:

$ oc --context="${CTX_CLUSTER2}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml \
  -l version=v2 -n sample

Deploy the sleep application by running the following command:

$ oc --context="${CTX_CLUSTER2}" apply \
  -f https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/sleep/sleep.yaml -n sample

Wait for the helloworld application on the West cluster to return the Ready status condition by running the following command:
```
$ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/helloworld-v2
```
Wait for the sleep application on the West cluster to return the Ready status condition by running the following command:
```
$ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/sleep
```

Verifying traffic flows between clusters

For the East cluster, send 10 requests to the helloworld service by running the following command:
```
$ for i in {0..9}; do \
  oc --context="${CTX_CLUSTER1}" exec -n sample deploy/sleep -c sleep -- curl -sS helloworld.sample:5000/hello; \
done
```
Verify that you see responses from both clusters. This means version 1 and version 2 of the service can be seen in the responses.
For the West cluster, send 10 requests to the helloworld service:
```
$ for i in {0..9}; do \
  oc --context="${CTX_CLUSTER2}" exec -n sample deploy/sleep -c sleep -- curl -sS helloworld.sample:5000/hello; \
done
```
Verify that you see responses from both clusters. This means version 1 and version 2 of the service can be seen in the responses.

Removing a multi-cluster topology from a development environment

After experimenting with the multi-cluster functionality in a development environment, remove the multi-cluster topology from all the clusters.

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

Prerequisites

You have installed a multi-cluster topology.

Procedure

Remove Istio and the sample applications from the East cluster of the development environment by running the following command:
```
$ oc --context="${CTX_CLUSTER1}" delete istio/default ns/istio-system ns/sample ns/istio-cni
```
Remove Istio and the sample applications from the West cluster of development environment by running the following command:
```
$ oc --context="${CTX_CLUSTER2}" delete istio/default ns/istio-system ns/sample ns/istio-cni
```

Installing a primary-remote multi-network mesh

Install Istio in a primary-remote multi-network topology on two OpenShift Container Platform clusters.

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

You can adapt these instructions for a mesh spanning more than two clusters.

Prerequisites

You have installed the OpenShift Service Mesh 3 Operator on all of the clusters that comprise the mesh.
You have completed "Creating certificates for a multi-cluster mesh".
You have completed "Applying certificates to a multi-cluster topology".
You have created an Istio Container Network Interface (CNI) resource.
You have istioctl installed on the laptop you will use to run these instructions.

Procedure

Create an ISTIO_VERSION environment variable that defines the Istio version to install by running the following command:
```
$ export ISTIO_VERSION=1.24.1
```

Install Istio on the East cluster:

Set the default network for the East cluster by running the following command:

$ oc --context="${CTX_CLUSTER1}" label namespace istio-system topology.istio.io/network=network1

Create an Istio resource on the East cluster by running the following command:

$ cat <<EOF | oc --context "${CTX_CLUSTER1}" apply -f -
apiVersion: sailoperator.io/v1alpha1
kind: Istio
metadata:
  name: default
spec:
  version: v${ISTIO_VERSION}
  namespace: istio-system
  values:
    global:
      meshID: mesh1
      multiCluster:
        clusterName: cluster1
      network: network1
      externalIstiod: true (1)
EOF

1	This enables the control plane installed on the East cluster to serve as an external control plane for other remote clusters.

Wait for the control plane to return the "Ready" status condition by running the following command:
```
$ oc --context "${CTX_CLUSTER1}" wait --for condition=Ready istio/default --timeout=3m
```

Create an East-West gateway on the East cluster by running the following command:

$ oc --context "${CTX_CLUSTER1}" apply -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/east-west-gateway-net1.yaml

Expose the control plane through the gateway so that services in the West cluster can access the control plane by running the following command:

$ oc --context "${CTX_CLUSTER1}" apply -n istio-system -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/expose-istiod.yaml

Expose the application services through the gateway by running the following command:

$ oc --context "${CTX_CLUSTER1}" apply -n istio-system -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/expose-services.yaml

Install Istio on the West cluster:

Save the IP address of the East-West gateway running in the East cluster by running the following command:

$ export DISCOVERY_ADDRESS=$(oc --context="${CTX_CLUSTER1}" \
    -n istio-system get svc istio-eastwestgateway \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

Create an Istio resource on the West cluster by running the following command:

$ cat <<EOF | oc --context "${CTX_CLUSTER2}" apply -f -
apiVersion: sailoperator.io/v1alpha1
kind: Istio
metadata:
  name: default
spec:
  version: v${ISTIO_VERSION}
  namespace: istio-system
  profile: remote
  values:
    istiodRemote:
      injectionPath: /inject/cluster/cluster2/net/network2
    global:
      remotePilotAddress: ${DISCOVERY_ADDRESS}
EOF

Annotate the istio-system namespace in the West cluster so that it is managed by the control plane in the East cluster by running the following command:
```
$ oc --context="${CTX_CLUSTER2}" annotate namespace istio-system topology.istio.io/controlPlaneClusters=cluster1
```

Set the default network for the West cluster by running the following command:

$ oc --context="${CTX_CLUSTER2}" label namespace istio-system topology.istio.io/network=network2

Install a remote secret on the East cluster that provides access to the API server on the West cluster by running the following command:

$ istioctl create-remote-secret \
  --context="${CTX_CLUSTER2}" \
  --name=cluster2 | \
  oc --context="${CTX_CLUSTER1}" apply -f -

Wait for the Istio resource to return the "Ready" status condition by running the following command:
```
$ oc --context "${CTX_CLUSTER2}" wait --for condition=Ready istio/default --timeout=3m
```
Create an East-West gateway on the West cluster by running the following command:
```
$ oc --context "${CTX_CLUSTER2}" apply -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/multicluster/east-west-gateway-net2.yaml
```
Since the West cluster is installed with a remote profile, exposing the application services on the East cluster exposes them on the East-West gateways of both clusters.

Next steps