Migrate xDS resource services from gRPC to YAML-over-HTTP annotated services (#1337)

Motivation:

The xDS resource management APIs (cluster, endpoint, listener, route, group, kubernetes) were implemented as gRPC services backed by service-specific `.proto` files. Migrating them to Armeria annotated HTTP services that consume `application/yaml` removes the protobuf service layer, simplifies the API surface, and makes the YAML-native storage format a first-class concern — clients send YAML directly and it is stored as-is (with `name`/`clusterName` injected).

Modifications:

- Convert `XdsClusterService`, `XdsEndpointService`, `XdsListenerService`, `XdsRouteService` from `*ImplBase` gRPC stubs to plain annotated HTTP services (`@Post`/`@Put`/`@Delete`, `@Consumes("application/yaml")`).
- Add `RequiresXdsGroupRole` annotation and `RequiresXdsGroupRoleDecorator` to replace the inline `checkWritePermission` calls with a declarative, per-method authorization mechanism.
- Refactor `XdsResourceManager` so that `push`/`update`/`delete` operate on raw YAML strings instead of protobuf messages, and add helpers `parseYaml`, `normalizeYamlKeys`, `injectYamlField`, and `errorResponse`.

Result:

- xDS resource CRUD is now served via plain HTTP with YAML bodies, removing the gRPC service layer and the associated proto wrapper definitions.

Author: minwoox

it/xds-k8s-node-ip-extractor/src/test/java/com/linecorp/centraldogma/it/xds/k8s/XdsKubernetesNodeIpExtractorTest.java

@@ -43,6 +43,8 @@
 import com.linecorp.centraldogma.common.Entry;
 import com.linecorp.centraldogma.common.Query;
 import com.linecorp.centraldogma.common.Revision;
+import com.linecorp.centraldogma.internal.Jackson;
+import com.linecorp.centraldogma.internal.Yaml;
 import com.linecorp.centraldogma.server.storage.repository.Repository;
 import com.linecorp.centraldogma.testing.junit.CentralDogmaExtension;
 import com.linecorp.centraldogma.xds.internal.XdsResourceManager;
@@ -147,7 +149,6 @@ void extractsNodeIpFromLabel() throws Exception {
 
         final AggregatedHttpResponse response = createAggregator(aggregator, aggregatorId);
         assertThat(response.status()).isSameAs(HttpStatus.OK);
-        assertThat(response.headers().get("grpc-status")).isEqualTo("0");
 
         final Repository fooGroup = dogma.projectManager().get(INTERNAL_PROJECT_XDS)
                                          .repos().get("foo");
@@ -223,7 +224,6 @@ void fallsBackToInternalIpWhenLabelKeyIsAbsent() throws Exception {
 
         final AggregatedHttpResponse response = createAggregator(aggregator, aggregatorId);
         assertThat(response.status()).isSameAs(HttpStatus.OK);
-        assertThat(response.headers().get("grpc-status")).isEqualTo("0");
 
         final Repository fooGroup = dogma.projectManager().get(INTERNAL_PROJECT_XDS)
                                          .repos().get("foo");
@@ -315,11 +315,12 @@ private static AggregatedHttpResponse createAggregator(
                 RequestHeaders.builder(HttpMethod.POST,
                                        "/api/v1/xds/groups/foo/k8s/endpointAggregators?" +
                                        "aggregator_id=" + aggregatorId)
-                              .contentType(MediaType.JSON_UTF_8)
+                              .contentType(MediaType.parse("application/yaml"))
                               .set(HttpHeaderNames.AUTHORIZATION, "Bearer anonymous")
                               .build();
-        return dogma.httpClient().blocking().execute(
-                headers, XdsResourceManager.JSON_MESSAGE_MARSHALLER.writeValueAsString(aggregator));
+        final String yaml = Yaml.writeValueAsString(
+                Jackson.readTree(XdsResourceManager.JSON_MESSAGE_MARSHALLER.writeValueAsString(aggregator)));
+        return dogma.httpClient().blocking().execute(headers, yaml);
     }
 
     private static Node newNodeWithLabel(String internalIp, String labelKey, String labelValue) {

webapp/src/dogma/features/xds/XdsTypes.ts

@@ -125,7 +125,6 @@ export const XDS_RESOURCE_TEMPLATES: Record<XdsResourceType, string> = {
           },
         },
       ],
-      respectDnsTtl: true,
     },
     null,
     2,

xds/src/main/java/com/linecorp/centraldogma/xds/cluster/v1/XdsClusterService.java

@@ -20,24 +20,30 @@
 import static com.linecorp.centraldogma.xds.internal.ControlPlaneService.CLUSTERS_DIRECTORY;
 import static com.linecorp.centraldogma.xds.internal.XdsResourceManager.LEGACY_RESOURCE_ID_PATTERN_STRING;
 import static com.linecorp.centraldogma.xds.internal.XdsResourceManager.RESOURCE_ID_PATTERN;
-import static com.linecorp.centraldogma.xds.internal.XdsResourceManager.removePrefix;
 
-import java.util.regex.Matcher;
+import java.io.IOException;
+import java.util.concurrent.CompletableFuture;
 import java.util.regex.Pattern;
 
-import com.google.protobuf.Empty;
+import org.jspecify.annotations.Nullable;
 
-import com.linecorp.centraldogma.xds.cluster.v1.XdsClusterServiceGrpc.XdsClusterServiceImplBase;
+import com.linecorp.armeria.common.HttpResponse;
+import com.linecorp.armeria.common.HttpStatus;
+import com.linecorp.armeria.server.annotation.Consumes;
+import com.linecorp.armeria.server.annotation.Delete;
+import com.linecorp.armeria.server.annotation.Param;
+import com.linecorp.armeria.server.annotation.Post;
+import com.linecorp.armeria.server.annotation.Put;
+import com.linecorp.centraldogma.common.RepositoryRole;
+import com.linecorp.centraldogma.xds.internal.RequiresXdsGroupRole;
 import com.linecorp.centraldogma.xds.internal.XdsResourceManager;
 
 import io.envoyproxy.envoy.config.cluster.v3.Cluster;
-import io.grpc.Status;
-import io.grpc.stub.StreamObserver;
 
 /**
- * Service for managing clusters.
+ * Annotated service object for managing clusters.
  */
-public final class XdsClusterService extends XdsClusterServiceImplBase {
+public final class XdsClusterService {
 
     private static final Pattern CLUSTER_NAME_PATTERN =
             Pattern.compile("^groups/([^/]+)/clusters/" + LEGACY_RESOURCE_ID_PATTERN_STRING + '$');
@@ -51,69 +57,91 @@ public XdsClusterService(XdsResourceManager xdsResourceManager) {
         this.xdsResourceManager = xdsResourceManager;
     }
 
-    @Override
-    public void createCluster(CreateClusterRequest request, StreamObserver<Cluster> responseObserver) {
-        final String parent = request.getParent();
-        final String group = removePrefix("groups/", parent);
-        xdsResourceManager.checkWritePermission(group);
-
-        final String clusterId = request.getClusterId();
+    /**
+     * POST /xds/groups/{group}/clusters
+     *
+     * <p>Creates a new cluster.
+     */
+    @Post("/xds/groups/{group}/clusters")
+    @Consumes("application/yaml")
+    @RequiresXdsGroupRole(RepositoryRole.WRITE)
+    public CompletableFuture<HttpResponse> createCluster(
+            @Param("group") String group,
+            @Param("cluster_id") String clusterId,
+            @Param("summary") @Nullable String summary,
+            String body) {
         if (!RESOURCE_ID_PATTERN.matcher(clusterId).matches()) {
-            throw Status.INVALID_ARGUMENT.withDescription("Invalid cluster_id: " + clusterId +
-                                                          " (expected: " + RESOURCE_ID_PATTERN + ')')
-                                         .asRuntimeException();
+            return CompletableFuture.completedFuture(
+                    XdsResourceManager.errorResponse(HttpStatus.BAD_REQUEST,
+                                                     "Invalid cluster ID: " + clusterId));
         }
-
-        final String clusterName = parent + CLUSTERS_DIRECTORY + clusterId;
-        final Cluster cluster
-                = request.getCluster()
-                         .toBuilder()
-                         // Ignore the specified name in the cluster and set the name with the format of
-                         // "groups/{group}/clusters/{cluster}".
-                         // https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0133.md#user-specified-ids
-                         .setName(clusterName)
-                         // Respect the DNS TTL would be more efficient in terms of DNS resolution.
-                         // https://github.com/envoyproxy/envoy/issues/6876
-                         // `respect_dns_ttl` is a `bool` field so it is not possible to check whether a value
-                         // has not been set for the field. Until we create our own proto file, the value only
-                         // can be set to false via the update API.
-                         .setRespectDnsTtl(true)
-                         .build();
-        final String createSummary = isNullOrEmpty(request.getSummary()) ?
-                                     "Create cluster: " + clusterName : request.getSummary();
-        xdsResourceManager.push(responseObserver, group, clusterName, CLUSTERS_DIRECTORY + clusterId + ".yaml",
-                                createSummary, cluster, currentAuthor(), true);
+        final String clusterName = clusterName(group, clusterId);
+        try {
+            XdsResourceManager.parseYaml(body, Cluster.newBuilder());
+        } catch (IOException e) {
+            return CompletableFuture.completedFuture(
+                    XdsResourceManager.errorResponse(HttpStatus.BAD_REQUEST,
+                                                     "Invalid request body: " + e.getMessage()));
+        }
+        final String createSummary = isNullOrEmpty(summary) ? "Create cluster: " + clusterName : summary;
+        final String bodyToStore = XdsResourceManager.injectYamlField(body, "name", clusterName);
+        return xdsResourceManager.push(group, clusterName, CLUSTERS_DIRECTORY + clusterId + ".yaml",
+                                       createSummary, currentAuthor(), true, bodyToStore);
     }
 
-    @Override
-    public void updateCluster(UpdateClusterRequest request, StreamObserver<Cluster> responseObserver) {
-        final Cluster cluster = request.getCluster();
-        final String clusterName = cluster.getName();
-        final String group = checkClusterName(clusterName).group(1);
-        xdsResourceManager.checkWritePermission(group);
-        final String updateSummary = isNullOrEmpty(request.getSummary()) ?
-                                     "Update cluster: " + clusterName : request.getSummary();
-        xdsResourceManager.update(responseObserver, group, clusterName,
-                                  updateSummary, cluster, currentAuthor());
+    /**
+     * PUT /xds/groups/{group}/clusters/{cluster_id}
+     *
+     * <p>Updates an existing cluster.
+     */
+    @Put("/xds/groups/{group}/clusters/{*cluster_id}")
+    @Consumes("application/yaml")
+    @RequiresXdsGroupRole(RepositoryRole.WRITE)
+    public CompletableFuture<HttpResponse> updateCluster(
+            @Param("group") String group,
+            @Param("cluster_id") String clusterId,
+            @Param("summary") @Nullable String summary,
+            String body) {
+        final String clusterName = clusterName(group, clusterId);
+        if (!CLUSTER_NAME_PATTERN.matcher(clusterName).matches()) {
+            return CompletableFuture.completedFuture(
+                    XdsResourceManager.errorResponse(HttpStatus.BAD_REQUEST,
+                                                     "Invalid cluster name: " + clusterName));
+        }
+        try {
+            XdsResourceManager.parseYaml(body, Cluster.newBuilder());
+        } catch (IOException e) {
+            return CompletableFuture.completedFuture(
+                    XdsResourceManager.errorResponse(HttpStatus.BAD_REQUEST,
+                                                     "Invalid request body: " + e.getMessage()));
+        }
+        final String updateSummary = isNullOrEmpty(summary) ? "Update cluster: " + clusterName : summary;
+        final String bodyToStore = XdsResourceManager.injectYamlField(body, "name", clusterName);
+        return xdsResourceManager.update(group, clusterName, updateSummary, currentAuthor(), bodyToStore);
     }
 
-    @Override
-    public void deleteCluster(DeleteClusterRequest request, StreamObserver<Empty> responseObserver) {
-        final String clusterName = request.getName();
-        final String group = checkClusterName(clusterName).group(1);
-        xdsResourceManager.checkWritePermission(group);
-        final String deleteSummary = isNullOrEmpty(request.getSummary()) ?
-                                     "Delete cluster: " + clusterName : request.getSummary();
-        xdsResourceManager.delete(responseObserver, group, clusterName, deleteSummary, currentAuthor());
+    /**
+     * DELETE /xds/groups/{group}/clusters/{cluster_id}
+     *
+     * <p>Removes a cluster.
+     */
+    @Delete("/xds/groups/{group}/clusters/{*cluster_id}")
+    @RequiresXdsGroupRole(RepositoryRole.WRITE)
+    public CompletableFuture<HttpResponse> deleteCluster(
+            @Param("group") String group,
+            @Param("cluster_id") String clusterId,
+            @Param("summary") @Nullable String summary) {
+        final String clusterName = clusterName(group, clusterId);
+        if (!CLUSTER_NAME_PATTERN.matcher(clusterName).matches()) {
+            return CompletableFuture.completedFuture(
+                    XdsResourceManager.errorResponse(HttpStatus.BAD_REQUEST,
+                                                     "Invalid cluster name: " + clusterName));
+        }
+        final String deleteSummary = isNullOrEmpty(summary) ? "Delete cluster: " + clusterName : summary;
+        return xdsResourceManager.delete(group, clusterName, deleteSummary, currentAuthor());
     }
 
-    private static Matcher checkClusterName(String clusterName) {
-        final Matcher matcher = CLUSTER_NAME_PATTERN.matcher(clusterName);
-        if (!matcher.matches()) {
-            throw Status.INVALID_ARGUMENT.withDescription("Invalid cluster name: " + clusterName +
-                                                          " (expected: " + CLUSTER_NAME_PATTERN + ')')
-                                         .asRuntimeException();
-        }
-        return matcher;
+    private static String clusterName(String group, String clusterId) {
+        return "groups/" + group + CLUSTERS_DIRECTORY + clusterId;
     }
 }