Skip to content

Add basic documentation for xDS integration #6724

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jrhee17 wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Add basic documentation for xDS integration #6724

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f156795
add documentation
jrhee17 Apr 15, 2026
64bb6c2
fix
jrhee17 Apr 15, 2026
3c15a66
fixes
jrhee17 Apr 15, 2026
aa1b278
lceanup
jrhee17 Apr 15, 2026
b4d466e
compile failure
jrhee17 Apr 15, 2026
9276a1e
address comment by @ikhoon
jrhee17 Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 0 additions & 94 deletions it/xds-client/src/main/java/com/linecorp/armeria/xds/it/XdsResourceReader.java
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion .../src/test/java/com/linecorp/armeria/xds/client/endpoint/TransportSocketMatchUtilTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
import com.linecorp.armeria.xds.TransportSocketMatchSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.it.XdsResourceReader;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.envoy.config.bootstrap.v3.Bootstrap;
import io.envoyproxy.envoy.config.endpoint.v3.ClusterLoadAssignment;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/BootstrapSecretsTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
import com.linecorp.armeria.xds.TlsCertificateSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.envoy.config.bootstrap.v3.Bootstrap;

Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/BootstrapTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import com.linecorp.armeria.xds.ClusterSnapshot;
import com.linecorp.armeria.xds.SnapshotWatcher;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand Down
1 change: 1 addition & 0 deletions ...ds-client/src/test/java/com/linecorp/armeria/xds/it/CertificateValidationContextTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand Down
1 change: 1 addition & 0 deletions ...s-client/src/test/java/com/linecorp/armeria/xds/it/ConfigSourceLifecycleObserverTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
import com.linecorp.armeria.testing.junit5.server.ServerExtension;
import com.linecorp.armeria.xds.ListenerRoot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.XdsType;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/ControlPlaneTlsIntegrationTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
import com.linecorp.armeria.xds.ListenerRoot;
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
10 changes: 8 additions & 2 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/DataSourceTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
import com.linecorp.armeria.xds.TlsCertificateSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand All @@ -51,6 +52,11 @@

