Installing

Procedure

1. In the OpenShift Container Platform web console, click Home → Projects.
2. Click Create Project.
3. At the prompt, enter a name for the project in the Name field. For example, istio-system. The other fields offer supplementary information to the Istio resource definition and are optional.
4. Click Create. The Service Mesh Operator deploys Istio to the project you specified.

Procedure

1. In the OpenShift Container Platform web console, click Operators → Installed Operators.
2. Select istio-system in the Project drop-down menu.
3. Click the Service Mesh Operator.
4. Click Istio.
5. Click Create Istio.
6. Select the istio-system project from the Namespace drop-down menu.

7. Click Create. This action deploys the Istio control plane.

   When State: Healthy displays in the Status column, Istio is successfully deployed.

Procedure

1. In the OpenShift Container Platform web console, click Home → Projects.
2. Click Create Project.
3. At the prompt, you must enter a name for the project in the Name field. For example, istio-cni. The other fields offer supplementary information and are optional.
4. Click Create.

Procedure

1. In the OpenShift Container Platform web console, click Operators → Installed Operators.
2. Select istio-cni in the Project drop-down menu.
3. Click the Service Mesh Operator.
4. Click IstioCNI.
5. Click Create IstioCNI.
6. Ensure that the name is default.

7. Click Create. This action deploys the Istio CNI plugin.

   When State: Healthy displays in the Status column, the Istio CNI plugin is successfully deployed.

Procedure

1. Add a label to the namespace containing the Istio control plane, for example, the istio-system system namespace, by running the following command:

   $ oc label namespace istio-system istio-discovery=enabled

2. Change the Istio control plane resource to include a discoverySelectors section with the same label, similar to the following example:

   kind: Istio
   apiVersion: sailoperator.io/v1
   metadata:
     name: default
   spec:
     namespace: istio-system
     values:
       meshConfig:
         discoverySelectors:
           - matchLabels:
               istio-discovery: enabled

3. Apply the Istio custom resource (CR) by running the following command:

1. Ensure that all namespaces that will contain workloads that are to be part of the Service Mesh have both the discoverySelector label and, if needed, the appropriate Istio injection label.

Procedure

1. In the OpenShift Container Platform web console, navigate to the Home → Projects page.
2. Click Create Project.

3. Enter bookinfo in the Project name field.

   The Display name and Description fields offer supplementary information and are not required.

4. Click Create.

5. Apply the Istio discovery selector and injection label to the bookinfo namespace by entering the following command:

   $ oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled

   Note

   In this example, the name of the Istio resource is default. If the Istio resource name is different, you must set the istio.io/rev label to the name of the Istio resource instead of adding the istio-injection=enabled label.

6. Apply the bookinfo YAML file to deploy the bookinfo application by entering the following command:

   oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo

Verification

1. Verify that the bookinfo service is available by running the following command:

   $ oc get services -n bookinfo

   You will get an output similar to the following example:

   NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
   details       ClusterIP   172.30.137.21   <none>        9080/TCP   44s
   productpage   ClusterIP   172.30.2.246    <none>        9080/TCP   43s
   ratings       ClusterIP   172.30.33.85    <none>        9080/TCP   44s
   reviews       ClusterIP   172.30.175.88   <none>        9080/TCP   44s

2. Verify that the bookinfo pods are available by running the following command:

   $ oc get pods -n bookinfo

   You will get an output similar to the following example:

   NAME                             READY   STATUS    RESTARTS   AGE
   details-v1-698d88b-km2jg         2/2     Running   0          66s
   productpage-v1-675fc69cf-cvxv9   2/2     Running   0          65s
   ratings-v1-6484c4d9bb-tpx7d      2/2     Running   0          65s
   reviews-v1-5b5d6494f4-wsrwp      2/2     Running   0          65s
   reviews-v2-5b667bcbf8-4lsfd      2/2     Running   0          65s
   reviews-v3-5b9bd44f4-44hr6       2/2     Running   0          65s

   When the Ready columns displays 2/2, the proxy sidecar was successfully injected. Confirm that Running displays in the Status column for each pod.

3. Verify that the bookinfo application is running by sending a request to the bookinfo page. Run the following command:

   $ oc exec "$(oc get pod -l app=ratings -n bookinfo -o jsonpath='{.items[0].metadata.name}')" -c ratings -n bookinfo -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"

Procedure

