envoyproxy/envoy

Native multi-file YAML config support like Nginx `include` directive

Open

#43511 opened on Feb 16, 2026

View on GitHub
 (2 comments) (0 reactions) (0 assignees)C++ (27,997 stars) (5,373 forks)batch import
enhancementhelp wanted

Description

Feature Request Summary

Add native support for splitting Envoy bootstrap configuration across multiple YAML files, similar to Nginx's include directive and /etc/nginx/conf.d/*.conf directory scanning.

Motivation

Unlike Nginx, which seamlessly loads multiple config files from a directory into a unified config tree, Envoy requires a single bootstrap YAML file. Current workarounds like !ignore YAML fragments with anchors/aliases work but have limitations:

  • Still requires a "main" bootstrap file
  • Manual anchor management across files
  • No automatic directory scanning
  • Full reload needed for fragment changes
  • Not as intuitive for teams familiar with Nginx/HAProxy

This is especially painful for complex deployments (Kubernetes sidecars, Docker Compose with multiple services) where configs grow large and need modularization.

Contributor guide

Tech stack
cpp
Domain
backenddevops
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Envoy bootstrap configC++YAML parsingFile system operations
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
15
Research direction
Examine the existing bootstrap configuration loading mechanism in Envoy, particularly the YAML parsing and validation code in source/server/config * files. Look at how the main configuration file is read (e.g., ConfigImpl::loadBootstrapConfig) and consider how to extend it to support multiple files via an include directive. Refer to Nginx's include implementation for inspiration. Engage with maintainers in the issue comments to clarify desired API, syntax, and constraints such as override semantics and directory scanning.