Getting Started with Istio and Kubernetes Gateway API
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, refer to our which Istio installation method should I use? FAQ page.
These steps require you to have a cluster running a supported version of Kubernetes (1.26, 1.27, 1.28, 1.29). 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 -
Move to the Istio package directory. For example, if the package is
istio-1.21.2
:$ cd istio-1.21.2
The installation directory contains:
- Sample applications in
samples/
- The
istioctl
client binary in thebin/
directory.
- Sample applications in
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.Unlike Istio Gateways, creating Kubernetes Gateways will, by default, also deploy associated gateway proxy services. Therefore, because they won’t be used, we disable the deployment of the default Istio gateway services that are normally installed as part of the
demo
profile.$ istioctl install -f @samples/bookinfo/demo-profile-no-gateways.yaml@ -y ✔ Istio core installed ✔ Istiod 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 be deployed 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-558b8b4b76-2llld 2/2 Running 0 2m41s productpage-v1-6987489c74-lpkgl 2/2 Running 0 2m40s ratings-v1-7dc98c7588-vzftc 2/2 Running 0 2m41s reviews-v1-7f99cc4496-gdxfn 2/2 Running 0 2m41s reviews-v2-7d79d5bd5d-8zzqd 2/2 Running 0 2m41s reviews-v3-7dbcdcbc56-m8dph 2/2 Running 0 2m41s
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 "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" -c ratings -- curl -sS 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 ingress gateway, which maps a path to a route at the edge of your mesh.
Create a Kubernetes Gateway for the Bookinfo application:
$ kubectl apply -f @samples/bookinfo/gateway-api/bookinfo-gateway.yaml@ gateway.gateway.networking.k8s.io/bookinfo-gateway created httproute.gateway.networking.k8s.io/bookinfo created
Because creating a Kubernetes
Gateway
resource will also deploy an associated proxy service, run the following command to wait for the gateway to be ready:$ kubectl wait --for=condition=programmed gtw bookinfo-gateway
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
Set the
INGRESS_HOST
andINGRESS_PORT
variables for accessing the gateway:$ export INGRESS_HOST=$(kubectl get gtw bookinfo-gateway -o jsonpath='{.status.addresses[0].value}') $ export INGRESS_PORT=$(kubectl get gtw bookinfo-gateway -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
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" 169.48.8.37:80
Verify external access
Confirm that the Bookinfo application is accessible from outside the cluster 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 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 Kiali dashboard, along with Prometheus, Grafana, and Jaeger.
Install Kiali and the other addons and wait for them to be deployed.
$ kubectl apply -f samples/addons $ kubectl rollout status deployment/kiali -n istio-system Waiting for deployment "kiali" rollout to finish: 0 of 1 updated replicas are available... deployment "kiali" successfully rolled out
Access the Kiali dashboard.
$ 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.
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
- 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.
$ kubectl delete -f @samples/addons@
$ istioctl uninstall -y --purge
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
The label to instruct Istio to automatically inject Envoy sidecar proxies is not removed by default. If no longer needed, use the following command to remove it:
$ kubectl label namespace default istio-injection-
If you installed the Kubernetes Gateway API CRDs and would now like to remove them, run one of the following commands:
If you ran any tasks that required the experimental version of the CRDs:
$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl delete -f -
Otherwise:
$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl delete -f -