WIP - management interface

docs/src/main/asciidoc/http-reference.adoc

@@ -261,7 +261,7 @@ include::{generated-dir}/config/quarkus-vertx-http-config-group-filter-config.ad
 == Support 100-Continue in vert.x
 
 In order to support `100-continue`, the `quarkus.http.handle-100-continue-automatically` option needs to be enabled explicitly
-For additional information check https://datatracker.ietf.org/doc/html/rfc7231#section-5.1.1[100-continue= and the related
+For additional information check https://datatracker.ietf.org/doc/html/rfc7231#section-5.1.1[100-continue] and the related
 https://vertx.io/docs/apidocs/io/vertx/core/http/HttpServerOptions.html#DEFAULT_HANDLE_100_CONTINE_AUTOMATICALLY[Vert.x documentation].
 
 [source,properties]

docs/src/main/asciidoc/management-interface-reference.adoc

@@ -0,0 +1,162 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= HTTP Reference
+include::_attributes.adoc[]
+:categories: observability
+:summary: Learn how you can use a separated management interface
+:numbered:
+:sectnums:
+:sectnumlevels: 4
+
+:numbered:
+:sectnums:
+:sectnumlevels: 4
+
+
+By default, Quarkus exposes the _management_ endpoints under `/q` on the main HTTP server.
+The same HTTP server provides the application endpoints and the management endpoints.
+
+This document presents how you can use a separate HTTP server (bound to a different network interface and port) for the management endpoints.
+It avoids exposing these endpoints on the main server and, thus, prevents undesired accesses.
+
+== Enabling the management interface
+
+To enable the management interface, use the following **build-time** property:
+
+[source, properties]
+----
+quarkus.management.enabled=true
+----
+
+Management endpoints will be exposed on: `http://0.0.0.0:8999/q`.
+For example, `http://0.0.0.0:8998/q/health/ready` for the readiness probe.
+
+== Configure the host, port and scheme
+
+By default, the management interface is exposed on the interface: `0.0.0.0` (all interfaces) and on the port `8999` (`8998` in test mode).
+It does not use TLS (`https`) by default.
+
+You can configure the host, ports and TLS certificates using the following properties:
+
+* `quarkus.management.host` - the interface / host
+* `quarkus.management.port` - the port
+* `quarkus.management.test-port` - the port to use in test mode
+* `quarkus.management.ssl` - the TLS configuration, xref:http-reference#ssl[same as for the main HTTP server].
+
+Here is an example for properties exposing the management interface on _https://localhost:9000_:
+
+[source, properties]
+----
+quarkus.management.enabled=true
+quarkus.management.host=localhost
+quarkus.management.port=9000
+quarkus.management.ssl.certificate.key-store-file=server-keystore.jks
+quarkus.management.ssl.certificate.key-store-password=secret
+----
+
+IMPORTANT: Unlike the main HTTP server, the management interface does not handle _http_ and _https_ at the same time.
+If _https_ is configured, plain HTTP requests will be rejected.
+
+== Configure the root path
+
+By default, management endpoints are exposed under `/q`.
+This _root path_ can be configured using the `quarkus.management.root-path` property.
+For example, if you want to expose the management endpoints under `/management` use:
+
+[source, properties]
+----
+quarkus.management.enabled=true
+quarkus.management.root-path=/management
+----
+
+The mounting rules of the management endpoints are slightly different than the ones used when using the main HTTP server:
+
+* Management endpoints configured using a _relative_ path (not starting with `/`) will be served from the configured root path.
+For example, if the endpoint path is `health` and the root path is `management`, the resulting path is `/management/health`
+* Management endpoints configured using an _absolute_ path (starting with `/`) will be served from the root.
+For example, if the endpoint path is `/health`, the resulting path is `/health`, regardless of the root path
+* The management interface does not use the HTTP root path from the main HTTP server.
+
+== Management endpoints
+
+SmallRye Health Checks, SmallRye Metrics and Prometheus are declared as management endpoints.
+Note that if you do not enable the management interface, these endpoints will be served using the main HTTP server (under `/q` by default).
+
+To declare a management endpoint, an extension must produce a _non application_ route and call the `management()` method:
+
+[source, java]
+----
+@BuildStep
+void createManagementRoute(BuildProducer<RouteBuildItem> routes,
+        NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
+        MyRecorder recorder) {
+
+    routes.produce(nonApplicationRootPathBuildItem.routeBuilder()
+        .management() // Must be called BEFORE the routeFunction method
+        .routeFunction("my-path", recorder.route())
+        .handler(recorder.getHandler())
+        .blockingRoute()
+        .build());
+    //...
+}
+----
+
+If the management interface is enabled, the endpoint will be exposed on: `http://0.0.0.0:8999/q/my-path`.
+Otherwise, it will be exposed on: `http://localhost:8080/q/my-path`.
+
+IMPORTANT: Management endpoints can only be declared by extensions and not from the application code.
+
+== Management Interface Configuration
+
+include::{generated-dir}/config/quarkus-management-management-management-interface-build-time-config.adoc[leveloffset=+1, opts=optional]
+
+include::{generated-dir}/config/quarkus-management-management-management-interface-configuration.adoc[leveloffset=+1, opts=optional]
+
+
+[[reverse-proxy]]
+== Running behind a reverse proxy
+
+Quarkus could be accessed through proxies that additionally generate headers (e.g. `X-Forwarded-Host`) to keep
+information from the client-facing side of the proxy servers that is altered or lost when they are involved.
+In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI
+reflecting the values in these headers.
+
+IMPORTANT: Activating this feature leaves the server exposed to several security issues (i.e. information spoofing).
+Consider activate it only when running behind a reverse proxy.
+
+To set up this feature for the management interface, include the following lines in `src/main/resources/application.properties`:
+[source,properties]
+----
+quarkus.management.proxy.proxy-address-forwarding=true
+----
+
+To consider only de-facto standard header (`Forwarded` header), please include the following lines in `src/main/resources/application.properties`:
+[source,properties]
+----
+quarkus.management.proxy.allow-forwarded=true
+----
+
+To consider only non-standard headers, please include the following lines instead in `src/main/resources/application.properties`:
+
+[source,properties]
+----
+quarkus.management.proxy.proxy-address-forwarding=true
+quarkus.management.proxy.allow-x-forwarded=true
+quarkus.management.proxy.enable-forwarded-host=true
+quarkus.management.proxy.enable-forwarded-prefix=true
+----
+
+Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence. However, combining them has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy.
+Therefore, proxies should strip unexpected `X-Forwarded` or `X-Forwarded-*` headers from the client.
+
+Supported forwarding address headers are:
+
+* `Forwarded`
+* `X-Forwarded-Proto`
+* `X-Forwarded-Host`
+* `X-Forwarded-Port`
+* `X-Forwarded-Ssl`
+* `X-Forwarded-Prefix`