class DataSourceTest {

private static String escapeMultiLine(String str) {
return str.replace("\\", "\\\\").replace("\"", "\\\"")
.replace("\n", "\\n").replace("\r", "\\r");
}

private static final String GROUP = "key";
private static final SimpleCache<String> cache = new SimpleCache<>(node -> GROUP);
private static final AtomicLong version = new AtomicLong();
Expand Down Expand Up @@ -842,8 +848,8 @@ void tlsCertificateWithInlineString() throws Exception {
inline_string: "%s"
certificate_chain:
inline_string: "%s"
""".formatted(XdsResourceReader.escapeMultiLine(privateKeyContent),
XdsResourceReader.escapeMultiLine(certContent));
""".formatted(escapeMultiLine(privateKeyContent),
escapeMultiLine(certContent));
final Secret secret = XdsResourceReader.fromYaml(tlsCertYaml, Secret.class);
version.incrementAndGet();
cache.setSnapshot(GROUP, Snapshot.create(ImmutableList.of(), ImmutableList.of(), ImmutableList.of(),
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/DynamicSecretTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
import com.linecorp.armeria.xds.TransportSocketMatchSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/ErrorHandlingTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
import com.linecorp.armeria.xds.SnapshotWatcher;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceException;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.XdsType;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/HealthCheckedTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.SnapshotWatcher;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsLoadBalancer;

import io.envoyproxy.envoy.config.bootstrap.v3.Bootstrap;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/LoadBalancerReloadTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.SnapshotWatcher;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsLoadBalancer;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/PreprocessorErrorTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import com.linecorp.armeria.common.TimeoutException;
import com.linecorp.armeria.internal.client.DefaultClientRequestContext;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class PreprocessorErrorTest {
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/ResourceNodeMetricTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
import com.linecorp.armeria.xds.ClusterRoot;
import com.linecorp.armeria.xds.ListenerRoot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/RetryTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@
import com.linecorp.armeria.common.RequestHeaders;
import com.linecorp.armeria.common.ResponseHeaders;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class RetryTest {
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/RouteMatcherTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
import com.linecorp.armeria.common.HttpRequest;
import com.linecorp.armeria.common.RequestHeaders;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class RouteMatcherTest {
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/TimeoutTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
import com.linecorp.armeria.common.HttpRequest;
import com.linecorp.armeria.common.HttpResponse;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class TimeoutTest {
Expand Down
1 change: 1 addition & 0 deletions ...-client/src/test/java/com/linecorp/armeria/xds/it/TlsPeerVerificationIntegrationTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class TlsPeerVerificationIntegrationTest {
Expand Down
1 change: 1 addition & 0 deletions ...ent/src/test/java/com/linecorp/armeria/xds/it/TlsValidationContextSdsIntegrationTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
import com.linecorp.armeria.xds.ListenerRoot;
import com.linecorp.armeria.xds.ListenerSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
1 change: 1 addition & 0 deletions ...ient/src/test/java/com/linecorp/armeria/xds/it/TransportSocketMatchesIntegrationTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import com.linecorp.armeria.testing.junit5.server.SelfSignedCertificateExtension;
import com.linecorp.armeria.testing.junit5.server.ServerExtension;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class TransportSocketMatchesIntegrationTest {
Expand Down
7 changes: 6 additions & 1 deletion it/xds-client/src/test/java/com/linecorp/armeria/xds/it/TransportSocketSnapshotTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@

package com.linecorp.armeria.xds.it;

import static com.linecorp.armeria.xds.it.XdsResourceReader.escapeMultiLine;
import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;

Expand Down Expand Up @@ -48,11 +47,17 @@
import com.linecorp.armeria.xds.TlsCertificateSnapshot;
import com.linecorp.armeria.xds.TransportSocketSnapshot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.envoy.config.bootstrap.v3.Bootstrap;

class TransportSocketSnapshotTest {

private static String escapeMultiLine(String str) {
return str.replace("\\", "\\\\").replace("\"", "\\\"")
.replace("\n", "\\n").replace("\r", "\\r");
}

@RegisterExtension
static SelfSignedCertificateExtension certificate = new SelfSignedCertificateExtension();

Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/VirtualHostRoutingTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
import com.linecorp.armeria.common.RequestHeaders;
import com.linecorp.armeria.common.annotation.Nullable;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

class VirtualHostRoutingTest {
Expand Down
1 change: 1 addition & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/XdsEndpointGroupTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
import com.linecorp.armeria.testing.junit5.server.SelfSignedCertificateExtension;
import com.linecorp.armeria.testing.junit5.server.ServerExtension;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsEndpointGroup;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down
1 change: 1 addition & 0 deletions ...lient/src/test/java/com/linecorp/armeria/xds/it/XdsLoadBalancerLifecycleObserverTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
import com.linecorp.armeria.testing.junit5.server.ServerExtension;
import com.linecorp.armeria.xds.ListenerRoot;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
import io.envoyproxy.controlplane.cache.v3.Snapshot;
Expand Down
17 changes: 17 additions & 0 deletions it/xds-client/src/test/java/com/linecorp/armeria/xds/it/XdsPreprocessorTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
import com.linecorp.armeria.testing.junit5.server.SelfSignedCertificateExtension;
import com.linecorp.armeria.testing.junit5.server.ServerExtension;
import com.linecorp.armeria.xds.XdsBootstrap;
import com.linecorp.armeria.xds.XdsResourceReader;
import com.linecorp.armeria.xds.client.endpoint.XdsHttpPreprocessor;

import io.envoyproxy.controlplane.cache.v3.SimpleCache;
Expand Down Expand Up @@ -147,6 +148,22 @@ void testWithListener() {
}
}

@Test
void whenReady() {
final Bootstrap bootstrap =
bootstrapYaml(BOOTSTRAP_CLUSTER_NAME,
server.httpSocketAddress().getHostString(),
server.httpPort(),
null);
try (XdsBootstrap xdsBootstrap = XdsBootstrap.of(bootstrap, eventLoop.get());
XdsHttpPreprocessor xdsPreprocessor =
XdsHttpPreprocessor.ofListener(LISTENER_NAME, xdsBootstrap)) {
xdsPreprocessor.whenReady().join();
final BlockingWebClient blockingClient = WebClient.of(xdsPreprocessor).blocking();
assertThat(blockingClient.get("/hello").contentUtf8()).isEqualTo("world");
}
}

@Test
void testAllHttps() {
final Bootstrap bootstrap =
Expand Down
17 changes: 17 additions & 0 deletions site-new/sidebars.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,23 @@ const sidebars: SidebarsConfig = {
title: 'Advanced',
},
items: [
{
type: 'category',
label: 'xDS',
link: {
type: 'generated-index',
title: 'xDS',
},
items: [
'advanced/xds/introduction',
'advanced/xds/getting-started',
'advanced/xds/concepts',
'advanced/xds/metrics',
'advanced/xds/extensions',
'advanced/xds/supported-features',
'advanced/xds/running-with-istio',
],
},
Comment thread
coderabbitai[bot] marked this conversation as resolved.
'advanced/logging',
'advanced/structured-logging',
'advanced/request-context',
Expand Down
Loading
Loading