Getting Started with Istio and Kubernetes Gateway API

Istio includes beta support for the Kubernetes Gateway API and intends to make it the default API for traffic management in the future. The following instructions allow you to get started with Istio using the Gateway API. If you prefer to use the tried-and-proven Istio APIs for traffic management, you should use these instructions instead.

The Kubernetes Gateway API CRDs do not come installed by default on most Kubernetes clusters, so make sure they are installed before using the Gateway API:

  1. $ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  2.   { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0" | kubectl apply -f -; }

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.27, 1.28, 1.29, 1.30). 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):

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

    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.22.0 for the x86_64 architecture, run:

    1. $ curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.0 TARGET_ARCH=x86_64 sh -

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

    1. $ cd istio-1.22.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 configuration profile. 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.

    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.

    Zip

    1. $ istioctl install -f @samples/bookinfo/demo-profile-no-gateways.yaml@ -y
    2. ✔ Istio core installed
    3. ✔ Istiod installed
    4. ✔ 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

Deploy the sample application

  1. Deploy the Bookinfo sample application:

    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-v1 created
    11. deployment.apps/reviews-v2 created
    12. deployment.apps/reviews-v3 created
    13. service/productpage created
    14. serviceaccount/bookinfo-productpage created
    15. 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
    4. kubernetes    ClusterIP   10.0.0.1        <none>        443/TCP    25m
    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 ingress gateway, which maps a path to a route at the edge of your mesh.

  1. Create a Kubernetes Gateway for the Bookinfo application:

    Zip

    1. $ kubectl apply -f @samples/bookinfo/gateway-api/bookinfo-gateway.yaml@
    2. gateway.gateway.networking.k8s.io/bookinfo-gateway created
    3. 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:

    1. $ kubectl wait --for=condition=programmed gtw bookinfo-gateway

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

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

Determining the ingress IP and ports

  1. Set the INGRESS_HOST and INGRESS_PORT variables for accessing the gateway:

    These instructions assume that your Kubernetes cluster supports external load balancers (i.e., Services of type LoadBalancer). Refer to ingress control for details.

    1. $ export INGRESS_HOST=$(kubectl get gtw bookinfo-gateway -o jsonpath='{.status.addresses[0].value}')
    2. $ export INGRESS_PORT=$(kubectl get gtw bookinfo-gateway -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')

  2. Set GATEWAY_URL:

    1. $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

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

    1. $ echo "$GATEWAY_URL"
    2. 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.

  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.

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.

  1. Install Kiali and the other addons 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 and can be configured using the Telemetry API. With the default sampling rate of 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

    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

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.

Zip

  1. $ kubectl delete -f @samples/addons@
  2. $ istioctl uninstall -y --purge

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

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:

  1. $ 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:

    1. $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.1.0" | kubectl delete -f -

  • Otherwise:

    1. $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0" | kubectl delete -f -