Run Envoy

The following instructions walk through starting Envoy as a system daemon or using the Envoy Docker image.

Check your Envoy version

Once you have installed Envoy, you can check the version information as follows:

$ envoy --version
...

View the Envoy command line options

You can view the Envoy command line options with the --help flag:

$ envoy --help
...

Run Envoy with the demo configuration

The -c or --config-path flag tells Envoy the path to its initial configuration.

Envoy will parse the config file according to the file extension, please see the config path command line option for further information.

To start Envoy as a system daemon download the demo configuration, and start as follows:

$ envoy -c envoy-demo.yaml
...

Check Envoy is proxying on http://localhost:10000.

$ curl -v localhost:10000
...

You can exit the server with Ctrl-c.

See the admin quick start guide for more information about the Envoy admin interface.

Override the default configuration

You can provide an override configuration using --config-yaml which will merge with the main configuration.

This option can only be specified once.

Save the following snippet to envoy-override.yaml:

admin:
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9902

Warning

If you run Envoy inside a Docker container you may wish to use 0.0.0.0. Exposing the admin interface in this way may give unintended control of your Envoy server. Please see the admin section for more information.

Next, start the Envoy server using the override configuration:

On Linux/Mac: run:

$ envoy -c envoy-demo.yaml --config-yaml "$(cat envoy-override.yaml)"
...

On Windows run:

Note

On August 31, 2023 the Envoy project ended official Windows support due to a lack of resources. We will continue to accept patches related to the Windows build. Until further notice, Windows builds are excluded from Envoy CI, as well as the Envoy release and security processes.

$ envoy -c envoy-demo.yaml --config-yaml "$(Get-Content -Raw envoy-override.yaml)"
...

The Envoy admin interface should now be available on http://localhost:9902.

$ curl -v localhost:9902
...

Note

When merging yaml lists (e.g. listeners or clusters) the merged configurations are appended.

You cannot therefore use an override file to change the configurations of previously specified listeners or clusters

Validating your Envoy configuration

You can start Envoy in validate mode.

This allows you to check that Envoy is able to start with your configuration, without actually starting or restarting the service, or making any network connections.

If the configuration is valid the process will print OK and exit with a return code of 0.

For invalid configuration the process will print the errors and exit with 1.

$ envoy --mode validate -c my-envoy-config.yaml
[2020-11-08 12:36:06.543][11][info][main] [source/server/server.cc:583] runtime: layers:
- name: base
  static_layer:
    {}
- name: admin
  admin_layer:
    {}
[2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:95] loading tracing configuration
[2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:70] loading 0 static secret(s)
[2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:76] loading 1 cluster(s)
[2020-11-08 12:36:06.546][11][info][config] [source/server/configuration_impl.cc:80] loading 1 listener(s)
[2020-11-08 12:36:06.549][11][info][config] [source/server/configuration_impl.cc:121] loading stats sink configuration
configuration 'my-envoy-config.yaml' OK

Envoy logging

By default Envoy system logs are sent to /dev/stderr.

This can be overridden using --log-path.

$ mkdir logs
$ envoy -c envoy-demo.yaml --log-path logs/custom.log

Access log paths can be set for the admin interface, and for configured listeners.

The demo configuration is configured with a listener that logs access to /dev/stdout:

12        typed_config:
13          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
14          stat_prefix: ingress_http
15          access_log:
16          - name: envoy.access_loggers.stdout
17            typed_config:
18              "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
19          http_filters:
20          - name: envoy.filters.http.router
21            typed_config:
22              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

The default configuration in the Envoy Docker container also logs access in this way.

Logging to /dev/stderr and /dev/stdout for system and access logs respectively can be useful when running Envoy inside a container as the streams can be separated, and logging requires no additional files or directories to be mounted.

Some Envoy filters and extensions may also have additional logging capabilities.

Envoy can be configured to log to different formats, and to different outputs in addition to files and stdout/err.

Envoy networking

By default Envoy can use both IPv4 and IPv6 networks.

If your environment does not support IPv6 you should disable it.

This may be the case when using Docker on a non-linux host (see here for more information regarding IPv6 support in Docker).

You can disable IPv6 by setting the dns_lookup_family to V4_ONLY in your configuration as follows:

envoy-demo.yaml
34  clusters:
35  - name: service_envoyproxy_io
36    type: LOGICAL_DNS
37    # Comment out the following line to test on v6 networks
38    dns_lookup_family: V4_ONLY
39    load_assignment:
40      cluster_name: service_envoyproxy_io
41      endpoints:
42      - lb_endpoints:
43        - endpoint:
44            address:
45              socket_address:

Debugging Envoy

The log level for Envoy system logs can be set using the -l or --log-level option.

The available log levels are:

  • trace

  • debug

  • info

  • warning/warn

  • error

  • critical

  • off

The default is info.

You can also set the log level for specific components using the --component-log-level option.

The following example inhibits all logging except for the upstream and connection components, which are set to debug and trace respectively.

$ envoy -c envoy-demo.yaml -l off --component-log-level upstream:debug,connection:trace
...

Tip

See ALL_LOGGER_IDS in logger.h for a list of components.