On this page

Add apps to the service mesh

Add services in existing namepaces to your service mesh, or deploy the Bookinfo sample app to try out traffic routing in your service mesh.

Add services to the mesh

Now that Istio is up and running, you can create service namespaces for your teams to run app workloads in. For any namespaces that you want to deploy apps to, be sure to follow these steps to include your services in the service mesh.

Save the revision that you used for your istiod installation in an environment variable. Typically, this is main for a Helm installation, or gloo for a Gloo operator installation.
- Gloo operator:
```
export REVISION=gloo
```
- Helm:
```
export REVISION=main
```
Label the service namespace for Istio sidecar injection with the revision label.
```
kubectl label namespace <namespace> istio.io/rev=${REVISION} --overwrite
```
If you already deployed app pods to the namespace, restart the workloads so that sidecars are injected into the pods. For example, you might roll out a restart to each deployment by using a command similar to the following.
```
kubectl rollout restart deployment -n <namespace> <deployment>
```

Make services available across clusters

If you linked clusters to form a multicluster ambient or sidecar mesh, you can make a service available across clusters throughout the multicluster mesh by using the solo.io/service-scope=global service label. When you apply this label to a service, it does not change the service. Instead, a new global service is created with a hostname in the format <name>.<namespace>.mesh.internal.

You can then use this internal hostname for in-mesh routing. For example, you might create a Gateway resource in cluster1 to manage incoming traffic requests for your app in cluster2. To make the app accessible across clusters, you label its service with solo.io/service-scope=global, which generates a global service hostname. To route requests to the app, you create an HTTPRoute resource that references this global service hostname. The ingress gateway can then use this global service hostname in the HTTPRoute to route incoming traffic requests through the east-west gateway across clusters to your app.

For the service that you want to be accessible from multiple clusters, apply the solo.io/service-scope=global label.
```
kubectl label service <name> -n <namespace> --context ${CLUSTER_CONTEXT} solo.io/service-scope=global
```

Verify that the global service entry with a hostname in the format <svc_name>.<namespace>.mesh.internal is created in the istio-system namespace. This hostname makes the endpoint for your service available across the multicluster mesh.

kubectl get serviceentry -n istio-system --context ${CLUSTER_CONTEXT}

Example output:

NAME                             HOSTS                                    LOCATION     RESOLUTION   AGE
autogen.<namespace>.<svc_name>   ["<svc_name>.<namespace>.mesh.internal"]              STATIC       94s

If you have a service of the same name and namespace in another cluster of the mesh, label that service too. This way, the service’s endpoint is added to the global service’s hostname, and increases the availability of your service in the multicluster mesh. For more information, see Namespace sameness.
```
kubectl label service <name> -n <namespace> --context <other_context> solo.io/service-scope=global
```
Optional: Modify the way that traffic is routed to service endpoints for the global service by applying the networking.istio.io/traffic-distribution annotation to each service instance. For more information, see Endpoint traffic control.
```
kubectl annotate service <name> -n <namespace> networking.istio.io/traffic-distribution=<mode>
```

For an example of deploying an app to a multicluster mesh, see Bookinfo example: Multicluster.

Namespace sameness

You might have the same app service in the same namespace in multiple clusters. When you label the service in one cluster, a global service is created in the mesh for that service’s endpoint. However, you must also label the service in the other cluster to include its endpoint in the global service’s hostname. When you label each service, then all instances of that app in the multicluster mesh are exposed by the global service. By adhering to the principle of namespace sameness, the global service’s hostname unifies the endpoints for each service across the clusters.

For example, you might have a myapp service in the stage namespace of cluster1, and a myapp service in the stage namespace of cluster2. If you label the service in cluster1 with solo.io/service-scope=global, a global service is created with the hostname myapp.stage.mesh.internal. However, until you label the service in cluster2, the service is not automatically included in the global service’s endpoints.

Endpoint traffic control

If an in-mesh service makes a request to a service that is exposed globally, and a healthy endpoint for that service is available locally in the same cluster network, the request is routed to that local instance by default. If no healthy endpoints of that service are available locally, requests are routed to healthy endpoints in remote cluster networks. An endpoint is considered healthy if the app pod exposed by that local service is in a ready state.

To modify this default behavior for global services, you can apply the networking.istio.io/traffic-distribution annotation to a service that has the solo.io/service-scope=global label.

PreferNetwork: Route requests to available endpoints within the source’s same network first. This is the default for global services.
PreferClose: Route requests to an available endpoint that is closest to the source first, considering the zone, region, and network. For example, you might have a global service with two endpoints in zone us-west and one endpoint in us-east. When sending traffic from a client in us-west, all traffic routes to the two us-west endpoints. If one of those endpoints becomes unhealthy, all traffic routes to the remaining endpoint in us-west. If that endpoint becomes unhealthy, traffic routes to the us-east endpoint.
PreferRegion: Route requests to an available endpoint that is closest to the source first, considering the region and network.
Any: Consider all endpoints equally, and route requests to a random available endpoint.

