Using the Envoy Docker Image¶
The following examples use the official Envoy Docker image.
These instructions are known to work for the
Running Envoy with docker-compose¶
If you would like to use Envoy with docker-compose you can overwrite the provided configuration file by using a volume.
version: '3' services: envoy: image: envoyproxy/envoy:v1.21.1 ports: - "10000:10000" volumes: - ./envoy.yaml:/etc/envoy/envoy.yaml
If you use this method, you will have to ensure that the
envoy user can read the mounted file
either by ensuring the correct permissions on the file, or making it world-readable, as described
Build and run a Docker image¶
Create a simple Dockerfile to execute Envoy.
If you create a custom
envoy.yaml you can create your own Docker image with it using the following
FROM envoyproxy/envoy:v1.21.1 COPY envoy.yaml /etc/envoy/envoy.yaml RUN chmod go+r /etc/envoy/envoy.yaml
Build the Docker image using:
$ docker build -t envoy:v1 .
Assuming Envoy is configured to listen on ports
10000, you can now start it
$ docker run -d --name envoy -p 9901:9901 -p 10000:10000 envoy:v1
Permissions for running Docker Envoy containers as a non-root user¶
By default, the Envoy Docker image will start as the root user but will switch to the
user created at build time, in the Docker
Alternatively, you can start the container specifying the Docker
In this case the container will not attempt to drop privileges, but you will still need to ensure that the user running inside the container has any required permissions, as described below.
gid of the
envoy user inside the container¶
gid for the
envoy user are
gid of this user can be set at runtime using the
This can be done, for example, on the Docker command line:
$ docker run -d --name envoy -e ENVOY_UID=777 -e ENVOY_GID=777 envoyproxy/envoy:v1.21.1
This can be useful if you wish to restrict or provide access to
unix sockets inside the container, or
for controlling access to an Envoy socket from outside of the container.
To run the process inside the container as the
root user you can set
but doing so has the potential to weaken the security of your running container.
Logging permissions inside the Envoy container¶
envoy image sends application logs to
/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
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:
$ mkdir logs $ chown 777 logs $ docker run -d --name envoy -v $(pwd)/logs:/var/log -e ENVOY_UID=777 envoyproxy/envoy:v1.21.1
You can then configure
envoy to log to files in
Configuration and binary file permissions inside the Envoy container¶
envoy user also needs to have permission to access any required configuration files mounted
into the container.
Any binary files specified in the configuration should also be executable by the
If you are running in an environment with a strict
umask setting, you may need to provide
with access by setting the ownership and/or permissions of the file.
One method of doing this without changing any file permissions is to start the container with the
uid, for example:
$ docker run -d --name envoy -v $(pwd)/envoy.yaml:/etc/envoy/envoy.yaml -e ENVOY_UID=$(id -u) envoyproxy/envoy:v1.21.1
Listen only on ports > 1024 inside the Docker Envoy container¶
Unix-based systems restrict opening
well-known ports (ie. with a port number <
1024) to the
If you need to listen on a
well-known port you can use Docker to do so.
For example, to create an Envoy server listening on port
8000, with forwarding from port
$ docker run -d --name envoy -p 80:8000 envoyproxy/envoy:v1.21.1