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 provide 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

   appears 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 provide 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

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

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

2. Modify the

   Istio

   control plane resource to include a

   discoverySelectors

   section with the same label.

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

3. Apply the Istio CR:

   $ oc apply -f istio.yaml

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

   Example output

   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

   Example output

   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

   appears 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 uses a sample gateway configuration file that must be applied in the namespace where the application is installed.

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. Modify the YAML file to automatically scale the pod when ingress traffic increases.

   Example configuration

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     labels:
       istio: ingressgateway
       release: istio
     name: ingressgatewayhpa
     namespace: bookinfo
   spec:
     maxReplicas: 5 

   1

   
     metrics:
     - resource:
         name: cpu
         target:
           averageUtilization: 80
           type: Utilization
       type: Resource
     minReplicas: 2
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: istio-ingressgateway

   1

   This example sets the the maximum replicas to 5 and the minimum replicas to 2. It also creates another replica when utilization reaches 80%.

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

   Example configuration

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

   1

   
     selector:
       matchLabels:
         istio: ingressgateway

   1

   This example ensures one replica is running if a pod gets restarted on a new node.

6. Obtain the gateway host name 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 uses a sample gateway configuration file that must be applied in the namespace where the application is installed.

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 host name 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. Modify the

   Istio

   custom resource (CR) similar to the following example:

   Example configuration

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: default
   spec:
     namespace: istio-system
     values:
       pilot:
         autoscaleMin: 2 

   1

   
         autoscaleMax: 5 

   2

   
         cpu:
           targetAverageUtilization: 80 

   3

   
         memory:
           targetAverageUtilization: 80 

   4

   1

   Specifies the minimum number of Istio control plane replicas that always run.

   2

   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.

   3

   Specifies the target CPU utilization for autoscaling to 80%. If the average CPU usage exceeds this threshold, the Horizontal Pod Autoscaler (HPA) automatically increases the number of replicas.

   4

   Specifies the target memory utilization 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

   Example output

   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 

   1

   
         replicaCount: 2 

   2

   
   '

   1

   Specifies a setting that disables autoscaling and ensures that the number of replicas remains fixed.

   2

   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

   Example output

   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 desired 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 sidecar injection is applied, redeploy the existing 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:

   Example output

   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. Modify 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:

   Example output

   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:

   Example output

   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:

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

   Example output

   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 wish to include in the mesh.

Procedure

1. Add a label to the namespace containing the

   Istio

   control plane resource, for example, the

   istio-system

   namespace, by running the following command:

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

2. Add a label to the namespace containing the

   IstioCNI

   resource, for example, the

   istio-cni

   namespace, by running the following command:

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

3. Add a label to the namespace containing the

   Ztunnel

   resource, for example, the

   ztunnel

   namespace, by running the following command:

   $ oc label namespace ztunnel istio-discovery=enabled

4. Modify the

   Istio

   control plane resource to include a

   discoverySelectors

   section with the same label:

   1. Create a YAML file with the name

      istio-discovery-selectors.yaml

      similar to the following example:

      Example configuration

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

   2. Apply the YAML file to

      Istio

      control plane resource by running the following command:

      $ oc apply -f istio-discovery-selectors.yaml

Procedure

1. Create the

   istio-system

   namespace by running the following command:

   $ oc create namespace istio-system

2. Patch the cert-manager Operator to install the

   istio-csr

   agent by running the following command:

   $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator \
     --type='merge' -p \
     '{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}'

3. Create the root certificate authority (CA) issuer by creating an

   Issuer

   object for the

   istio-csr

   agent:

   1. Create a new project for installing the

      istio-csr

      agent by running the following command:

      $ oc new-project istio-csr

   2. Create an

      Issuer

      object similar to the following example:
      Note

      The

      selfSigned

      issuer is intended for demonstration, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA.

      Example issuer.yaml file

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

   3. Create the objects by running the following command:

      $ oc apply -f issuer.yaml

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

4. Create the

   IstioCSR

   custom resource:

   1. Create the

      IstioCSR

      custom resource similar to the following example:

      Example istioCSR.yaml file

      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

   2. Create the

      istio-csr

      agent by by running the following command:

      $ oc create -f istioCSR.yaml

   3. Verify that the

      istio-csr

      deployment is ready by running the following command:

      $ oc get deployment -n istio-csr

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

   istiod

   TLS certificate that is generated by the

   istio-csr

   agent is mounted into the pod at a known location for use.

   1. Create the

      Istio

      object similar to the following example:

      Example istio.yaml file

      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 wait --for=condition=Ready istios/default -n istio-system

1. Create the namespaces:

   1. Create the

      apps-1

      namespace by running the following command:

      $ oc new-project apps-1

   2. Create the

      apps-2

      namespace by running the following command:

      $ oc new-project apps-2