notifications

Recall that the directionality that you choose when you link the clusters can also affect how services can communicate. For example, if you choose to asymmetrically link your clusters, services in one cluster might not be able to send requests to remote endpoints for services in another cluster.

Subset routing

Traditional subset routing in Istio, such by configuring routing rules to different app subsets in a DestinationRule, is currently not supported for cross-cluster routing when using multicluster peering. Instead, the recommended approach involves using services to represent specific subsets, and using an HTTPRoute resource to manage cross-cluster routing to each “subset” service.

For example, say that you have three clusters that you linked together to create a multicluster mesh.

You deploy the Bookinfo app across the clusters by creating the ratings and productpage microservices in cluster0, reviews-v1 in cluster1, and reviews-v2 in cluster2.
You then abstract the reviews subsets into individual services, such as one service called reviews-v1 and one service called reviews-v2, instead of using just one reviews service for both.
To ensure that each service is accessible across the multicluster mesh, you label them with solo.io/service-scope=global, so that they now have internal global hostnames such as reviews-v1.bookinfo.internal.mesh and reviews-v2.bookinfo.internal.mesh.

To manage routing rules for each service, you create an HTTPRoute similar to the following example. This HTTPRoute routes requests to each global service hostname. You can then implement routing rules to each “subset” service, such as by using header matching to send requests from a user called “blackstar” to only reviews-v2.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: reviews
    port: 9080
  rules:
  - matches:
    - headers:
      - name: end-user
        value: jason
    backendRefs:
    - name: reviews-v1.bookinfo.internal.mesh
      port: 9080
  - backendRefs:
    - name: reviews-v2.bookinfo.internal.mesh
      port: 9080
    matches:
    - headers:
      - name: end-user
        value: blackstar

Bookinfo example: Single cluster

Save the revision that you used for your istiod installation in an environment variable. Typically, this is main for a Helm installation, or gloo for a Gloo operator installation.
- Gloo operator:
```
export REVISION=gloo
```
- Helm:
```
export REVISION=main
```
Create the bookinfo namespace and label it so that the services become part of the service mesh.
```
kubectl create ns bookinfo
kubectl label ns bookinfo istio.io/rev=${REVISION} --overwrite
```

Deploy the Bookinfo app.

# deploy bookinfo application components for all versions less than v3
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app,version notin (v3)'
# deploy an updated product page with extra container utilities such as 'curl' and 'netcat'
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/productpage-with-curl.yaml
# deploy all bookinfo service accounts
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account'

Verify that the Bookinfo app deployed successfully.
```
kubectl get pods,svc -n bookinfo
```

Bookinfo example: Multicluster

For testing purposes, you can deploy the Bookinfo sample app across multiple clusters, add the app services to your sidecar mesh, and make the services available across clusters in the mesh.

Deploy Bookinfo

Save the kubeconfig contexts for two clusters that you deployed an a sidecar mesh to and linked together.
```
export REMOTE_CONTEXT1=<cluster1-context>
export REMOTE_CONTEXT2=<cluster2-context>
```
Save the revision that you used for your istiod installation in an environment variable. Typically, this is main for a Helm installation, or gloo for a Gloo operator installation.
- Gloo operator:
```
export REVISION=gloo
```
- Helm:
```
export REVISION=main
```
Create the bookinfo namespace in each cluster, and label them with the istio.io/rev=$REVISION label. This label adds all Bookinfo services that you create in each namespace to the sidecar mesh in the respective cluster.
```
for context in ${REMOTE_CONTEXT1} ${REMOTE_CONTEXT2}; do
  kubectl --context ${context} create ns bookinfo
  kubectl --context ${context} label namespace bookinfo istio.io/rev=${REVISION} --overwrite
done
```

Deploy Bookinfo with the details, productpage, ratings, reviews-v1, and reviews-v2 services in the first cluster.

# deploy bookinfo application components for all versions less than v3
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app,version notin (v3)' --context ${REMOTE_CONTEXT1}
# deploy an updated product page with extra container utilities such as 'curl' and 'netcat'
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/productpage-with-curl.yaml --context ${REMOTE_CONTEXT1}
# deploy all bookinfo service accounts
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account' --context ${REMOTE_CONTEXT1}

Deploy Bookinfo with the ratings and reviews-v3 services in the second cluster.

# deploy reviews and ratings services
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'service in (reviews)' --context ${REMOTE_CONTEXT2}
# deploy reviews-v3
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app in (reviews),version in (v3)' --context ${REMOTE_CONTEXT2}
# deploy ratings
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app in (ratings)' --context ${REMOTE_CONTEXT2}
# deploy reviews and ratings service accounts
kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.24.2/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account in (reviews, ratings)' --context ${REMOTE_CONTEXT2}

Verify that the Bookinfo app is deployed successfully.

kubectl --context ${REMOTE_CONTEXT1} get pods,svc -n bookinfo
kubectl --context ${REMOTE_CONTEXT2} get pods,svc -n bookinfo

Expose services across clusters

