Skip to main content
logoTetrate Istio SubscriptionVersion: Next

Deploy Envoy Gateway as Ingress Gateway and Waypoint Proxy in Ambient Mesh

This document describes how to deploy Envoy Gateway as both an Ingress Gateway and a Waypoint Proxy in an Ambient Mesh. By following these steps, you can leverage Envoy Gateway's capabilities for managing ingress traffic and providing Layer 7 routing and policy enforcement within the ambient mesh architecture.

Note: Envoy Gateway can function as Ingress Gateway, Waypoint Proxy, or both simultaneously. In this guide, we will demonstrate how to set up Envoy Gateway to perform both roles.

Prerequisites​

  • A Kubernetes cluster with Istio installed and configured in Ambient Mode. If you haven't set up Istio in Ambient Mode yet, refer to the Migration to Ambient Mode guide.
  • kubectl and helm command-line tools installed and configured to connect to your cluster.
  • Basic understanding of Istio, Envoy Gateway, and Kubernetes Gateway API.

Step 1: Install Envoy Gateway​

Please follow the Envoy Gateway installation guide to install Envoy Gateway in your Kubernetes cluster. To ensure it functions correctly as a waypoint proxy in Ambient Mode, make sure to set the deployment type to GatewayNamespace during installation.

helm install teg ${REGISTRY}/teg-envoy-gateway-helm \
 --version ${CHART_VERSION} \
 --set gateway-helm.config.envoyGateway.provider.kubernetes.deploy.type=GatewayNamespace \
 -n envoy-gateway-system --create-namespace

Step 2: Install Bookinfo Demo Application​

To demonstrate the functionality of Envoy Gateway as an Ingress Gateway and Waypoint Proxy, we'll use the Bookinfo demo application.

First, label the default namespace to enable Ambient Mode:

kubectl label namespace default istio.io/dataplane-mode=ambient

Next, deploy the Bookinfo application:

cd ${ISTIO_INSTALL_DIR}
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml

Step 2: Configure Envoy Gateway as Ingress Gateway​

To configure Envoy Gateway as an Ingress Gateway, create a Gateway resource that defines how external traffic should be routed into the mesh. Below is an example configuration:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  labels:
    istio.io/dataplane-mode: ambient
  name: bookinfo-ingress
spec:
  gatewayClassName: teg
  listeners:
  - name: ingress
    port: 80
    protocol: HTTP

We'll also create an HTTPRoute resource to route incoming requests to the productpage service of the Bookinfo application:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ingress-bookinfo
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: bookinfo-ingress
  rules:
  - backendRefs:
    - group: ""
      kind: Service
      name: productpage
      port: 9080

Then, you can access the Bookinfo application through the Envoy Gateway's external IP address. Open your web browser and navigate to http://<EXTERNAL-IP>/productpage to see the Bookinfo application.

Step 3: Configure Envoy Gateway as Waypoint Proxy​

Since waypoint proxies may have different configurations compared to ingress gateways, we will create a separate GatewayClass for waypoint proxies. Below is an example configuration for the GatewayClass:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg-waypoint
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: waypoint
    namespace: envoy-gateway-system

Create a EnvoyProxy resource to define the configuration for the waypoint proxy:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: waypoint
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: ClusterIP
        patch:
          type: StrategicMerge
          value:
            spec:
              ports:
                # HACK:zTunnel currently expects the HBONE port to always be on the Waypoint's Service
                # This will be fixed in future PRs to both istio and zTunnel.
                - name: fake-hbone-port
                  port: 15008
                  protocol: TCP
                  targetPort: 15008

The 15008 port is actually not used in this setup, but it is required by zTunnel to recognize the waypoint proxy. This is a known issue and will be fixed in future Istio releases.

Next, create a Gateway resource for the waypoint proxy:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  labels:
    istio.io/dataplane-mode: ambient
  name: reviews-waypoint
spec:
  gatewayClassName: eg-waypoint
  listeners:
  - name: reviews
    port: 9080
    protocol: HTTP

We'll also create an HTTPRoute resource to route traffic to the reviews service of the Bookinfo application:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
spec:
  hostnames:
  - reviews
  - reviews.default
  - reviews.default.svc.cluster.local
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: reviews-waypoint
  rules:
  - backendRefs:
    - group: ""
      kind: Service
      name: reviews
      port: 9080

Finally, we need to add an label to the reviews service to specify that it should use the waypoint proxy for Layer 7 traffic:

apiVersion: v1
kind: Service
metadata:
  labels:
    app: reviews
    service: reviews
    istio.io/use-waypoint: reviews-waypoint
  name: reviews
spec:
  ports:
  - name: http
    port: 9080
    protocol: TCP
    targetPort: 9080
  selector:
    app: reviews

With this configuration, the reviews service will route its Layer 7 traffic through the Envoy Gateway waypoint proxy, allowing for advanced routing and policy enforcement.

Open your web browser and navigate to http://<EXTERNAL-IP>/productpage to see the Bookinfo application. In the log of the waypoint proxy, you can see the traffic to the reviews service being routed through the waypoint proxy.

