Difficulty: Beginner
Estimated Time: 10 minutes

Envoy is an open source edge and service proxy, designed for cloud-native applications.

The following scenario demonstrates how to configure Envoy as a proxy, allowing you to forward traffic to different destinations.

You will learn how to:

  • Configure Envoy Proxy to forward traffic to external websites.

  • Configure Envoy Proxy to forward traffic to Docker Containers.

  • Perform path-based routing for controlling traffic destination.

Once the Envoy proxy is in place, it can be extended to support load balancing, health checking and metrics. These are discussed in more advanced scenarios.

Congratulations. You have successfully:

  • Configured Envoy as a reverse proxy to external websites.
  • Learned how to forward traffic to Docker Containers running on your host machine.

Continue completing Katacoda scenarios to learn more about the potential of Envoy.

Getting Started with Envoy

Step 1 of 4

Create Proxy Config

Envoy is configured using a YAML definition file to control the proxy's behaviour. In this step, we're building a configuration using the Static Configuration API. This means that all the settings are pre-defined within the configuration.

Envoy also supports Dynamic Configuration. This allows the settings to be discovered via an external source.


The first line of the Envoy configuration defines the API configuration being used. In this case, we're configuring the Static API, so the first line should be static_resources. Copy the snippet to the editor.



The beginning of the configuration defines the Listeners. A Listener is the networking configuration, such as IP address and ports, that Envoy listens to for requests. Envoy runs inside of a Docker Container, so it needs to listen on the IP address In this case, Envoy will listen on port 10000.

Below is the configuration to define this setup. Copy the snippet to the editor.

  - name: listener_0
      socket_address: { address:, port_value: 10000 }

Filter Chains and Filters

With Envoy listening for incoming traffic, the next stage is to define how to process the requests. Each Listener has a set of filters, and different Listeners can have a different set of filters.

In this example, we'll proxy all traffic to Google.com (thanks Google!). The result: We should be able to request the Envoy endpoint and see the Google homepage appear, without the URL changing.

Filtering is defined using filter_chains. The aim of each filter is to find a match on the incoming request, to match it to the target destination. Copy the snippet to the editor.

    - filters:
      - name: envoy.http_connection_manager
          stat_prefix: ingress_http
            name: local_route
            - name: local_service
              domains: ["*"]
              - match: { prefix: "/" }
                route: { host_rewrite: www.google.com, cluster: service_google }
          - name: envoy.router

The filter is using envoy.http_connection_manager, a built-in filter designed for HTTP connections. The details are as follows:

  • stat_prefix: The human-readable prefix to use when emitting statistics for the connection manager.

  • route_config: The configuration for the route. If the virtual host matches, then the route is checked. In this example, the route_config matches all incoming HTTP requests, no matter the host domain requested.

  • routes: If the URL prefix is matched then a set of route rules defines what should happen next. In this case "/" means match the root of the request

  • host_rewrite: Change the inbound Host header for the HTTP request.

  • cluster: The name of the cluster which will handle the request. The implementation is defined below.

  • http_filters: The filter allows Envoy to adapt and modify the request as it is processed.


When a request matches a filter, the request is passed onto a cluster. The cluster shown below defines that the host is google.com running over HTTPS. If multiple hosts had been defined, then Envoy would perform a Round Robin strategy.

Copy the cluster implementation to complete the configuration:

  - name: service_google
    connect_timeout: 0.25s
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    lb_policy: ROUND_ROBIN
    hosts: [{ socket_address: { address: google.com, port_value: 443 }}]
    tls_context: { sni: www.google.com }


Finally, an admin section is required. The admin section is explained in more detail in the following steps.

  access_log_path: /tmp/admin_access.log
    socket_address: { address:, port_value: 9901 }

This structure defines the boilerplate for Envoy Static Configuration. The Listener defines the ports and IP address for Envoy. The listener has a set of filters to match on the incoming requests. Once a request is matched, it will be forwarded to a cluster.

You can view the full configuration on Github.