To make Bookinfo globally available in the multicluster setup, you label each productpage service so that both productpage endpoints are available behind one global service hostname.

Label the productpage service in each cluster to create one productpage global service.

kubectl --context ${REMOTE_CONTEXT1} label service productpage -n bookinfo solo.io/service-scope=global
kubectl --context ${REMOTE_CONTEXT2} label service productpage -n bookinfo solo.io/service-scope=global

Apply the networking.istio.io/traffic-distribution=Any annotation to the services. This annotation allows requests to the productpage global service to be routed to each service endpoint equally.

kubectl --context ${REMOTE_CONTEXT1} annotate service productpage -n bookinfo networking.istio.io/traffic-distribution=Any
kubectl --context ${REMOTE_CONTEXT2} annotate service productpage -n bookinfo networking.istio.io/traffic-distribution=Any

Verify that the global service entry with the productpage.bookinfo.mesh.internal hostname is created in the istio-system namespace.

kubectl get serviceentry -n istio-system --context ${REMOTE_CONTEXT1} | grep bookinfo
kubectl get serviceentry -n istio-system --context ${REMOTE_CONTEXT2} | grep bookinfo

Example output:

autogen.bookinfo.productpage   ["productpage.bookinfo.mesh.internal"]              STATIC       94s

Use the ratings app to send a request to the productpage.bookinfo.mesh.internal global hostname. Verify that you get back a 200 HTTP response code.

kubectl -n bookinfo --context $REMOTE_CONTEXT1 debug -i pods/$(kubectl get pod -l app=ratings \
--context $REMOTE_CONTEXT1 -A -o jsonpath='{.items[0].metadata.name}') \
--image=curlimages/curl -- curl -vik http://productpage.bookinfo.mesh.internal:9080/productpage

Example output:

* Request completely sent off
HTTP/1.0 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 4183
Server: Werkzeug/0.14.1 Python/3.6.8
Date: Fri, 14 Feb 2025 21:05:09 GMT<!DOCTYPE html>
<html>
<head>
<title>Simple Bookstore App</title>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
…

The productpage services for each Bookinfo instance are now unified behind one hostname, which increases the availability of the Bookinfo app. You can now use this global service hostname in routing configurations. For example, to expose the productpage global service hostname with an ingress gateway, continue with the Bookinfo example in the ingress gateway guide.

Scale down the productpage app in $REMOTE_CLUSTER1.

kubectl scale deployment productpage-v1 -n bookinfo --context $REMOTE_CONTEXT1 --replicas=0

Repeat the request from the ratings app to the productpage app. Because the productpage app in $REMOTE_CLUSTER1 is unavailable, all traffic is automatically routed to the productpage app in $REMOTE_CLUSTER2 through the east-west gateway. Verify that you get back a 200 HTTP response code.

kubectl -n bookinfo --context $REMOTE_CONTEXT1 debug -i pods/$(kubectl get pod -l app=ratings \
--context $REMOTE_CONTEXT1 -A -o jsonpath='{.items[0].metadata.name}') \
--image=curlimages/curl -- curl -vik http://productpage.bookinfo.mesh.internal:9080/productpage

Example output:

* Request completely sent off
HTTP/1.0 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 4183
Server: Werkzeug/0.14.1 Python/3.6.8
Date: Fri, 14 Feb 2025 21:05:09 GMT<!DOCTYPE html>
<html>
<head>
<title>Simple Bookstore App</title>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
…

If you also installed Gloo Mesh, open the Gloo UI. If you do not have Gloo Mesh installed, you can follow the Get started guide.
```
meshctl dashboard --kubecontext $MGMT_CONTEXT
```
Navigate to Observability > Graph and verify that you see the traffic flow for your multicluster setup. Note that you might need to select both clusters and the bookinfo and istio-eastwest namespaces.

Scale the productpage deployment back up in $REMOTE_CLUSTER1.

kubectl scale deployment productpage-v1 -n bookinfo --context $REMOTE_CONTEXT1 --replicas=1

Expose apps in your mesh with an ingress gateway.
Launch the Gloo UI to review the Istio insights that were captured for your service mesh setup. Gloo Mesh comes with an insights engine that automatically analyzes your Istio setups for health issues. These issues are displayed in the UI along with recommendations to harden your Istio setups. The insights give you a checklist to address issues that might otherwise be hard to detect across your environment. For more information, see Insights.
When it’s time to upgrade your service mesh, you can perform a safe in-place upgrade by using the Gloo operator or Helm.

Add apps to the service mesh

Add services to the mesh link

Make services available across clusters link

Namespace sameness link

Endpoint traffic control link

Subset routing link

Bookinfo example: Single cluster link

Bookinfo example: Multicluster link

Deploy Bookinfo link

Expose services across clusters link

Next link

Add services to the mesh

Make services available across clusters

Namespace sameness

Endpoint traffic control

Subset routing

Bookinfo example: Single cluster

Bookinfo example: Multicluster

Deploy Bookinfo

Expose services across clusters

Next