kubectl logs -l gateway.envoyproxy.io/owning-gateway-name=reviews-waypoint -c envoy --tail 1

{":authority":"reviews:9080","bytes_received":0,"bytes_sent":358,"connection_termination_details":null,"downstream_local_address":"10.244.0.19:9080","downstream_remote_address":"10.244.0.17:54117","duration":16,"method":"GET","protocol":"HTTP/1.1","requested_server_name":null,"response_code":200,"response_code_details":"via_upstream","response_flags":"-","route_name":"httproute/default/reviews/rule/0/match/0/reviews","start_time":"2025-06-30T06:26:49.054Z","upstream_cluster":"httproute/default/reviews/rule/0","upstream_host":"10.244.0.14:9080","upstream_local_address":"10.244.0.19:37302","upstream_transport_failure_reason":null,"user-agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36","x-envoy-origin-path":"/reviews/0","x-envoy-upstream-service-time":null,"x-forwarded-for":"10.244.0.17","x-request-id":"47a3520f-bf6d-40dc-9d7a-6aa4dcddd5b1"}

Envoy Gateway Policies​

You can apply various Istio policies to the Envoy Gateway to enhance security and traffic management at both the ingress gateway and waypoint proxy levels. Here are some examples:

OIDC Authentication at Ingress Gateway​

Follow the OIDC Authentication guide to set up OIDC authentication at the ingress gateway. This will ensure that only authenticated users can access the Bookinfo application. You can use any OIDC provider, such as Google, AWS, Okta, KeyCloak or Auth0. The following is an example configuration using AWS Cognito as the OIDC provider:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: oidc-example
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: ingress-bookinfo
  oidc:
    provider:
      issuer: https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_ewsdqjtaD
    clientID: 3su394h1en0hpdfd86lddh9fkd
    clientSecret:
      name: my-app-client-secret
    redirectURL: https://www.example.com/productpage/oauth2/callback
    logoutPath: /productpage/logout
    forwardAccessToken: true
  jwt:
    providers:
    - name: aws-cognito
      issuer: https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_ewsdqjtaD
      remoteJWKS:
        uri: https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_ewsdqjtaD/.well-known/jwks.json
  authorization:
    defaultAction: Deny
    rules:
    - action: Allow
      name: allow
      principal:
        jwt:
          scopes: [openid]
          claims:
          - name: username
            valueType: String
            values:
            - 89eed458-a031-70a2-f079-21ce7ccae5f0
          provider: aws-cognito

This configuration will require users to authenticate using AWS Cognito before accessing the Bookinfo application. It also enforces authorization based on the scope and claims in the JWT token.

Please note that the configuration above is just an example. You will need to replace the issuer, clientID, clientSecret, and redirectURL with your own values from your OIDC provider.

Then, you can access the Bookinfo application through the Envoy Gateway's external IP address. Open your web browser and navigate to https://<EXTERNAL-IP>/productpage. You will be redirected to the AWS Cognito login page. After logging in, you will be redirected back to the Bookinfo application.

Local Rate Limiting at Waypoint Proxy​

Apply local rate limiting to control the rate of requests to the reviews service:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: reviews-rate-limiting
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: reviews
  rateLimit:
    type: Local
    local:
      rules:
      - limit:
          requests: 3
          unit: Minute

Open your web browser and navigate to http://<EXTERNAL-IP>/productpage to see the Bookinfo application. If you refresh the page more than 3 times in a minute, , you will see that the reviews are not displayed. Instead, you will see a message "Sorry, product reviews are currently unavailable for this book."

Look at the Envoy Gateway waypoint proxy's logs, you can see that the request is rate limited:

kubectl logs -l gateway.envoyproxy.io/owning-gateway-name=reviews-waypoint -c envoy --tail 1

{":authority":"reviews:9080","bytes_received":0,"bytes_sent":18,"connection_termination_details":null,"downstream_local_address":"10.244.0.19:9080","downstream_remote_address":"10.244.0.17:54253","duration":0,"method":"GET","protocol":"HTTP/1.1","requested_server_name":null,"response_code":429,"response_code_details":"local_rate_limited","response_flags":"RL","route_name":"httproute/default/reviews/rule/0/match/0/reviews","start_time":"2025-06-30T06:26:56.063Z","upstream_cluster":"httproute/default/reviews/rule/0","upstream_host":null,"upstream_local_address":null,"upstream_transport_failure_reason":null,"user-agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36","x-envoy-origin-path":"/reviews/0","x-envoy-upstream-service-time":null,"x-forwarded-for":"10.244.0.17","x-request-id":"8b6f06bd-dbf7-4df9-b314-80931bbc878b"}

What's Next?​

All the Envoy Gateway's Layer 7 features are available at both the Ingress Gateway and Waypoint Proxy levels, including the Gateway API features, Envoy Gateway's ClientTrafficPolicy, BackendTrafficPolicy, SecurityPolicy, and EnvoyExtensionPolicy. You can follow the Envoy Gateway's documentation to try them out.