Getting Started

    The fastest way to get started using Envoy is . You can also build it from source.

    These examples use the , but use only the static configuration feature of the API, which is most useful for simple requirements. For more complex requirements Dynamic Configuration is supported.

    These instructions run from files in the Envoy repo. The sections below give a more detailed explanation of the configuration file and execution steps for the same configuration.

    A very minimal Envoy configuration that can be used to validate basic plain HTTP proxying is available in . This is not intended to represent a realistic Envoy deployment:

    The Docker image used will contain the latest version of Envoy and a basic Envoy configuration. This basic configuration tells Envoy to route incoming requests to *.google.com.

    Envoy can be configured using a single YAML file passed in as an argument on the command line.

    The admin message is required to configure the administration server. The address key specifies the listening which in this case is simply 0.0.0.0:9901.

    2.   access_log_path: /tmp/admin_access.log
    3.   address:
    4.     socket_address: { address: 0.0.0.0, port_value: 9901 }

    The static_resources contains everything that is configured statically when Envoy starts, as opposed to the means of configuring resources dynamically when Envoy is running. The describes this.

    1. static_resources:
    1. listeners:
    2. - name: listener_0
    3.   address:
    4.     socket_address: { address: 0.0.0.0, port_value: 10000 }
    5.   filter_chains:
    6.   - filters:
    7.     - name: envoy.filters.network.http_connection_manager
    8.       typed_config:
    9.         "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
    10.         stat_prefix: ingress_http
    11.         codec_type: AUTO
    12.         route_config:
    13.           name: local_route
    14.           - name: local_service
    16.             routes:
    17.             - match: { prefix: "/" }
    18.               route: { host_rewrite_literal: www.google.com, cluster: service_google }
    19.         http_filters:
    20.         - name: envoy.filters.http.router

    The specification of the clusters.

    Create a simple Dockerfile to execute Envoy, which assumes that envoy.yaml (described above) is in your local directory. You can refer to the .

    1. FROM envoyproxy/envoy:v1.16.0
    2. COPY envoy.yaml /etc/envoy/envoy.yaml

    Build the Docker image that runs your configuration using:

    1. $ docker build -t envoy:v1 .

    And now you can execute it with:

    1. $ docker run -d --name envoy -p 9901:9901 -p 10000:10000 envoy:v1

    And finally, test it using:

    If you would like to use Envoy with docker-compose you can overwrite the provided configuration file by using a volume.

    By default the Docker image will run as the envoy user created at build time.

    The uid and gid of this user can be set at runtime using the ENVOY_UID and ENVOY_GID environment variables. This can be done, for example, on the Docker command line:

    1. $ docker run -d --name envoy -e ENVOY_UID=777 -e ENVOY_GID=777 -p 9901:9901 -p 10000:10000 envoy:v1

    If you wish to run the container as the root user you can set ENVOY_UID to .

    The envoy image sends application logs to /dev/stdout and /dev/stderr by default, and these can be viewed in the container log.

    If you send application, admin or access logs to a file output, the envoy user will require the necessary permissions to write to this file. This can be achieved by setting the ENVOY_UID and/or by making the file writeable by the envoy user.

    For example, to mount a log folder from the host and make it writable, you can:

    1. $ mkdir logs
    2. $ chown 777 logs
    3. $ docker run -d -v `pwd`/logs:/var/log --name envoy -e ENVOY_UID=777 -p 9901:9901 -p 10000:10000 envoy:v1

    You can then configure envoy to log to files in /var/log

    The default envoy uid and gid are 101.

    The envoy user also needs to have permission to access any required configuration files mounted into the container.

    If you are running in an environment with a strict umask setting, you may need to provide envoy with access either by setting the uid or gid of the file, or by making the configuration file readable by the envoy user.

    We’ve created a number of sandboxes using Docker Compose that set up different environments to test out Envoy’s features and show sample configurations. As we gauge peoples’ interests we will add more sandboxes demonstrating different features. The following sandboxes are available: