Getting Started

    These steps require you to have a cluster running a compatible version of Kubernetes (1.18, 1.19, 1.20, 1.21). You can use any supported platform, for example or others specified by the platform-specific setup instructions.

    Follow these steps to get started with Istio:

    2. Deploy the sample application
    4. View the dashboard

    1. Go to the page to download the installation file for your OS, or download and extract the latest release automatically (Linux or macOS):

      The command above downloads the latest release (numerically) of Istio. You can pass variables on the command line to download a specific version or to override the processor architecture. For example, to download Istio 1.6.8 for the x86_64 architecture, run:

    2. Move to the Istio package directory. For example, if the package is istio-1.10.0:

      1. $ cd istio-1.10.0

      The installation directory contains:

      • Sample applications in samples/
      • The istioctl client binary in the bin/ directory.

    3. Add the istioctl client to your path (Linux or macOS):

      1. $ export PATH=$PWD/bin:$PATH

    Install Istio

    1. For this installation, we use the demo . It’s selected to have a good set of defaults for testing, but there are other profiles for production or performance testing.

      If your platform has a vendor-specific configuration profile, e.g., Openshift, use it in the following command, instead of the demo profile. Refer to your platform instructions for details.

      1. $ istioctl install --set profile=demo -y
      2. ✔ Istio core installed
      3. ✔ Istiod installed
      4. ✔ Egress gateways installed
      5. ✔ Ingress gateways installed
      6. ✔ Installation complete

    2. Add a namespace label to instruct Istio to automatically inject Envoy sidecar proxies when you deploy your application later:

      1. $ kubectl label namespace default istio-injection=enabled
      2. namespace/default labeled

    1. Deploy the :

      Zip

      1. $ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@
      2. service/details created
      3. serviceaccount/bookinfo-details created
      4. deployment.apps/details-v1 created
      5. service/ratings created
      6. serviceaccount/bookinfo-ratings created
      7. deployment.apps/ratings-v1 created
      8. service/reviews created
      9. serviceaccount/bookinfo-reviews created
      10. deployment.apps/reviews-v2 created
      11. deployment.apps/reviews-v3 created
      12. service/productpage created
      13. serviceaccount/bookinfo-productpage created
      14. deployment.apps/productpage-v1 created

    2. The application will start. As each pod becomes ready, the Istio sidecar will be deployed along with it.

      1. $ kubectl get services
      2. NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
      3. details       ClusterIP   10.0.0.212      <none>        9080/TCP   29s
      5. productpage   ClusterIP   10.0.0.57       <none>        9080/TCP   28s
      6. ratings       ClusterIP   10.0.0.33       <none>        9080/TCP   29s
      7. reviews       ClusterIP   10.0.0.28       <none>        9080/TCP   29s

      and

      1. $ kubectl get pods
      2. NAME                              READY   STATUS    RESTARTS   AGE
      3. details-v1-558b8b4b76-2llld       2/2     Running   0          2m41s
      4. productpage-v1-6987489c74-lpkgl   2/2     Running   0          2m40s
      5. ratings-v1-7dc98c7588-vzftc       2/2     Running   0          2m41s
      6. reviews-v1-7f99cc4496-gdxfn       2/2     Running   0          2m41s
      7. reviews-v2-7d79d5bd5d-8zzqd       2/2     Running   0          2m41s
      8. reviews-v3-7dbcdcbc56-m8dph       2/2     Running   0          2m41s

      Re-run the previous command and wait until all pods report READY 2/2 and STATUS Running before you go to the next step. This might take a few minutes depending on your platform.

    3. Verify everything is working correctly up to this point. Run this command to see if the app is running inside the cluster and serving HTML pages by checking for the page title in the response:

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

    Open the application to outside traffic

    The Bookinfo application is deployed but not accessible from the outside. To make it accessible, you need to create an , which maps a path to a route at the edge of your mesh.

    1. Associate this application with the Istio gateway:

      Zip

      1. $ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@
      2. gateway.networking.istio.io/bookinfo-gateway created
      3. virtualservice.networking.istio.io/bookinfo created

    2. Ensure that there are no issues with the configuration:

      1. $ istioctl analyze
      2. ✔ No validation issues found when analyzing namespace: default.

    Set the ingress ports:

    Ensure a port was successfully assigned to each environment variable:

    1. $ echo "$INGRESS_PORT"
    2. 32194
    1. $ echo "$SECURE_INGRESS_PORT"
    2. 31632

    Set the ingress IP:

    1. $ export INGRESS_HOST=$(minikube ip)

    Ensure an IP address was successfully assigned to the environment variable:

    1. $ echo "$INGRESS_HOST"
    2. 192.168.4.102

    Run this command in a new terminal window to start a Minikube tunnel that sends traffic to your Istio Ingress Gateway:

    1. $ minikube tunnel

    Execute the following command to determine if your Kubernetes cluster is running in an environment that supports external load balancers:

    1. $ kubectl get svc istio-ingressgateway -n istio-system
    2. NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                                      AGE
    3. istio-ingressgateway   LoadBalancer   172.21.109.129   130.211.10.121  80:31380/TCP,443:31390/TCP,31400:31400/TCP   17h

    If the EXTERNAL-IP value is set, your environment has an external load balancer that you can use for the ingress gateway. If the EXTERNAL-IP value is <none> (or perpetually ), your environment does not provide an external load balancer for the ingress gateway. In this case, you can access the gateway using the service’s .

    Choose the instructions corresponding to your environment:

    Follow these instructions if you have determined that your environment has an external load balancer.

    Set the ingress IP and ports:

    1. $ export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')
    2. $ export SECURE_INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}')

    In certain environments, the load balancer may be exposed using a host name, instead of an IP address. In this case, the ingress gateway’s EXTERNAL-IP value will not be an IP address, but rather a host name, and the above command will have failed to set the INGRESS_HOST environment variable. Use the following command to correct the INGRESS_HOST value:

    1. $ export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

    Follow these instructions if your environment does not have an external load balancer and choose a node port instead.

    Set the ingress ports:

    1. $ export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].nodePort}')
    2. $ export SECURE_INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].nodePort}')

    GKE:

    1. $ export INGRESS_HOST=workerNodeAddress

    You need to create firewall rules to allow the TCP traffic to the ingressgateway service’s ports. Run the following commands to allow the traffic for the HTTP port, the secure port (HTTPS) or both:

    1. $ gcloud compute firewall-rules create allow-gateway-http --allow "tcp:$INGRESS_PORT"
    2. $ gcloud compute firewall-rules create allow-gateway-https --allow "tcp:$SECURE_INGRESS_PORT"

    IBM Cloud Kubernetes Service:

    Docker For Desktop:

    1. $ export INGRESS_HOST=127.0.0.1

    Other environments:

    1. $ export INGRESS_HOST=$(kubectl get po -l istio=ingressgateway -n istio-system -o jsonpath='{.items[0].status.hostIP}')

    1. Set GATEWAY_URL:

      1. $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

    2. Ensure an IP address and port were successfully assigned to the environment variable:

      1. $ echo "$GATEWAY_URL"
      2. 192.168.99.100:32194

    Verify external access

    1. Run the following command to retrieve the external address of the Bookinfo application.

      1. $ echo "http://$GATEWAY_URL/productpage"

    2. Paste the output from the previous command into your web browser and confirm that the Bookinfo product page is displayed.

    Istio integrates with several different telemetry applications. These can help you gain an understanding of the structure of your service mesh, display the topology of the mesh, and analyze the health of your mesh.

    Use the following instructions to deploy the dashboard, along with Prometheus, , and Jaeger.

    1. Install and wait for them to be deployed.

      1. $ kubectl apply -f samples/addons
      2. $ kubectl rollout status deployment/kiali -n istio-system
      3. Waiting for deployment "kiali" rollout to finish: 0 of 1 updated replicas are available...
      4. deployment "kiali" successfully rolled out

      If there are errors trying to install the addons, try running the command again. There may be some timing issues which will be resolved when the command is run again.

    2. Access the Kiali dashboard.

      1. $ istioctl dashboard kiali

    3. In the left navigation menu, select Graph and in the Namespace drop down, select default.

      To see trace data, you must send requests to your service. The number of requests depends on Istio’s sampling rate. You set this rate when you install Istio. The default sampling rate is 1%. You need to send at least 100 requests before the first trace is visible. To send a 100 requests to the productpage service, use the following command:

      1. $ for i in $(seq 1 100); do curl -s -o /dev/null "http://$GATEWAY_URL/productpage"; done

      The Kiali dashboard shows an overview of your mesh with the relationships between the services in the Bookinfo sample application. It also provides filters to visualize the traffic flow.

      Kiali Dashboard

    Next steps

    Congratulations on completing the evaluation installation!

    These tasks are a great place for beginners to further evaluate Istio’s features using this demo installation:

    Before you customize Istio for production use, see these resources:

    We welcome you to ask questions and give us feedback by joining the Istio community.

    Uninstall

    To delete the Bookinfo sample application and its configuration, see .

    The Istio uninstall deletes the RBAC permissions and all resources hierarchically under the istio-system namespace. It is safe to ignore errors for non-existent resources because they may have been deleted hierarchically.

    Zip

    1. $ kubectl delete -f @samples/addons@
    2. $ istioctl manifest generate --set profile=demo | kubectl delete --ignore-not-found=true -f -

    The istio-system namespace is not removed by default. If no longer needed, use the following command to remove it:

    1. $ kubectl delete namespace istio-system