Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Gateways and Ingress

Istio Ingress Gateway: Gateway and VirtualService Basics

Expose services outside the cluster with the Istio ingress gateway: how the Gateway and VirtualService resources work together, host matching, ports, and common mistakes.

Sidecars handle traffic between services. To let users from the internet reach a service, you need a front door. In Istio that door is the ingress gateway: a standalone Envoy proxy running as a normal Deployment, usually behind a Kubernetes LoadBalancer Service. It has the same features as a sidecar (routing, retries, TLS, telemetry) but sits at the edge of the mesh.

The product cannot run on this site, so the YAML is read-only. Two Python stand-ins model host matching and route selection so you can experiment with the rules.

Two resources, two jobs

Exposing a service takes two cooperating resources, and keeping their roles straight prevents most confusion:

  • A Gateway describes the listener: which ports, protocols and hostnames the proxy accepts. It says nothing about where traffic goes.
  • A VirtualService describes the routing: given a request for a host and path, which service receives it. It is bound to the gateway through its gateways: field.
flowchart LR
  C["Client"] --> LB["Cloud load balancer"]
  LB --> GW["istio-ingressgateway pods<br/>(Envoy)"]
  GW -->|"Gateway: listens on :80 for shop.example.com"| VS["VirtualService: routes"]
  VS --> P["productpage service"]
  VS --> A["api service"]

The Gateway opens the port; the VirtualService decides the destination.

A working example

YAML
apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: shop-gateway
  namespace: shop
spec:
  selector:
    istio: ingressgateway          # which gateway pods implement this
  servers:
    - port:
        number: 80
        name: http
        protocol: HTTP
      hosts:
        - "shop.example.com"
---
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: shop
  namespace: shop
spec:
  hosts:
    - "shop.example.com"
  gateways:
    - shop-gateway
  http:
    - match:
        - uri:
            prefix: /api
      route:
        - destination:
            host: api
            port:
              number: 8080
    - route:
        - destination:
            host: productpage
            port:
              number: 9080

Rules are evaluated top to bottom and the first match wins, so the most specific match goes first and the catch-all (no match) goes last.

Check the result:

Terminal
kubectl get svc istio-ingressgateway -n istio-system     # find the external address
curl -H "Host: shop.example.com" http://$GATEWAY_ADDRESS/api/health
istioctl analyze -n shop                                  # lints the config

On a local cluster without a cloud load balancer (such as kind or minikube) the Service stays in Pending; use a NodePort, minikube tunnel or a port-forward to reach it.

How the selector works

selector: istio: ingressgateway matches the label on the gateway pods. The default install creates a Deployment with exactly that label in istio-system. If you deploy your own gateway (a good practice for isolation between teams), give it a different label and select that instead. A Gateway whose selector matches no pods silently does nothing, which is a very common first mistake.

You can also install gateways with gateway injection: a plain Deployment with the annotation inject.istio.io/templates: gateway and the label of your choice. The control plane fills in the proxy container. This approach is recommended over the older Operator-defined gateways because teams own and upgrade the gateway like any other workload.

Host matching rules

The hosts fields of the Gateway and VirtualService must overlap:

  • An exact host (shop.example.com) matches only that name.
  • A wildcard (*.example.com) matches any single or multi-level subdomain on the left but not the bare domain.
  • * matches everything.
  • On a Gateway, the host ns/host form restricts which namespaces may bind to it, for example shop/*.example.com or ./* (same namespace only).

If the VirtualService host is not accepted by the Gateway server, the route is never attached and requests get a 404 from Envoy.

Try it: host matching

Python Does this host match the Gateway?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Try it: first match wins

Python Simulate VirtualService route selection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  1. The VirtualService does not list the gateway in gateways:. Without it the rules apply only to in-mesh traffic.
  2. Port names: the service port must be named http, grpc or prefixed (http-web), or declare appProtocol; otherwise Istio treats it as plain TCP and HTTP features vanish.
  3. Different namespaces: a VirtualService in shop can bind a Gateway in istio-system only as istio-system/shop-gateway.
  4. Forgetting the Host header when testing by IP address.
  5. Overlapping hosts in different VirtualServices produce merge behavior that is hard to predict; keep one VirtualService per host where you can.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the job of a Gateway resource?

    The Gateway opens listeners; routing is described by a VirtualService bound to it.
  2. 2. A VirtualService has no gateways field. What happens to requests from the internet?

    Without a gateways list the VirtualService binds to the mesh gateway only.
  3. 3. Does the wildcard host *.example.com match example.com?

    A wildcard needs at least one label before the suffix.
  4. 4. Why should the most specific match rule come first?

    Rules are evaluated in order and the first match decides the route.

Summary

  • The ingress gateway is a standalone Envoy at the edge, selected by labels.
  • A Gateway opens ports and hosts; a VirtualService bound with gateways: routes.
  • Order matters: first match wins; end with a catch-all.
  • Name service ports by protocol so HTTP features work.
  • Use istioctl analyze to catch mismatches.

Next: TLS at the gateway