envoy-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# Envoy Development

## Lightweight Envoy Build

Build minimal Envoy (~25 extensions vs ~334 full) for fast compilation.
Covers HTTP/HTTPS reverse proxy with TLS, filesystem SDS, health checking, DNS, load balancing. HTTP/3 disabled.

### Setup

Verified against Envoy `main` (1.40.0-dev, bzlmod, Bazel 8.8.0, hermetic LLVM 22.1.8) on
Ubuntu 24.04. See "Pre-bzlmod branches" below for release branches such as v1.38.x.

#### 1. No toolchain patch needed

Do **not** patch `bazel/toolchains.bzl`. On main that file no longer defines a version —
it re-exports from `@llvm_toolchain_llvm//:llvm.bzl`. The hermetic LLVM version lives in
`bazel/extensions.bzl` (`_LLVM_VERSION`) and `MODULE.bazel`, and is used by default.

#### 2. `user.bazelrc`

```
build --disk_cache=~/.cache/envoy-bazel
build --experimental_disk_cache_gc_max_size=20G
build --experimental_disk_cache_gc_max_age=14d
build --local_resources=cpu=HOST_CPUS*0.3
build --local_resources=memory=HOST_RAM*0.3
build --copt=-Wno-nullability-completeness

# Must be `common`, not `build`: otherwise query/cquery ignore the override and
# silently analyse the FULL extension set.
common --override_repository=+envoy_build_config_ext+envoy_build_config=%workspace%/envoy_lightweight_build_config

build --//bazel:http3=False
```

Three things that are easy to get wrong:

- **No `--config=clang`.** That config no longer exists in `.bazelrc` on main; it fails with
  `Config value 'clang' is not defined in any .rc file`. Check with
  `bazel canonicalize-flags --config=clang -- --compilation_mode=fastbuild`.
- **The override repo name must be canonical.** `envoy_build_config` is created by the
  `envoy_build_config_ext` module extension, so plain
  `--override_repository=envoy_build_config=...` is *silently ignored* and you get a full
  ~334-extension build. The canonical name is `+envoy_build_config_ext+envoy_build_config`.
  This is documented in `bazel/README.md` → "Customize extension build config".
- **Keep resource limits at 0.3.** Envoy compiles are memory-hungry; raising these pushes the
  machine into swap. 0.3 of 20 CPUs ≈ 6 concurrent actions, visible as
  `(N actions, 6 running)` in the build output.

Verify the override actually took effect before starting a long build:

```bash
OB=$(bazel info output_base)
ls -l "$OB/external/+envoy_build_config_ext+envoy_build_config/extensions_build_config.bzl"
```

A **symlink into `source/extensions/`** means the override was ignored (full build).
A **regular file** matching your lightweight copy means it worked.

#### 3. `envoy_lightweight_build_config/`

Directory in repo root. Overrides the `@envoy_build_config` Bazel repository to control which extensions are compiled.

Files:

- `MODULE.bazel` — empty (required under bzlmod for `--override_repository` to accept the dir)
- `BUILD` — empty (required by Bazel)
- `WORKSPACE` — empty (harmless; only needed for pre-bzlmod branches)
- `extensions_build_config.bzl` — content below:

```python
EXTENSIONS = {
    "envoy.access_loggers.file": "//source/extensions/access_loggers/file:config",
    "envoy.access_loggers.stdout": "//source/extensions/access_loggers/stream:config",
    "envoy.clusters.static": "//source/extensions/clusters/static:static_cluster_lib",
    "envoy.clusters.strict_dns": "//source/extensions/clusters/strict_dns:strict_dns_cluster_lib",
    "envoy.clusters.logical_dns": "//source/extensions/clusters/logical_dns:logical_dns_cluster_lib",
    "envoy.clusters.dns": "//source/extensions/clusters/dns:dns_cluster_lib",
    "envoy.network.dns_resolver.cares": "//source/extensions/network/dns_resolver/cares:config",
    "envoy.config_subscription.filesystem": "//source/extensions/config_subscription/filesystem:filesystem_subscription_lib",
    "envoy.filters.http.router": "//source/extensions/filters/http/router:config",
    "envoy.filters.http.health_check": "//source/extensions/filters/http/health_check:config",
    "envoy.filters.http.buffer": "//source/extensions/filters/http/buffer:config",
    "envoy.filters.network.http_connection_manager": "//source/extensions/filters/network/http_connection_manager:config",
    "envoy.filters.network.tcp_proxy": "//source/extensions/filters/network/tcp_proxy:config",
    "envoy.filters.listener.original_dst": "//source/extensions/filters/listener/original_dst:config",
    "envoy.filters.listener.tls_inspector": "//source/extensions/filters/listener/tls_inspector:config",
    "envoy.filters.listener.http_inspector": "//source/extensions/filters/listener/http_inspector:config",
    "envoy.transport_sockets.raw_buffer": "//source/extensions/transport_sockets/raw_buffer:config",
    "envoy.transport_sockets.tls": "//source/extensions/transport_sockets/tls:config",
    "envoy.load_balancing_policies.round_robin": "//source/extensions/load_balancing_policies/round_robin:config",
    "envoy.load_balancing_policies.least_request": "//source/extensions/load_balancing_policies/least_request:config",
    "envoy.health_checkers.http": "//source/extensions/health_checkers/http:health_checker_lib",
    "envoy.health_checkers.tcp": "//source/extensions/health_checkers/tcp:health_checker_lib",
    "envoy.upstreams.http.http_protocol_options": "//source/extensions/upstreams/http/http:config",
    "envoy.upstreams.http.tcp": "//source/extensions/upstreams/tcp/generic:config",
    "envoy.upstreams.tcp.generic": "//source/extensions/upstreams/tcp/generic:config",
    "envoy.request_id.uuid": "//source/extensions/request_id/uuid:config",
    "envoy.retry_priorities.previous_priorities": "//source/extensions/retry/priority/previous_priorities:config",
    "envoy.retry_host_predicates.previous_hosts": "//source/extensions/retry/host/previous_hosts:config",
}

EXTENSION_CONFIG_VISIBILITY = ["//:extension_config", "//:contrib_library", "//:mobile_library"]
EXTENSION_PACKAGE_VISIBILITY = ["//:extension_library", "//:contrib_library", "//:mobile_library"]
CONTRIB_EXTENSION_PACKAGE_VISIBILITY = ["//:contrib_library"]
MOBILE_PACKAGE_VISIBILITY = ["//:mobile_library"]
LEGACY_ALWAYSLINK = 1
```

### Build

```bash
bazel build -c fastbuild //source/exe:envoy-static
```

Binary at `bazel-bin/source/exe/envoy-static`.

Expect roughly **7.7k actions** for the lightweight set (a full build is 30k+). From a warm
disk cache that is ~15 min at `cpu=HOST_CPUS*0.3`; from cold, closer to an hour.

From tsaarni/agent-skills, Apache-2.0.

More from tsaarni/agent-skills