1. Create the istio-ingressgateway deployment and service by running the following command:

   $ oc apply -n bookinfo -f ingress-gateway.yaml

   Note

   This example uses a sample ingress-gateway.yaml file that is available in the Istio community repository.

2. Configure the bookinfo application to use the new gateway. Apply the gateway configuration by running the following command:

   $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/networking/bookinfo-gateway.yaml -n bookinfo

   Note

   To configure gateway injection with the bookinfo application, this example provides a sample gateway configuration file that you must apply in the application’s namespace.

3. Use a route to expose the gateway external to the cluster by running the following command:

   $ oc expose service istio-ingressgateway -n bookinfo

4. Change the YAML file to automatically scale the pod when ingress traffic increases.

   You can see the following example configuration for reference:

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     labels:
       istio: ingressgateway
       release: istio
     name: ingressgatewayhpa
     namespace: bookinfo
   spec:
     maxReplicas: 5
     metrics:
     - resource:
         name: cpu
         target:
           averageUtilization: 80
           type: Utilization
       type: Resource
     minReplicas: 2
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: istio-ingressgateway

   • spec.maxReplicas shows an example that sets the maximum replicas to 5 and the minimum replicas to 2. It also creates another replica when usage reaches 80%.

5. Specify the minimum number of pods that must be running on the node.

   You can see the following example configuration for reference:

   apiVersion: policy/v1
   kind: PodDisruptionBudget
   metadata:
     labels:
       istio: ingressgateway
       release: istio
     name: ingressgatewaypdb
     namespace: bookinfo
   spec:
     minAvailable: 1
     selector:
       matchLabels:
         istio: ingressgateway

   spec.minAvailable shows an example that ensures one replica is running if a pod gets restarted on a new node.

6. Obtain the gateway hostname and the URL for the product page by running the following command:

   $ HOST=$(oc get route istio-ingressgateway -n bookinfo -o jsonpath='{.spec.host}')

7. Verify that the productpage is accessible from a web browser by running the following command:

   $ echo productpage URL: http://$HOST/productpage

Procedure

