SupportConsoleDevelopersStart a trialContact

Chapter 5. Multi-Cluster topologies

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

5.1. 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.

5.1.1. 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.

5.1.2. 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.

5.2. 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.

5.2.1. 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

  1. Create the root CA certificate:

    1. Create a key for the root certificate by running the following command: 

      $ openssl genrsa -out root-key.pem 4096

    2. 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

    3. 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

    4. 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

  2. Create the intermediate CA certificate for the East cluster:

    1. Create a directory named east by running the following command: 

      $ mkdir east

    2. Create a key for the intermediate certificate for the East cluster by running the following command: 

      $ openssl genrsa -out east/ca-key.pem 4096

    3. 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

    4. 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

    5. 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

    6. 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

  3. Create the intermediate CA certificate for the West cluster:

    1. Create a directory named west by running the following command: 

      $ mkdir west

    2. Create a key for the intermediate certificate for the West cluster by running the following command: 

      $ openssl genrsa -out west/ca-key.pem 4096

    3. 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

    4. 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

    5. 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

    6. 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

5.2.2. Applying certificates to a multi-cluster topology

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

Note

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

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

    1. Log in to East cluster by running the following command: 

      $ oc login -u https://<east_cluster_api_server_url>

    2. 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)

    3. 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}"

    4. 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

    5. 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
      Note

      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.

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

    1. Log in to the West cluster by running the following command: 

      $ oc login -u https://<west_cluster_api_server_url>

    2. 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)

    3. 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}"

    4. 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

    5. 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
      Note

      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.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.