Two flavors of Envoy Docker images, based on Ubuntu and Alpine Linux, are built.
The Ubuntu based Envoy Docker image at envoyproxy/envoy-build:<hash>
is used for CircleCI checks,
where <hash>
is specified in envoy_build_sha.sh
. Developers
may work with envoyproxy/envoy-build:latest
to provide a self-contained environment for building Envoy binaries and
running tests that reflects the latest built Ubuntu Envoy image. Moreover, the Docker image
at envoyproxy/envoy:<hash>
is an image that has an Envoy binary at /usr/local/bin/envoy
. The <hash>
corresponds to the master commit at which the binary was compiled. Lastly, envoyproxy/envoy:latest
contains an Envoy
binary built from the latest tip of master that passed tests.
Minimal images based on Alpine Linux allow for quicker deployment of Envoy. Two Alpine based images are built,
one with an Envoy binary with debug (envoyproxy/envoy-alpine-debug
) symbols and one stripped of them (envoyproxy/envoy-alpine
).
Both images are pushed with two different tags: <hash>
and latest
. Parallel to the Ubuntu images above, <hash>
corresponds to the
master commit at which the binary was compiled, and latest
corresponds to a binary built from the latest tip of master that passed tests.
Currently there are three build images:
envoyproxy/envoy-build
— alias toenvoyproxy/envoy-build-ubuntu
.envoyproxy/envoy-build-ubuntu
— based on Ubuntu 16.04 (Xenial) which uses the GCC 5.4 compiler.
We also install and use the clang-7 compiler for some sanitizing runs.
An example basic invocation to build a developer version of the Envoy static binary (using the Bazel fastbuild
type) is:
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.dev'
The build image defaults to envoyproxy/envoy-build-ubuntu
, but you can choose build image by setting IMAGE_NAME
in the environment.
In case your setup is behind a proxy, set `http_proxy` and `https_proxy` to the proxy servers before invoking the build.
```bash
IMAGE_NAME=envoyproxy/envoy-build-ubuntu http_proxy=http://proxy.foo.com:8080 https_proxy=http://proxy.bar.com:8080 ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.dev'
The Envoy binary can be found in /tmp/envoy-docker-build/envoy/source/exe/envoy-fastbuild
on the Docker host. You
can control this by setting ENVOY_DOCKER_BUILD_DIR
in the environment, e.g. to
generate the binary in ~/build/envoy/source/exe/envoy-fastbuild
you can run:
ENVOY_DOCKER_BUILD_DIR=~/build ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.dev'
For a release version of the Envoy binary you can run:
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.release.server_only'
The build artifact can be found in /tmp/envoy-docker-build/envoy/source/exe/envoy
(or wherever
$ENVOY_DOCKER_BUILD_DIR
points).
For a debug version of the Envoy binary you can run:
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.debug.server_only'
The build artifact can be found in /tmp/envoy-docker-build/envoy/source/exe/envoy-debug
(or wherever
$ENVOY_DOCKER_BUILD_DIR
points).
To leverage a bazel remote cache add the http_remote_cache endpoint to the BAZEL_BUILD_OPTIONS environment variable
BAZEL_BUILD_OPTIONS='--remote_http_cache=http://127.0.0.1:28080' ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.release'
The ./ci/run_envoy_docker.sh './ci/do_ci.sh <TARGET>'
targets are:
bazel.api
— build and run API tests under-c fastbuild
with clang.bazel.asan
— build and run tests under-c dbg --config=clang-asan
with clang.bazel.debug
— build Envoy static binary and run tests under-c dbg
.bazel.debug.server_only
— build Envoy static binary under-c dbg
.bazel.dev
— build Envoy static binary and run tests under-c fastbuild
with clang.bazel.release
— build Envoy static binary and run tests under-c opt
with gcc.bazel.release <test>
— build Envoy static binary and run a specified test or test dir under-c opt
with gcc.bazel.release.server_only
— build Envoy static binary under-c opt
with gcc.bazel.coverage
— build and run tests under-c dbg
with gcc, generating coverage information in$ENVOY_DOCKER_BUILD_DIR/envoy/generated/coverage/coverage.html
.bazel.coverity
— build Envoy static binary and run Coverity Scan static analysis.bazel.tsan
— build and run tests under-c dbg --config=clang-tsan
with clang.bazel.compile_time_options
— build Envoy and test with various compile-time options toggled to their non-default state, to ensure they still build.bazel.clang_tidy
— build and run clang-tidy over all source files.check_format
— runclang-format-6.0
andbuildifier
on entire source tree.fix_format
— run and enforceclang-format-6.0
andbuildifier
on entire source tree.check_spelling
— runmisspell
on entire project.fix_spelling
— run and enforcemisspell
on entire project.check_spelling_pedantic
— runaspell
on C++ and proto comments.docs
— build documentation tree ingenerated/docs
.
While all changes to the build image should eventually be upstreamed, it can be useful to test those changes locally before sending out a pull request. To experiment with a local clone of the upstream build image you can make changes to files such as build_container.sh locally and then run:
DISTRO=ubuntu
cd ci/build_container
LINUX_DISTRO="${DISTRO}" CIRCLE_SHA1=my_tag ./docker_build.sh # Wait patiently for quite some time
cd ../..
IMAGE_NAME="envoyproxy/envoy-build-${DISTRO}" IMAGE_ID=my_tag ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.whatever'
This build the Ubuntu based envoyproxy/envoy-build-ubuntu
image, and the final call will run against your local copy of the build image.
The macOS CI build is part of the CircleCI workflow.
Dependencies are installed by the ci/mac_ci_setup.sh
script, via Homebrew,
which is pre-installed on the CircleCI macOS image. The dependencies are cached are re-installed
on every build. The ci/mac_ci_steps.sh
script executes the specific commands that
build and test Envoy.
Coverity Scan static analysis is not run within Envoy CI. However, Envoy can be locally built and
submitted for analysis. A Coverity Scan Envoy project token must be generated from the
Coverity Project Settings.
Only a Coverity Project Administrator can create a token. With this token, running
ci/do_coverity_local.sh
will use the Ubuntu based envoyproxy/envoy-build-ubuntu
image to build the
Envoy static binary with the Coverity Scan tool chain. This process generates an artifact,
envoy-coverity-output.tgz, that is uploaded to Coverity for static analysis.
To build and submit for analysis:
COVERITY_TOKEN={generated Coverity project token} ./ci/do_coverity_local.sh