Add Envoy service mesh example

[eottabom]

Follow up on #8772, where a mesh style Envoy example was suggested.

Envoy behaviour comes almost entirely from configuration that a control plane delivers, which makes it awkward to try out locally. This example brings both parts up in a test:

test (client app) -> client-sidecar :15001 -> server-sidecar :15006 -> server-app :8080
                            ^                        ^
                            +------ xDS (ADS) -------+
                             control plane in test JVM

The client sidecar adds a caller header, retries 5xx twice and applies a 1s timeout. The server sidecar authorizes the caller with the RBAC filter. Both boot with a bootstrap file that only points at the control plane, which runs in the test JVM on envoyproxy/java-control-plane and is reached through Testcontainers.exposeHostPorts. Listener and cluster configuration lives in JSON resources under src/test/resources/xds.

The four tests demonstrate the setup rather than test Envoy itself: a request travelling through both sidecars, a policy update pushed to a running sidecar, retries, and a timeout. The echo application can be told to fail or to respond slowly with a request header, so no extra fault injection configuration is needed.

Note that the caller identity is a plain header, not a substitute for mutual TLS, and that only the sidecar case is covered, not Envoy at the edge.

Summary by CodeRabbit

• New Features
  • Added an Envoy integration example demonstrating service-to-service communication with Testcontainers.
  • Demonstrates traffic routing, access control, retries, request timeouts, and dynamic configuration updates.
  • Added the Envoy example to the project’s examples documentation.
  • Added Gradle configuration for running the example with JUnit 5.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: c41f4b77-1513-4ad1-aa49-04e799c8d6a8

📥 Commits

Reviewing files that changed from the base of the PR and between 8e54951 and c49aa8a.

📒 Files selected for processing (11)

• docs/examples.md
• examples/envoy/build.gradle
• examples/envoy/src/test/java/com/example/EnvoyContainerTest.java
• examples/envoy/src/test/java/com/example/XdsControlPlane.java
• examples/envoy/src/test/resources/bootstrap.yaml
• examples/envoy/src/test/resources/logback-test.xml
• examples/envoy/src/test/resources/xds/client-sidecar-cluster.json
• examples/envoy/src/test/resources/xds/client-sidecar-listener.json
• examples/envoy/src/test/resources/xds/server-sidecar-cluster.json
• examples/envoy/src/test/resources/xds/server-sidecar-listener.json
• examples/settings.gradle

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds a Gradle Envoy example with an xDS control plane, two Envoy sidecars, a server container, bootstrap and xDS resources, and JUnit tests for routing, authorization, retries, and timeouts.

Changes

Envoy example

Layer / File(s)	Summary
Project registration examples/settings.gradle, examples/envoy/build.gradle, docs/examples.md	Registers the Envoy example, adds its test dependencies and JUnit Platform configuration, and links the example from the documentation.
xDS control plane and resources examples/envoy/src/test/java/com/example/XdsControlPlane.java, examples/envoy/src/test/resources/bootstrap.yaml, examples/envoy/src/test/resources/logback-test.xml, examples/envoy/src/test/resources/xds/*	Adds the gRPC xDS control plane and the bootstrap, listener, and cluster resources for client-sidecar routing and server-sidecar authorization.
Sidecar topology setup examples/envoy/src/test/java/com/example/EnvoyContainerTest.java	Creates the server application and Envoy sidecars, connects them to a shared network, publishes snapshots, and manages test lifecycle hooks.
Traffic behavior validation examples/envoy/src/test/java/com/example/EnvoyContainerTest.java	Tests successful routing, dynamic caller authorization, retry counts, timeout responses, and HTTP request helpers.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant EnvoyContainerTest
  participant clientSidecar
  participant serverSidecar
  participant serverApp
  EnvoyContainerTest->>clientSidecar: Send request to outbound port
  clientSidecar->>serverSidecar: Route request and add x-service-caller
  serverSidecar->>serverApp: Forward authorized request
  serverApp-->>EnvoyContainerTest: Return response

Loading

Suggested reviewers: eddumelendez

Merge Risk: ⚪ Minimal · up to c49aa

The new Envoy example’s declared dependencies and sidecar configuration are consistent with its test topology, with no remaining actionable merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 2 files. (9 skipped: 9…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding an Envoy service mesh example.
Description check	✅ Passed	The description explains the context, architecture, demonstrated behaviors, implementation approach, scope, and related issue #8772. It satisfies the repository template requirements.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 2 files. (9 skipped: 9 unsupported.)

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}