1. Enable the Gateway API CRDs for OpenShift Container Platform 4.18 and earlier, by running the following command:

   $ oc get crd gateways.gateway.networking.k8s.io &> /dev/null ||  { oc kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.0.0" | oc apply -f -; }

2. Create and configure a gateway by using the Gateway and HTTPRoute resources by running the following command:

   $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/gateway-api/bookinfo-gateway.yaml -n bookinfo

   Note

   To configure a gateway with the bookinfo application by using the Gateway API, this example provides a sample gateway configuration file that you must apply to the application’s namespace.

3. Ensure that the Gateway API service is ready, and has an address allocated by running the following command:

   $ oc wait --for=condition=programmed gtw bookinfo-gateway -n bookinfo

4. Retrieve the host by running the following command:

   $ export INGRESS_HOST=$(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.status.addresses[0].value}')

5. Retrieve the port by running the following command:

   $ export INGRESS_PORT=$(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')

6. Retrieve the gateway URL by running the following command:

   $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

7. Obtain the gateway hostname and the URL of the product page by running the following command:

   $ echo "http://${GATEWAY_URL}/productpage"

Procedure

1. In the OpenShift Container Platform web console, click Installed Operators.
2. Click Red Hat OpenShift Service Mesh 3 Operator.
3. Click Istio.
4. Click the name of the Istio installation. For example, default.
5. Click YAML.

6. Change the Istio custom resource (CR) similar to the following example:

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: default
   spec:
     namespace: istio-system
     values:
       pilot:
         autoscaleMin: 2
         autoscaleMax: 5
         cpu:
           targetAverageUtilization: 80
         memory:
           targetAverageUtilization: 80

   • spec.values.pilot.autoscaleMin specifies the minimum number of Istio control plane replicas that always run.
   • spec.values.pilot.autoscaleMax specifies the maximum number of Istio control plane replicas, allowing for scaling based on load. To support HA, there must be at least two replicas.
   • spec.values.pilot.cpu.targetAverageUtilization specifies the target CPU usage for autoscaling to 80%. If the average CPU usage exceeds this threshold, the Horizontal Pod Autoscaler (HPA) automatically increases the number of replicas.
   • spec.values.pilot.memory.targetAverageUtilization specifies the target memory usage for autoscaling to 80%. If the average memory usage exceeds this threshold, the HPA automatically increases the number of replicas.

Procedure

1. Obtain the name of the Istio resource by running the following command:

   $ oc get istio -n istio-sytem

   You will get an output similar to the following example:

   NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
   default   1           1       0        default           Healthy   v1.24.6   24m

   The name of the Istio resource is default.

2. Update the Istio custom resource (CR) by adding the autoscaleEnabled and replicaCount parameters by running the following command:

   $ oc patch istio default -n istio-system --type merge -p '
   spec:
     values:
       pilot:
         autoscaleEnabled: false
         replicaCount: 2
   '

   • spec.values.pilot.autoscaleEnabled specifies a setting that disables autoscaling and ensures that the number of replicas remains fixed.
   • spec.values.pilot.replicaCount specifies the number of Istio control plane replicas. To support HA, there must be at least two replicas.

Verification

1. Verify the status of the Istio control pods by running the following command:

   $ oc get pods -n istio-system -l app=istiod

   You will get an output similar to the following example:

   NAME                      READY   STATUS    RESTARTS   AGE
   istiod-7c7b6564c9-nwhsg   1/1     Running   0          70s
   istiod-7c7b6564c9-xkmsl   1/1     Running   0          85s

   Two istiod pods are running, which is the minimum requirement for an HA Istio control plane and indicates that a basic HA setup is in place.

Procedure

1. Verify the revision name of the Istio control plane using the following command:

   $ oc get istiorevisions

   You should see output similar to the following example:

   Example output

   NAME      TYPE    READY   STATUS    IN USE   VERSION   AGE
   default   Local   True    Healthy   False    v1.23.0   4m57s

   Since the revision name is default, you can use the default injection labels without referencing the exact revision name.

2. Verify that workloads already running in the required namespace show 1/1 containers as READY by using the following command. This confirms that the pods are running without sidecars.

   $ oc get pods -n bookinfo

   You should see output similar to the following example:

   Example output

   NAME                             READY   STATUS    RESTARTS   AGE
   details-v1-65cfcf56f9-gm6v7      1/1     Running   0          4m55s
   productpage-v1-d5789fdfb-8x6bk   1/1     Running   0          4m53s
   ratings-v1-7c9bd4b87f-6v7hg      1/1     Running   0          4m55s
   reviews-v1-6584ddcf65-6wqtw      1/1     Running   0          4m54s
   reviews-v2-6f85cb9b7c-w9l8s      1/1     Running   0          4m54s
   reviews-v3-6f5b775685-mg5n6      1/1     Running   0          4m54s

3. To apply the injection label to the bookinfo namespace, run the following command at the CLI:

   $ oc label namespace bookinfo istio-injection=enabled
   namespace/bookinfo labeled

4. To ensure the control plane applies sidecar injection, redeploy the workloads in the bookinfo namespace. Use the following command to perform a rolling update of all workloads:

   $ oc -n bookinfo rollout restart deployments

Verification

1. Verify the rollout by checking that the new pods display 2/2 containers as READY, confirming successful sidecar injection by running the following command:

   $ oc get pods -n bookinfo

   You should see output similar to the following example:

   You will get an output similar to the following example:

   NAME                              READY   STATUS    RESTARTS   AGE
   details-v1-7745f84ff-bpf8f        2/2     Running   0          55s
   productpage-v1-54f48db985-gd5q9   2/2     Running   0          55s
   ratings-v1-5d645c985f-xsw7p       2/2     Running   0          55s
   reviews-v1-bd5f54b8c-zns4v        2/2     Running   0          55s
   reviews-v2-5d7b9dbf97-wbpjr       2/2     Running   0          55s
   reviews-v3-5fccc48c8c-bjktn       2/2     Running   0          55s

Procedure

1. Open the application’s Deployment resource in an editor. In this case, exclude the ratings-v1 service.

2. Change the spec.template.metadata.labels section of your Deployment resource to include the label sidecar.istio.io/inject: false to disable sidecar injection.

   kind: Deployment
   apiVersion: apps/v1
   metadata:
   name: ratings-v1
   namespace: bookinfo
   labels:
     app: ratings
     version: v1
   spec:
     template:
       metadata:
         labels:
           sidecar.istio.io/inject: 'false'

   Note

   Adding the label to the top-level labels section of the Deployment does not affect sidecar injection.

   Updating the deployment triggers a rollout, creating a new ReplicaSet with updated pod(s).

Verification

1. Verify that the updated pod(s) do not contain a sidecar container and show 1/1 containers as Running by running the following command:

   $ oc get pods -n bookinfo

   You should see output similar to the following example:

   You will get an output similar to the following example:

   NAME                              READY   STATUS    RESTARTS   AGE
   details-v1-6bc7b69776-7f6wz       2/2     Running   0          29m
   productpage-v1-54f48db985-gd5q9   2/2     Running   0          29m
   ratings-v1-5d645c985f-xsw7p       1/1     Running   0          7s
   reviews-v1-bd5f54b8c-zns4v        2/2     Running   0          29m
   reviews-v2-5d7b9dbf97-wbpjr       2/2     Running   0          29m
   reviews-v3-5fccc48c8c-bjktn       2/2     Running   0          29m

Procedure

1. Verify the revision name of the Istio control plane by running the following command:

   $ oc get istiorevisions

   You should see output similar to the following example:

   You will get an output similar to the following example:

   NAME      TYPE    READY   STATUS    IN USE   VERSION   AGE
   my-mesh   Local   True    Healthy   False    v1.23.0   47s

   Since the revision name is my-mesh, use the revision label istio.io/rev=my-mesh to enable sidecar injection.

2. Verify that workloads already running show 1/1 containers as READY, indicating that the pods are running without sidecars by running the following command:

   $ oc get pods -n bookinfo

   You should see output similar to the following example:

   You will get an output similar to the following example:

   NAME                             READY   STATUS    RESTARTS   AGE
   details-v1-65cfcf56f9-gm6v7      1/1     Running   0          4m55s
   productpage-v1-d5789fdfb-8x6bk   1/1     Running   0          4m53s
   ratings-v1-7c9bd4b87f-6v7hg      1/1     Running   0          4m55s
   reviews-v1-6584ddcf65-6wqtw      1/1     Running   0          4m54s
   reviews-v2-6f85cb9b7c-w9l8s      1/1     Running   0          4m54s
   reviews-v3-6f5b775685-mg5n6      1/1     Running   0          4m54s

3. Open the application’s Deployment resource in an editor. In this case, update the ratings-v1 service.

4. Update the spec.template.metadata.labels section of your Deployment to include the appropriate pod injection or revision label. In this case, istio.io/rev: my-mesh:

   kind: Deployment
   apiVersion: apps/v1
   metadata:
   name: ratings-v1
   namespace: bookinfo
   labels:
     app: ratings
     version: v1
   spec:
     template:
       metadata:
         labels:
           istio.io/rev: my-mesh

   Note

   Adding the label to the top-level labels section of the Deployment resource does not impact sidecar injection.

   Updating the deployment triggers a rollout, creating a new ReplicaSet with the updated pod(s).

Verification

1. Verify that only the ratings-v1 pod now shows 2/2 containers READY, indicating that the sidecar has been successfully injected by running the following command:

   $ oc get pods -n bookinfo

   You should see output similar to the following example:

   You will get an output similar to the following example:

   NAME                              READY   STATUS    RESTARTS   AGE
   details-v1-559cd49f6c-b89hw       1/1     Running   0          42m
   productpage-v1-5f48cdcb85-8ppz5   1/1     Running   0          42m
   ratings-v1-848bf79888-krdch       2/2     Running   0          9s
   reviews-v1-6b7444ffbd-7m5wp       1/1     Running   0          42m
   reviews-v2-67876d7b7-9nmw5        1/1     Running   0          42m
   reviews-v3-84b55b667c-x5t8s       1/1     Running   0          42m

2. Repeat for other workloads that you want to include in the mesh.

Procedure

1. Create the istio-system namespace by running the following command:

   $ oc create namespace istio-system

2. Create the root issuer by creating an Issuer object in a YAML file.

   1. Create an Issuer object similar to the following example:

      Note

      The selfSigned issuer serves demonstration purposes, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA.

      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: selfsigned
        namespace: istio-system
      spec:
        selfSigned: {}
      ---
      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
          name: istio-ca
          namespace: istio-system
      spec:
        isCA: true
        duration: 87600h # 10 years
        secretName: istio-ca
        commonName: istio-ca
        privateKey:
          algorithm: ECDSA
          size: 256
        subject:
          organizations:
            - cluster.local
            - cert-manager
        issuerRef:
          name: selfsigned
          kind: Issuer
          group: cert-manager.io
      ---
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: istio-ca
        namespace: istio-system
      spec:
        ca:
          secretName: istio-ca
      ---

   2. Create the objects by running the following command:

      $ oc apply -f issuer.yaml

   3. Wait for the istio-ca certificate to contain the "Ready" status condition by running the following command:

      $ oc wait --for=condition=Ready certificates/istio-ca -n istio-system

3. Copy the istio-ca certificate to the cert-manager namespace so it can be used by istio-csr:

   apiVersion: operator.openshift.io/v1alpha1
   kind: IstioCSR
   metadata:
     name: default
     namespace: istio-csr
   spec:
     istioCSRConfig:
       certManager:
         issuerRef:
           name: istio-ca
           kind: Issuer
           group: cert-manager.io
       istiodTLSConfig:
         trustDomain: cluster.local
       istio:
         namespace: istio-system

   1. Create the istio-csr agent by running the following command:

      $ oc create -f istioCSR.yaml

   2. Verify that the istio-csr deployment is ready by running the following command:

      $ oc get deployment -n istio-csr

4. Install the istio resource:

   Note

   The configuration disables the built-in CA server for Istio and forwards certificate signing requests from istiod to the istio-csr agent. The istio-csr agent obtains certificates for both istiod and mesh workloads from the cert-manager Operator. The istio-csr agent generates the istiod TLS certificate, and the system mounts it into the pod at a known location.

   1. Create the Istio object similar to the following example:

      apiVersion: sailoperator.io/v1
      kind: Istio
      metadata:
        name: default
      spec:
        version: v1.24-latest
        namespace: istio-system
        values:
          global:
            caAddress: cert-manager-istio-csr.istio-csr.svc:443
          pilot:
            env:
              ENABLE_CA_SERVER: "false"

   2. Create the Istio resource by running the following command:

      $ oc apply -f istio.yaml

   3. Verify that the istio resource displays the "Ready" status condition by running the following command:

      $ oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem

   4. Create a secret from the local certificate file in the cert-manager namespace by running the following command:

      $ oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem

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:

      You can see the following example configuration for reference:

      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:

      You can see the following example configuration for reference:

      [ 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 the intermediate certificate of the West cluster. Copy the following example file and save it locally:

      You can see the following example configuration for reference:

      [ 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

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 has 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 be present in the east/ directory. If your certificates are present in a different directory, change the syntax.

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 has 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 be present in the west/ directory. If your certificates are present in a different directory, change the syntax.

Procedure

1. Deploy sample applications on the East cluster:

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

   2. Label the application namespace to support sidecar injection by running the following command:

      $ oc --context="${CTX_CLUSTER1}" label namespace sample istio-injection=enabled

   3. Deploy the helloworld application:

      1. Create the helloworld service by running the following command:

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

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

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

   4. Deploy the sleep application by running the following command:

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

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

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

2. Deploy the sample applications on the West cluster:

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

   2. Label the application namespace to support sidecar injection by running the following command:

      $ oc --context="${CTX_CLUSTER2}" label namespace sample istio-injection=enabled

   3. Deploy the helloworld application:

      1. Create the helloworld service by running the following command:

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

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

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

   4. Deploy the sleep application by running the following command:

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

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

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

Verification

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

2. 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 the responses show both version 1 and version 2 of the service.

Procedure

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

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

Procedure

1. Create the namespace for the first Istio control plane called istio-system-1 by running the following command:

   $ oc new-project istio-system-1

2. Label the first namespace, which the Istio discoverySelectors field uses by running the following command:

   $ oc label namespace istio-system-1 istio-discovery=mesh-1

3. Create a YAML file named istio-1.yaml with the name mesh-1 and the discoverySelector as mesh-1 similar to the following example:

   kind: Istio
   apiVersion: sailoperator.io/v1
   metadata:
     name: mesh-1
   spec:
     namespace: istio-system-1
     values:
       meshConfig:
         discoverySelectors:
           - matchLabels:
               istio-discovery: mesh-1
   # ...

4. Create the first Istio resource by running the following command:

   $ oc apply -f istio-1.yaml

5. To restrict workloads in mesh-1 from communicating freely with decrypted traffic between meshes, deploy a PeerAuthentication resource to enforce mutual TLS (mTLS) traffic within the mesh-1 data plane. Apply the PeerAuthentication resource in the istio-system-1 namespace by using a configuration file, such as peer-auth-1.yaml, by running the following command:

   $ oc apply -f peer-auth-1.yaml

   You can see the following example configuration for reference:

   apiVersion: security.istio.io/v1
   kind: PeerAuthentication
   metadata:
     name: "mesh-1-peerauth"
     namespace: "istio-system-1"
   spec:
     mtls:
       mode: STRICT

Procedure

1. Create a namespace for the second Istio control plane called istio-system-2 by running the following command:

   $ oc new-project istio-system-2

2. Label the second namespace, which the Istio discoverySelectors field uses by running the following command:

   $ oc label namespace istio-system-2 istio-discovery=mesh-2

3. Create a YAML file named istio-2.yaml similar to the following example:

   kind: Istio
   apiVersion: sailoperator.io/v1
   metadata:
     name: mesh-2
   spec:
     namespace: istio-system-2
     values:
       meshConfig:
         discoverySelectors:
           - matchLabels:
               istio-discovery: mesh-2
   # ...

4. Create the second Istio resource by running the following command:

   $ oc apply -f istio-2.yaml

5. Deploy a policy for workloads in the istio-system-2 namespace to only accept mutual TLS traffic peer-auth-2.yaml by running the following command:

   $ oc apply -f peer-auth-2.yaml

   You can see the following example configuration for reference:

   apiVersion: security.istio.io/v1
   kind: PeerAuthentication
   metadata:
     name: "mesh-2-peerauth"
     namespace: "istio-system-2"
   spec:
     mtls:
       mode: STRICT

1. Verify that the control plane in istio-system-1 manages the workloads by running the following command:

   $ oc get pods -n istio-system-1

   You will get an output similar to the following example:

   NAME                            READY   STATUS    RESTARTS   AGE
   istiod-mesh-1-b69646b6f-kxrwk   1/1     Running   0          4m14s

2. Verify that the control plane in istio-system-2 manages the workloads by running the following command:

   $ oc get pods -n istio-system-2

   You will get an output similar to the following example:

   NAME                            READY   STATUS    RESTARTS   AGE
   istiod-mesh-2-8666fdfc6-mqp45   1/1     Running   0          118s

Procedure

1. Create an ISTIO_VERSION environment variable that defines the Istio version to install on all the clusters by running the following command:

   $ export ISTIO_VERSION=1.24.3

2. Create a REMOTE_CLUSTER_NAME environment variable that defines the name of the cluster by running the following command:

   $ export REMOTE_CLUSTER_NAME=cluster1

3. Set up the environment variable that contains the oc command context for the control plane cluster by running the following command:

   $ export CTX_CONTROL_PLANE_CLUSTER=<context_name_of_the_control_plane_cluster>

4. Set up the environment variable that contains the oc command context for the data plane cluster by running the following command:

   $ export CTX_DATA_PLANE_CLUSTER=<context_name_of_the_data_plane_cluster>

5. Set up the ingress gateway for the control plane:

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

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

   2. Create an Istio resource on the control plane cluster to manage the ingress gateway by running the following command:

      $ cat <<EOF | oc --context "${CTX_CONTROL_PLANE_CLUSTER}" apply -f -
      apiVersion: sailoperator.io/v1
      kind: Istio
      metadata:
        name: default
      spec:
        version: v${ISTIO_VERSION}
        namespace: istio-system
        value:
          global:
            network: network1
      EOF

   3. Create the ingress gateway for the control plane by running the following command:

      $ oc --context "${CTX_CONTROL_PLANE_CLUSTER}" apply -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/deployment-models/resources/controlplane-gateway.yaml

   4. Get the assigned IP address for the ingress gateway by running the following command:

      $ oc --context "${CTX_CONTROL_PLANE_CLUSTER}" get svc istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

   5. Store the IP address of the ingress gateway in an environment variable by running the following command:

      $ export EXTERNAL_ISTIOD_ADDR=$(oc -n istio-system --context="${CTX_CONTROL_PLANE_CLUSTER}" get svc istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

6. Install Istio on the data plane cluster:

   1. Create a project called external-istiod on the data plane cluster by running the following command:

      $ oc get project external-istiod --context "${CTX_DATA_PLANE_CLUSTER}" || oc new-project external-istiod --context "${CTX_DATA_PLANE_CLUSTER}"

   2. Create an Istio resource on the data plane cluster by running the following command:

      $ cat <<EOF | oc --context "${CTX_DATA_PLANE_CLUSTER}" apply -f -
      apiVersion: sailoperator.io/v1
      kind: Istio
      metadata:
        name: external-istiod
      spec:
        version: v${ISTIO_VERSION}
        namespace: external-istiod
        profile: remote
        values:
          defaultRevision: external-istiod
          global:
            remotePilotAddress: ${EXTERNAL_ISTIOD_ADDR}
            configCluster: true 

      1

      
          pilot:
            configMap: true
            istiodRemote:
              injectionPath: /inject/cluster/cluster2/net/network1
      EOF

      1

      This setting identifies the data plane cluster as the source of the mesh configuration.

7. Create a project called istio-cni on the data plane cluster by running the following command:

   $ oc get project istio-cni --context "${CTX_DATA_PLANE_CLUSTER}" || oc new-project istio-cni --context "${CTX_DATA_PLANE_CLUSTER}"

   1. Create an IstioCNI resource on the data plane cluster by running the following command:

      $ cat <<EOF | oc --context "${CTX_DATA_PLANE_CLUSTER}" apply -f -
      apiVersion: sailoperator.io/v1
      kind: IstioCNI
      metadata:
        name: default
      spec:
        version: v${ISTIO_VERSION}
        namespace: istio-cni
      EOF

8. Set up the external Istio control plane on the control plane cluster:

   1. Create a project called external-istiod on the control plane cluster by running the following command:

      $ oc get project external-istiod --context "${CTX_CONTROL_PLANE_CLUSTER}" || oc new-project external-istiod --context "${CTX_CONTROL_PLANE_CLUSTER}"

   2. Create a ServiceAccount resource on the control plane cluster by running the following command:

      $ oc --context="${CTX_CONTROL_PLANE_CLUSTER}" create serviceaccount istiod-service-account -n external-istiod

   3. Store the API server address for the data plane cluster in an environment variable by running the following command:

      $ DATA_PLANE_API_SERVER=https://<hostname_or_IP_address_of_the_API_server_for_the_data_plane_cluster>:6443

   4. Install a remote secret on the control plane cluster that provides access to the API server on the data plane cluster by running the following command:

      $ istioctl create-remote-secret \
        --context="${CTX_DATA_PLANE_CLUSTER}" \
        --type=config \
        --namespace=external-istiod \
        --service-account=istiod-external-istiod \
        --create-service-account=false \
        --server="${DATA_PLANE_API_SERVER}" | \
        oc --context="${CTX_CONTROL_PLANE_CLUSTER}" apply -f -

   5. Create an Istio resource on the control plane cluster by running the following command:

      $ cat <<EOF | oc --context "${CTX_CONTROL_PLANE_CLUSTER}" apply -f -
      apiVersion: sailoperator.io/v1
      kind: Istio
      metadata:
        name: external-istiod
      spec:
        version: v${ISTIO_VERSION}
        namespace: external-istiod
        profile: empty
        values:
          meshConfig:
            rootNamespace: external-istiod
            defaultConfig:
              discoveryAddress: $EXTERNAL_ISTIOD_ADDR:15012
          pilot:
            enabled: true
            volumes:
              - name: config-volume
                configMap:
                  name: istio-external-istiod
              - name: inject-volume
                configMap:
                  name: istio-sidecar-injector-external-istiod
            volumeMounts:
              - name: config-volume
                mountPath: /etc/istio/config
              - name: inject-volume
                mountPath: /var/lib/istio/inject
            env:
              INJECTION_WEBHOOK_CONFIG_NAME: "istio-sidecar-injector-external-istiod-external-istiod"
              VALIDATION_WEBHOOK_CONFIG_NAME: "istio-validator-external-istiod-external-istiod"
              EXTERNAL_ISTIOD: "true"
              LOCAL_CLUSTER_SECRET_WATCHER: "true"
              CLUSTER_ID: cluster2
              SHARED_MESH_CONFIG: istio
          global:
            caAddress: $EXTERNAL_ISTIOD_ADDR:15012
            configValidation: false
            meshID: mesh1
            multiCluster:
              clusterName: cluster2
            network: network1
      EOF

   6. Create Gateway and VirtualService resources so that the sidecar proxies on the data plane cluster can access the control plane by running the following command:

      $ oc --context "${CTX_CONTROL_PLANE_CLUSTER}" apply -f - <<EOF
      apiVersion: networking.istio.io/v1
      kind: Gateway
      metadata:
        name: external-istiod-gw
        namespace: external-istiod
      spec:
        selector:
          istio: ingressgateway
        servers:
          - port:
              number: 15012
              protocol: tls
              name: tls-XDS
            tls:
              mode: PASSTHROUGH
            hosts:
            - "*"
          - port:
              number: 15017
              protocol: tls
              name: tls-WEBHOOK
            tls:
              mode: PASSTHROUGH
            hosts:
            - "*"
      ---
      apiVersion: networking.istio.io/v1
      kind: VirtualService
      metadata:
        name: external-istiod-vs
        namespace: external-istiod
      spec:
          hosts:
          - "*"
          gateways:
          - external-istiod-gw
          tls:
          - match:
            - port: 15012
              sniHosts:
              - "*"
            route:
            - destination:
                host: istiod-external-istiod.external-istiod.svc.cluster.local
                port:
                  number: 15012
          - match:
            - port: 15017
              sniHosts:
              - "*"
            route:
            - destination:
                host: istiod-external-istiod.external-istiod.svc.cluster.local
                port:
                  number: 443
      EOF

   7. Wait for the external-istiod Istio resource on the control plane cluster to return the "Ready" status condition by running the following command:

      $ oc --context "${CTX_CONTROL_PLANE_CLUSTER}" wait --for condition=Ready istio/external-istiod --timeout=3m

   8. Wait for the Istio resource on the data plane cluster to return the "Ready" status condition by running the following command:

      $ oc --context "${CTX_DATA_PLANE_CLUSTER}" wait --for condition=Ready istio/external-istiod --timeout=3m

   9. Wait for the IstioCNI resource on the data plane cluster to return the "Ready" status condition by running the following command:

      $ oc --context "${CTX_DATA_PLANE_CLUSTER}" wait --for condition=Ready istiocni/default --timeout=3m

Verification

1. Deploy sample applications on the data plane cluster:

   1. Create a namespace for sample applications on the data plane cluster by running the following command:

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

   2. Label the namespace for the sample applications to support sidecar injection by running the following command:

      $ oc --context="${CTX_DATA_PLANE_CLUSTER}" label namespace sample istio.io/rev=external-istiod

   3. Deploy the helloworld application:

      1. Create the helloworld service by running the following command:

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

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

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

   4. Deploy the sleep application by running the following command:

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

   5. Verify that the pods on the sample namespace have a sidecar injected by running the following command:

      $ oc --context="${CTX_DATA_PLANE_CLUSTER}" get pods -n sample

      The terminal should return 2/2 for each pod on the sample namespace by running the following command:

      Example output

      NAME                             READY   STATUS    RESTARTS   AGE
      helloworld-v1-6d65866976-jb6qc   2/2     Running   0          1m
      sleep-5fcd8fd6c8-mg8n2           2/2     Running   0          1m

2. Verify that internal traffic can reach the applications on the cluster:

   1. Verify a request can be sent to the helloworld application through the sleep application by running the following command:

      $ oc exec --context="${CTX_DATA_PLANE_CLUSTER}" -n sample -c sleep deploy/sleep -- curl -sS helloworld.sample:5000/hello

      The terminal should return a response from the helloworld application:

      Example output

      Hello version: v1, instance: helloworld-v1-6d65866976-jb6qc

3. Install an ingress gateway to expose the sample application to external clients:

   1. Create the ingress gateway by running the following command:

      $ oc --context="${CTX_DATA_PLANE_CLUSTER}" apply
      -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/refs/heads/main/chart/samples/ingress-gateway.yaml -n sample

   2. Confirm that the ingress gateway is running by running the following command:

      $ oc get pod -l app=istio-ingressgateway -n sample --context="${CTX_DATA_PLANE_CLUSTER}"

      The terminal should return output confirming that the gateway is running:

      Example output

      NAME                                    READY   STATUS    RESTARTS   AGE
      istio-ingressgateway-7bcd5c6bbd-kmtl4   1/1     Running   0          8m4s

   3. Expose the helloworld application through the ingress gateway by running the following command:

      $ oc apply -f https://raw.githubusercontent.com/istio/istio/refs/heads/master/samples/helloworld/helloworld-gateway.yaml -n sample --context="${CTX_DATA_PLANE_CLUSTER}"

   4. Set the gateway URL environment variable by running the following command:

      $ export INGRESS_HOST=$(oc -n sample --context="${CTX_DATA_PLANE_CLUSTER}" get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}'); \
        export INGRESS_PORT=$(oc -n sample --context="${CTX_DATA_PLANE_CLUSTER}" get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}'); \
        export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

4. Verify that external traffic can reach the applications on the mesh:

   1. Confirm that the helloworld application is accessible through the gateway by running the following command:

      $ curl -s "http://${GATEWAY_URL}/hello"

      The helloworld application should return a response.

      Example output

      Hello version: v1, instance: helloworld-v1-6d65866976-jb6qc