extensions/vertx-http/deployment/src/test/java/io/quarkus/vertx/http/management/ManagementWithMainServerDisabledTest.java

@@ -0,0 +1,80 @@
+package io.quarkus.vertx.http.management;
+
+import java.util.function.Consumer;
+
+import javax.enterprise.event.Observes;
+import javax.inject.Singleton;
+
+import org.hamcrest.Matchers;
+import org.jboss.shrinkwrap.api.asset.StringAsset;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.builder.BuildChainBuilder;
+import io.quarkus.builder.BuildContext;
+import io.quarkus.builder.BuildStep;
+import io.quarkus.test.QuarkusUnitTest;
+import io.quarkus.vertx.http.deployment.NonApplicationRootPathBuildItem;
+import io.quarkus.vertx.http.deployment.RouteBuildItem;
+import io.restassured.RestAssured;
+import io.vertx.core.Handler;
+import io.vertx.ext.web.RoutingContext;
+
+public class ManagementWithMainServerDisabledTest {
+    private static final String APP_PROPS = "" +
+            "quarkus.management.enabled=true\n" +
+            "quarkus.management.root-path=/management\n" +
+            "quarkus.http.host-enabled=false\n";
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar
+                    .addAsResource(new StringAsset(APP_PROPS), "application.properties")
+                    .addClasses(MyObserver.class))
+            .addBuildChainCustomizer(buildCustomizer());
+
+    static Consumer<BuildChainBuilder> buildCustomizer() {
+        return new Consumer<BuildChainBuilder>() {
+            @Override
+            public void accept(BuildChainBuilder builder) {
+                builder.addBuildStep(new BuildStep() {
+                    @Override
+                    public void execute(BuildContext context) {
+                        NonApplicationRootPathBuildItem buildItem = context.consume(NonApplicationRootPathBuildItem.class);
+                        context.produce(buildItem.routeBuilder()
+                                .management()
+                                .route("my-route")
+                                .handler(new MyHandler())
+                                .blockingRoute()
+                                .build());
+                    }
+                }).produces(RouteBuildItem.class)
+                        .consumes(NonApplicationRootPathBuildItem.class)
+                        .build();
+            }
+        };
+    }
+
+    public static class MyHandler implements Handler<RoutingContext> {
+        @Override
+        public void handle(RoutingContext rc) {
+            rc.response().end("ok");
+        }
+    }
+
+    @Test
+    public void testManagementWithoutMain() {
+        RestAssured.given()
+                .get("http://0.0.0.0:8998/management/my-route")
+                .then().statusCode(200).body(Matchers.equalTo("ok"));
+    }
+
+    @Singleton
+    static class MyObserver {
+
+        void test(@Observes String event) {
+            //Do Nothing
+        }
+
+    }
+}

extensions/vertx-http/deployment/src/test/java/io/quarkus/vertx/http/management/ManagementWithP12Test.java

@@ -70,7 +70,7 @@ public void handle(RoutingContext rc) {
     }
 
     @Test
-    public void testSslWithJks() {
+    public void testSslWithP12() {
         RestAssured.given()
                 .relaxedHTTPSValidation()
                 .get("https://0.0.0.0:8998/management/my-route")

extensions/vertx-http/deployment/src/test/java/io/quarkus/vertx/http/management/ManagementWithPemTest.java

@@ -71,7 +71,7 @@ public void handle(RoutingContext rc) {
     }
 
     @Test
-    public void testSslWithJks() {
+    public void testSslWithPem() {
         RestAssured.given()
                 .relaxedHTTPSValidation()
                 .get("https://0.0.0.0:8998/management/my-route")