Getting Started
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:
- Download and install Istio
- Deploy the sample application
- Open the application to outside traffic
- View the dashboard
Download Istio
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 -
The command above downloads the latest release (numerically) of Istio. To download a specific version, you can add a variable on the command line. For example to download Istio 1.4.3, you would run
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.4.3 sh -
Move to the Istio package directory. For example, if the package is
istio-1.6.0
:$ cd istio-1.6.0
The installation directory contains:
- Sample applications in
samples/
- The
istioctl
client binary in thebin/
directory.
Add the
istioctl
client to your path (Linux or macOS):$ export PATH=$PWD/bin:$PATH
Install Istio
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
✔ Component Base installed
✔ Component Pilot installed
✔ Component EgressGateways installed
✔ Component IngressGateways installed
✔ Component AddonComponents installed
✔ Installation complete
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
Deploy the
Bookinfo
sample application:$ 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
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
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.
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.
Associate this application with the Istio gateway:
$ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@
gateway.networking.istio.io/bookinfo-gateway created
virtualservice.networking.istio.io/bookinfo created
Ensure that there are no issues with the configuration:
$ istioctl analyze
✔ No validation issues found when analyzing namespace: default.
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
Execute the following command to determine if your Kubernetes cluster is running in an environment that supports external load balancers:
$ kubectl get svc istio-ingressgateway -n istio-system
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
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 <pending>
), 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 node port.
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:
$ export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
$ export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')
$ 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:
$ 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:
$ 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}')
GKE:
$ 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:
$ gcloud compute firewall-rules create allow-gateway-http --allow tcp:$INGRESS_PORT
$ gcloud compute firewall-rules create allow-gateway-https --allow tcp:$SECURE_INGRESS_PORT
Docker For Desktop:
$ export INGRESS_HOST=127.0.0.1
Other environments (e.g., IBM Cloud Private, etc.):
$ export INGRESS_HOST=$(kubectl get po -l istio=ingressgateway -n istio-system -o jsonpath='{.items[0].status.hostIP}')
Set
GATEWAY_URL
:$ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
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 by viewing the Bookinfo product page using a browser.
Run the following command to retrieve the external address of the Bookinfo application.
$ echo http://$GATEWAY_URL/productpage
Paste the output from the previous command into your web browser and confirm that the Bookinfo product page is displayed.
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.
Access the Kiali dashboard. The default user name is
admin
and default password isadmin
.$ istioctl dashboard kiali
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
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:
- Request routing
- Fault injection
- Traffic shifting
- Querying metrics
- Visualizing metrics
- Rate limiting
- Accessing external services
- Visualizing your mesh
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
To delete the Bookinfo
sample application and its configuration, see Bookinfo
cleanup.
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.
$ istioctl manifest generate --set profile=demo | kubectl delete -f -
The istio-system
namespace is not removed by default. If no longer needed, use the following command to remove it:
$ kubectl delete namespace istio-system
See also
Safely Upgrade Istio using a Canary Control Plane Deployment
Simplifying Istio upgrades by offering safe canary deployments of the control plane.
Provision and manage DNS certificates in Istio.
Introducing the Istio Operator
Introduction to Istio’s new operator-based installation and control plane management feature.
A more secure way to manage Istio webhooks.
Demystifying Istio’s Sidecar Injection Model
De-mystify how Istio manages to plugin its data-plane components into an existing deployment.
Customizable Install with Istioctl
Install and customize any Istio configuration profile for in-depth evaluation or production use.