Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท Gateways and Ingress

TLS at the Istio Gateway: SIMPLE, MUTUAL and PASSTHROUGH

Secure the Istio ingress gateway with HTTPS: TLS modes, credentialName secrets, redirecting HTTP to HTTPS, mutual TLS for clients, SNI routing and certificate rotation with cert-manager.

Traffic inside the mesh is encrypted by sidecars with mutual TLS. Traffic from the internet is a different matter: browsers expect a certificate from a public authority for your domain, and the gateway is where that certificate lives. Configuring TLS on the gateway means choosing a mode, giving the proxy a certificate and key, and optionally redirecting plain HTTP.

The product cannot run here, so the configuration is read-only. The Python stand-ins check certificate names and help you pick the right mode.

The three TLS modes

On a Gateway server entry, tls.mode decides what the gateway does with the connection.

Mode The gateway... Use when
SIMPLE terminates TLS using its certificate; clients are anonymous Normal HTTPS website or API
MUTUAL terminates TLS and also requires a client certificate signed by your CA Partner APIs, B2B, internal admin endpoints
PASSTHROUGH does not decrypt; routes by the SNI name and forwards the encrypted bytes The backend must terminate TLS itself, or you cannot hold the key

There are also ISTIO_MUTUAL (the gateway speaks Istio's own mTLS, used for east-west gateways) and AUTO_PASSTHROUGH (SNI-based forwarding used in multicluster setups). For internet traffic you will use the first three.

HTTPS with a Kubernetes secret

Create a TLS secret in the same namespace as the gateway pods (usually istio-system) and reference it with credentialName. The gateway reads it through its secret discovery service, so rotating the secret needs no restart.

Terminal
kubectl create -n istio-system secret tls shop-cert \
  --cert=shop.example.com.crt --key=shop.example.com.key
YAML
apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: shop-gateway
  namespace: shop
spec:
  selector:
    istio: ingressgateway
  servers:
    - port: { number: 443, name: https, protocol: HTTPS }
      hosts: ["shop.example.com"]
      tls:
        mode: SIMPLE
        credentialName: shop-cert
        minProtocolVersion: TLSV1_2
    - port: { number: 80, name: http, protocol: HTTP }
      hosts: ["shop.example.com"]
      tls:
        httpsRedirect: true          # answer 301 and send clients to HTTPS

The VirtualService stays unchanged, bound to the same gateway; it routes decrypted HTTP. Test with curl and its --resolve flag so the SNI and Host header match:

Terminal
curl -v --resolve shop.example.com:443:$GATEWAY_IP https://shop.example.com/

Mutual TLS from clients

With mode: MUTUAL the secret also contains the CA certificate used to verify clients: it needs keys tls.crt, tls.key and ca.crt (or a separate credentialName-cacert secret). A client that presents no certificate, or one signed by another CA, fails the handshake before any HTTP request is seen. You can additionally authorize specific clients with an AuthorizationPolicy on the gateway using the certificate's identity.

Passthrough and SNI routing

With PASSTHROUGH the gateway cannot read HTTP, so the VirtualService uses a tls route that matches on sniHosts:

YAML
spec:
  hosts: ["secure.example.com"]
  gateways: ["passthrough-gateway"]
  tls:
    - match:
        - port: 443
          sniHosts: ["secure.example.com"]
      route:
        - destination: { host: legacy-https, port: { number: 8443 } }

You lose L7 features here: no path routing, retries on HTTP codes, or header manipulation, because the proxy sees only encrypted bytes.

Certificates in practice

Writing secrets by hand does not scale. The usual pattern is cert-manager: you create a Certificate object in istio-system that asks Let's Encrypt (or an internal CA) for a certificate, and cert-manager keeps the resulting secret renewed. Because the gateway watches the secret, renewed certificates are picked up live. Monitor expiry anyway; an expired certificate is one of the most embarrassing outages.

The secret must live where the gateway pods run, not where the Gateway resource lives. A credentialName that points to a missing secret makes the listener fail, and clients see a TLS handshake error instead of a helpful message.

Try it: does a certificate cover the hostname?

Python Check certificate names against a host

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.

A wildcard certificate covers exactly one label, which is why a.b.api.example.com fails.

Try it: choose the TLS mode

Python TLS mode advisor

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.

The last case shows the real-world answer: if you need HTTP features, terminate at the gateway (SIMPLE) and re-encrypt to the backend with a DestinationRule.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which TLS mode makes the gateway verify client certificates?

    MUTUAL terminates TLS and requires a client certificate signed by the configured CA.
  2. 2. In which namespace must the credentialName secret exist?

    The gateway reads the secret through its own namespace, normally istio-system.
  3. 3. What does httpsRedirect: true do on a port 80 server?

    The gateway answers with a 301 redirect to the HTTPS URL.
  4. 4. What is lost when using PASSTHROUGH?

    The gateway sees only encrypted bytes, so it cannot read paths or headers.

Summary

  • SIMPLE terminates TLS, MUTUAL also verifies clients, PASSTHROUGH forwards encrypted bytes by SNI.
  • Put the certificate in a secret in the gateway's namespace and reference it with credentialName.
  • Redirect HTTP with httpsRedirect: true; set minProtocolVersion.
  • Automate issuance and renewal with cert-manager and monitor expiry.

Next: Controlling egress traffic