2. Add the

   istio-injection=enabled

   label on the namespaces:

   1. Add the

      istio-injection=enabled

      label on the

      apps-1

      namespace by running the following command:

      $ oc label namespaces apps-1 istio-injection=enabled

   2. Add the

      istio-injection=enabled

      label on the

      apps-2

      namespace by running the following command:

      $ oc label namespaces apps-2 istio-injection=enabled

3. Deploy the

   httpbin

   app in the namespaces:

   1. Deploy the

      httpbin

      app in the

      apps-1

      namespace by running the following command:

      $ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml

   2. Deploy the

      httpbin

      app in the

      apps-2

      namespace by running the following command:

      $ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml

4. Deploy the

   sleep

   app in the namespaces:

   1. Deploy the

      sleep

      app in the

      apps-1

      namespace by running the following command:

      $ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml

   2. Deploy the

      sleep

      app in the

      apps-2

      namespace by running the following command:

      $ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml

5. Verify that the created apps have sidecars injected:

   1. Verify that the created apps have sidecars injected for

      apps-1

      namespace by running the following command:

      $ oc get pods -n apps-1

   2. Verify that the created apps have sidecars injected for

      apps-2

      namespace by running the following command:

      $ oc get pods -n apps-2

6. Create a mesh-wide strict mutual Transport Layer Security (mTLS) policy similar to the following example:

   Note

   Enabling

   PeerAuthentication

   in strict mTLS mode verifies that certificates are distributed correctly and that mTLS communication functions between workloads.

   Example peer_auth.yaml file

   apiVersion: security.istio.io/v1beta1
   kind: PeerAuthentication
   metadata:
     name: default
     namespace: istio-system
   spec:
     mtls:
       mode: STRICT

7. Apply the mTLS policy by running the following command:

   $ oc apply -f peer_auth.yaml

8. Verify that the

   apps-1/sleep

   app can access the

   apps-2/httpbin

   service by running the following command:

   $ oc -n apps-1 exec "$(oc -n apps-1 get pod \
     -l app=sleep -o jsonpath={.items..metadata.name})" \
     -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000

   Example output

   HTTP/1.1 200 OK
   access-control-allow-credentials: true
   access-control-allow-origin: *
   content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com
   content-type: text/html; charset=utf-8
   date: Wed, 18 Jun 2025 09:20:55 GMT
   x-envoy-upstream-service-time: 14
   server: envoy
   transfer-encoding: chunked

9. Verify that the

   apps-2/sleep

   app can access the

   apps-1/httpbin

   service by running the following command:

   $ oc -n apps-2 exec "$(oc -n apps-1 get pod \
     -l app=sleep -o jsonpath={.items..metadata.name})" \
     -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000

   Example output

   HTTP/1.1 200 OK
   access-control-allow-credentials: true
   access-control-allow-origin: *
   content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com
   content-type: text/html; charset=utf-8
   date: Wed, 18 Jun 2025 09:21:23 GMT
   x-envoy-upstream-service-time: 16
   server: envoy
   transfer-encoding: chunked

10. Verify that the

    httpbin

    workload certificate matches as expected by running the following command:

    $ istioctl proxy-config secret -n apps-1 \
      $(oc get pods -n apps-1 -o jsonpath='{.items..metadata.name}' --selector app=httpbin) \
      -o json | jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' \
      | base64 --decode | openssl x509 -text -noout

    Example output

    ...
    Issuer: O = cert-manager + O = cluster.local, CN = istio-ca
    ...
    X509v3 Subject Alternative Name:
    URI:spiffe://cluster.local/ns/apps-1/sa/httpbin

Procedure

1. Remove the

   IstioCSR

   custom resource by running the following command:

   $ oc -n <istio-csr_project_name> delete istiocsrs.operator.openshift.io default

2. Remove the related resources:

   1. List the cluster scoped-resources by running the following command:

      $ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr"

      Save the names of the listed resources for later reference.

   2. List the resources in

      istio-csr

      agent deployed namespace by running the following command:

      $ oc get certificate,deployments,services,serviceaccounts -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n <istio_csr_project_name>

      Save the names of the listed resources for later reference.

   3. List the resources in Red Hat OpenShift Service Mesh or Istio deployed namespaces by running the following command:

      $ oc get roles,rolebindings \
        -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" \
        -n <istio_csr_project_name>

      Save the names of the listed resources for later reference.

   4. For each resource listed in previous steps, delete the resources by running the following command:

      $ oc -n <istio_csr_project_name> delete <resource_type>/<resource_name>

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

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.

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

Verifying traffic flows between clusters

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 version 1 and version 2 of the service can be seen in the responses.

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