Getting Started

 7 minute read

This guide lets you quickly evaluate Istio. If you are already familiar with Istio or interested in installing other configuration profiles or advanced deployment models, see Customizable Install with istioctl instead.

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

Follow these steps to get started with Istio:

  1. Download and install Istio
  2. Deploy the sample application
  3. Open the application to outside traffic
  4. View the dashboard

Download Istio

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

    $ curl -L https://istio.io/downloadIstio | sh -

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

    $ cd istio-1.5.4

    The installation directory contains:

    • Installation YAML files for Kubernetes in install/kubernetes
    • Sample applications in samples/
    • The istioctl client binary in the bin/ directory.

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

    $ export PATH=$PWD/bin:$PATH

Install Istio

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

    $ istioctl manifest apply --set profile=demo
Detected that your cluster does not support third party JWT authentication. Falling back to less secure first party JWT
- Applying manifest for component Base...
✔ Finished applying manifest for component Base.
- Applying manifest for component Pilot...
✔ Finished applying manifest for component Pilot.
Waiting for resources to become ready...
- Applying manifest for component EgressGateways...
- Applying manifest for component IngressGateways...
- Applying manifest for component AddonComponents...
✔ Finished applying manifest for component EgressGateways.
✔ Finished applying manifest for component IngressGateways.
✔ Finished applying manifest for component AddonComponents.

✔ Installation complete

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

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

Deploy the sample application

  1. Deploy the Bookinfo sample application:

    Zip
    $ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@
service/details created
serviceaccount/bookinfo-details created
deployment.apps/details-v1 created
service/ratings created
serviceaccount/bookinfo-ratings created
deployment.apps/ratings-v1 created
service/reviews created
serviceaccount/bookinfo-reviews created
deployment.apps/reviews-v1 created
deployment.apps/reviews-v2 created
deployment.apps/reviews-v3 created
service/productpage created
serviceaccount/bookinfo-productpage created
deployment.apps/productpage-v1 created

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

    $ kubectl get services
NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
details       ClusterIP   10.0.0.212      <none>        9080/TCP   29s
kubernetes    ClusterIP   10.0.0.1        <none>        443/TCP    25m
productpage   ClusterIP   10.0.0.57       <none>        9080/TCP   28s
ratings       ClusterIP   10.0.0.33       <none>        9080/TCP   29s
reviews       ClusterIP   10.0.0.28       <none>        9080/TCP   29s

    and

    $ kubectl get pods
NAME                              READY   STATUS            RESTARTS   AGE
details-v1-78d78fbddf-tj56d       0/2     PodInitializing   0          2m30s
productpage-v1-85b9bf9cd7-zg7tr   0/2     PodInitializing   0          2m29s
ratings-v1-6c9dbf6b45-5djtx       0/2     PodInitializing   0          2m29s
reviews-v1-564b97f875-dzdt5       0/2     PodInitializing   0          2m30s
reviews-v2-568c7c9d8f-p5wrj       1/2     Running           0          2m29s
reviews-v3-67b4988599-7nhwz       0/2     PodInitializing   0          2m29s

  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:

    $ kubectl exec -it $(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}') -c ratings -- curl productpage:9080/productpage | grep -o "<title>.*</title>"
<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 Istio Ingress Gateway, which maps a path to a route at the edge of your mesh.

  1. Associate this application with the Istio gateway:

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

  2. Confirm the gateway has been created:

    $ kubectl get gateway
NAME               AGE
bookinfo-gateway   32s

Determining the ingress IP and ports

Follow these instructions to set the INGRESS_HOST and INGRESS_PORT variables for accessing the gateway. Use the tabs to choose the instructions for your chosen platform:

Set the ingress ports:

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

Ensure a port was successfully assigned to each environment variable:

$ echo $INGRESS_PORT
32194

$ echo $SECURE_INGRESS_PORT
31632

Set the ingress IP:

$ export INGRESS_HOST=$(minikube ip)

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

$ echo $INGRESS_HOST
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:

$ minikube tunnel

  1. Set GATEWAY_URL:

    $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

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

    $ echo $GATEWAY_URL
192.168.99.100:32194

Verify external access

Confirm that the Bookinfo application is accessible from outside. Copy the output of this command and paste into your browser:

$ echo http://$GATEWAY_URL/productpage

View the dashboard

Istio has several optional dashboards installed by the demo installation. The Kiali dashboard helps you understand the structure of your service mesh by displaying the topology and indicates the health of your mesh.

  1. Access the Kiali dashboard. The default user name is admin and default password is admin.

    $ istioctl dashboard kiali

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

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

Join the Istio community

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

Uninstall

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

$ istioctl manifest generate --set profile=demo | kubectl delete -f -

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

Was this information useful?
Do you have any suggestions for improvement?

Thanks for your feedback!