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
...
$ docker run --rm \
envoyproxy/envoy:v1.21.6 \
--version
...
PS> docker run --rm
'envoyproxy/envoy-windows:v1.21.6'
--version
...
View the Envoy command line options¶
You can view the Envoy command line options with the --help
flag:
$ envoy --help
...
$ docker run --rm \
envoyproxy/envoy:v1.21.6 \
--help
...
PS> docker run --rm
'envoyproxy/envoy-windows:v1.21.6'
--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
...
You can start the Envoy Docker image without specifying a configuration file, and it will use the demo config by default.
$ docker run --rm -it \
-p 9901:9901 \
-p 10000:10000 \
envoyproxy/envoy:v1.21.6
...
To specify a custom configuration you can mount the config into the container, and specify the path with -c
.
Assuming you have a custom configuration in the current directory named envoy-custom.yaml
:
$ docker run --rm -it \
-v $(pwd)/envoy-custom.yaml:/envoy-custom.yaml \
-p 9901:9901 \
-p 10000:10000 \
envoyproxy/envoy:v1.21.6 \
-c /envoy-custom.yaml
...
You can start the Envoy Docker image without specifying a configuration file, and it will use the demo config by default.
PS> docker run --rm -it
-p '9901:9901'
-p '10000:10000'
'envoyproxy/envoy-windows:v1.21.6'
...
To specify a custom configuration you can mount the config into the container, and specify the path with -c
.
Assuming you have a custom configuration in the current directory named envoy-custom.yaml
, from PowerShell run:
PS> docker run --rm -it
-v "$PWD\:`"C:\envoy-configs`""
-p '9901:9901'
-p '10000:10000'
'envoyproxy/envoy-windows:v1.21.6'
-c 'C:\envoy-configs\envoy-custom.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
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:
$ envoy -c envoy-demo.yaml --config-yaml "$(Get-Content -Raw envoy-override.yaml)"
...
$ docker run --rm -it \
-p 9902:9902 \
-p 10000:10000 \
envoyproxy/envoy:v1.21.6 \
-c /etc/envoy/envoy.yaml \
--config-yaml "$(cat envoy-override.yaml)"
...
PS> docker run --rm -it
-p '9902:9902'
-p '10000:10000'
'envoyproxy/envoy-windows:v1.21.6'
-c 'C:\ProgramData\envoy.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
...
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
$ docker run --rm \
-v $(pwd)/my-envoy-config.yaml:/my-envoy-config.yaml \
envoyproxy/envoy:v1.21.6 \
--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
PS> docker run --rm -it
-v "$PWD\:`"C:\envoy-configs`""
-p '9901:9901'
-p '10000:10000'
'envoyproxy/envoy-windows:v1.21.6'
--mode validate
-c 'C:\envoy-configs\my-envoy-config.yaml'
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
$ mkdir logs
$ chmod go+rwx logs/
$ docker run --rm -it \
-p 10000:10000 \
-v $(pwd)/logs:/logs \
envoyproxy/envoy:v1.21.6 \
-c /etc/envoy/envoy.yaml \
--log-path logs/custom.log
PS> mkdir logs
PS> docker run --rm -it
-p '10000:10000'
-v "$PWD\logs\:`"C:\logs`""
'envoyproxy/envoy-windows:v1.21.6'
-c 'C:\ProgramData\envoy.yaml'
--log-path 'C:\logs\custom.log'
Note
Envoy on a Windows system Envoy will output to CON
by default.
This can also be used as a logging path when configuring logging.
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 route_config:
22 name: local_route
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
.
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
...
$ docker run --rm -d \
-p 9901:9901 \
-p 10000:10000 \
envoyproxy/envoy:v1.21.6 \
-c /etc/envoy/envoy.yaml \
-l off \
--component-log-level upstream:debug,connection:trace
...
PS> mkdir logs
PS> docker run --rm -it
-p '10000:10000'
envoyproxy/|envoy_windws_docker_image|
-c 'C:\ProgramData\envoy.yaml'
-l off
--component-log-level 'upstream:debug,connection:trace'
...
Tip
See ALL_LOGGER_IDS
in logger.h for a list of components.