Installing Envoy

The Envoy project provides a number of pre-built Docker images for both amd64 and arm64 architectures.

If you are installing on Mac OSX, you can install natively with brew.

Once you have installed Envoy, check out the quick start guide for more information on getting your Envoy proxy up and running.

Install Envoy on Debian GNU/Linux

You can install Envoy on Debian using packages created by Tetrate until official packages exist.

$ sudo apt update
$ sudo apt install debian-keyring debian-archive-keyring apt-transport-https curl lsb-release
$ curl -sL 'https://deb.dl.getenvoy.io/public/gpg.8115BA8E629CC074.key' | sudo gpg --dearmor -o /usr/share/keyrings/getenvoy-keyring.gpg
# Verify the keyring - this should yield "OK"
$ echo a077cb587a1b622e03aa4bf2f3689de14658a9497a9af2c427bba5f4cc3c4723 /usr/share/keyrings/getenvoy-keyring.gpg | sha256sum --check
$ echo "deb [arch=amd64 signed-by=/usr/share/keyrings/getenvoy-keyring.gpg] https://deb.dl.getenvoy.io/public/deb/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/getenvoy.list
$ sudo apt update
$ sudo apt install getenvoy-envoy

Install Envoy on Ubuntu Linux

You can install Envoy on Ubuntu using packages created by Tetrate until official packages exist.

$ sudo apt update
$ sudo apt install apt-transport-https gnupg2 curl lsb-release
$ curl -sL 'https://deb.dl.getenvoy.io/public/gpg.8115BA8E629CC074.key' | sudo gpg --dearmor -o /usr/share/keyrings/getenvoy-keyring.gpg
# Verify the keyring - this should yield "OK"
$ echo a077cb587a1b622e03aa4bf2f3689de14658a9497a9af2c427bba5f4cc3c4723 /usr/share/keyrings/getenvoy-keyring.gpg | sha256sum --check
$ echo "deb [arch=amd64 signed-by=/usr/share/keyrings/getenvoy-keyring.gpg] https://deb.dl.getenvoy.io/public/deb/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/getenvoy.list
$ sudo apt update
$ sudo apt install -y getenvoy-envoy

Install Envoy on RPM-based distros

You can install Envoy on Centos/Redhat Enterprise Linux (RHEL) using packages created by Tetrate until official packages exist.

$ sudo yum install yum-utils
$ sudo rpm --import 'https://rpm.dl.getenvoy.io/public/gpg.CF716AF503183491.key'
$ curl -sL 'https://rpm.dl.getenvoy.io/public/config.rpm.txt?distro=el&codename=7' > /tmp/tetrate-getenvoy-rpm-stable.repo
$ sudo yum-config-manager --add-repo '/tmp/tetrate-getenvoy-rpm-stable.repo'
$ sudo yum makecache --disablerepo='*' --enablerepo='tetrate-getenvoy-rpm-stable'
$ sudo yum install getenvoy-envoy

Install Envoy on Mac OSX

You can install Envoy on Mac OSX using the official brew repositories.

$ brew update
$ brew install envoy

Install Envoy on Windows

You can run Envoy using the official Windows Docker image.

$ docker pull envoyproxy/envoy-windows-dev:a2673f749bb7a3f68f357e006e49b2143cc98b8f
$ docker run --rm envoyproxy/envoy-windows-dev:a2673f749bb7a3f68f357e006e49b2143cc98b8f --version

Install Envoy using Docker

You can run Envoy using the official Docker images.

The following commands will pull and show the Envoy version of current images.

$ docker pull envoyproxy/envoy:dev-a2673f749bb7a3f68f357e006e49b2143cc98b8f
$ docker run --rm envoyproxy/envoy:dev-a2673f749bb7a3f68f357e006e49b2143cc98b8f --version

Supported tags

For stable Envoy versions images are created for the version and the latest of that minor version.

For example, if the latest version in the v1.73.x series is v1.73.7 then images are created for:

  • envoyproxy/envoy:v1.73.7

  • envoyproxy/envoy:v1.73-latest

A similar strategy is used to create images for each of the versioned variants.

Supported architectures

The Envoy project currently supports amd64 and arm64 architectures for its Linux build and images.

Contrib builds

As described in this document, the Envoy project allows extensions to enter the repository as “contrib” extensions. The requirements for such extensions are lower, and as such they are only available by default in special images.

Throughout the documentation, extensions are clearly marked as being a contrib extension or a core extension.

Image variants

envoyproxy/envoy:<version>

These images contains just the core Envoy binary built upon an Ubuntu base image.

envoyproxy/envoy:distroless-<version>

These images contains just the core Envoy binary built upon a distroless (nonroot/nossl) base image.

These images are the most efficient and secure way to deploy Envoy in a container.

envoyproxy/envoy:contrib-<version>

These images contain the Envoy binary built with all contrib extensions on top of an Ubuntu base.

envoyproxy/envoy:tools-<version>

These images contain tools that are separate from the proxy binary but are useful in supporting systems such as CI, configuration generation pipelines, etc

envoyproxy/envoy:dev / envoyproxy/envoy:dev-<SHA> / envoyproxy/envoy:<variant>-dev / envoyproxy/envoy:<variant>-dev-<SHA>

The Envoy project considers the main branch to be release candidate quality at all times, and many organizations track and deploy main in production.

We encourage you to do the same so that issues can be reported and resolved as quickly as possible.

envoyproxy/envoy:debug-<version> / envoyproxy/envoy:<variant>-debug-<version>

These images are built for each of the variants, but with an Envoy binary containing debug symbols.

Pre-built Envoy Docker images

envoyproxy/envoy

The following table shows the available Docker tag variants for the latest envoyproxy/envoy images.

variant

latest stable (amd64/arm64)

main dev (amd64/arm64)

envoy (default)

envoyproxy/envoy:v1.29-latest

envoyproxy/envoy:dev

contrib

envoyproxy/envoy:contrib-v1.29-latest

envoyproxy/envoy:contrib-dev

distroless

envoyproxy/envoy:distroless-v1.29-latest

envoyproxy/envoy:distroless-dev

debug

envoyproxy/envoy:debug-v1.29-latest

envoyproxy/envoy:debug-dev

contrib-debug

envoyproxy/envoy:contrib-debug-v1.29-latest

envoyproxy/envoy:contrib-debug-dev

tools

envoyproxy/envoy:tools-v1.29-latest

envoyproxy/envoy:tools-dev

envoyproxy/envoy-windows, envoyproxy/envoy-windows-dev

Release binary with symbols stripped on top of a Windows Server 1809 base.

The windows-dev image also contains build tools.

variant

latest stable (amd64)

main dev (amd64)

envoy-windows

envoyproxy/envoy-windows:v1.29-latest

envoyproxy/envoy-windows-dev

envoyproxy/envoy-build-ubuntu

Build images are always versioned using their commit SHA, which is in turn committed to the Envoy repository to ensure reproducible builds.

variant

latest (amd64/arm64)

envoy-build-ubuntu (default)

envoyproxy/envoy-build-ubuntu:<build_sha>

envoy-build-ubuntu:mobile

envoyproxy/envoy-build-ubuntu:mobile-<build_sha>

Note

The envoy-build-ubuntu image does not contain a working Envoy server, but can be used for building Envoy and related containers.

This image requires 4-5GB of available disk space to use.