Avoid polluting the URI namespace with Quarkus endpoints?

[Guillaume Smet]

Hi,

Ken has a good point here about us starting to significantly pollute the endpoint namespace with the extensions: https://github.com/quarkusio/quarkus/pull/1573#issuecomment-474506344 .

/health, /openapi, /metrics, now /swagger-ui and probably others in the future.

While I don't think /admin/ is a good choice of prefix, I wonder if we should have all these endpoints hosted by default with a /quarkus/ prefix.

They can be configured if needed but at least, by default, we won't pollute the endpoint namespace and the /quarkus/ name makes it clear that it's a "reserved" namespace.

What I'm wondering is: for the MicroProfile extensions, are these default endpoints in the spec? Or can we safely change them?

Thoughts?

--

Guillaume

[jmat...@redhat.com]

I agree that items should exist under a reserved prefix URI spring boot actuator and other frameworks does something similar so I do not believe this out of the question. Also would help prevent overlap if an application needs to have one of these urls.

[Martin Kouba]

Dne 21. 03. 19 v 0:42 Guillaume Smet napsal(a):

> Hi,
>
> Ken has a good point here about us starting to significantly pollute the
> endpoint namespace with the extensions:
> https://github.com/quarkusio/quarkus/pull/1573#issuecomment-474506344 .
>
> /health, /openapi, /metrics, now /swagger-ui and probably others in the
> future.
>
> While I don't think /admin/ is a good choice of prefix, I wonder if we
> should have all these endpoints hosted by default with a /quarkus/ prefix.
>
> They can be configured if needed but at least, by default, we won't
> pollute the endpoint namespace and the /quarkus/ name makes it clear
> that it's a "reserved" namespace.

I like the idea of a configurable base path for all non-app endpoints.

>
> What I'm wondering is: for the MicroProfile extensions, are these
> default endpoints in the spec? Or can we safely change them?

MP Health spec: "This /health endpoint is expected to be associated with
a configurable context, such as a web application deployment, that can
be configured with settings such as port, virtual-host, security, etc."

However, I'm not so sure about MP Metrics and OpenAPI. @Jan Martiska
@Eric Wittmann?

>
> Thoughts?
>
> --
> Guillaume
>
> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev...@googlegroups.com>.
> Visit this group at https://groups.google.com/group/quarkus-dev.
> For more options, visit https://groups.google.com/d/optout.

--
Martin Kouba
Senior Software Engineer
Red Hat, Czech Republic

[clement escoffier]

Hello,

I like the idea you use a configurable prefix defaulting to "/quarkus” (we just need to be sure that it does not conflict with the user path).

Clement

> To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

[Jan Martiška]

On Thursday, March 21, 2019 at 8:08:41 AM UTC+1, Martin Kouba wrote:

Dne 21. 03. 19 v 0:42 Guillaume Smet napsal(a):
> Hi,
>
> Ken has a good point here about us starting to significantly pollute the
> endpoint namespace with the extensions:
> https://github.com/quarkusio/quarkus/pull/1573#issuecomment-474506344 .
>
> /health, /openapi, /metrics, now /swagger-ui and probably others in the
> future.
>
> While I don't think /admin/ is a good choice of prefix, I wonder if we
> should have all these endpoints hosted by default with a /quarkus/ prefix.
>
> They can be configured if needed but at least, by default, we won't
> pollute the endpoint namespace and the /quarkus/ name makes it clear
> that it's a "reserved" namespace.

I like the idea of a configurable base path for all non-app endpoints.

>
> What I'm wondering is: for the MicroProfile extensions, are these
> default endpoints in the spec? Or can we safely change them?

MP Health spec: "This /health endpoint is expected to be associated with
a configurable context, such as a web application deployment, that can
be configured with settings such as port, virtual-host, security, etc."

However, I'm not so sure about MP Metrics and OpenAPI. @Jan Martiska
@Eric Wittmann?

AFAIK MP Metrics spec doesn't explicitly mention that the endpoint is expected to be configurable, but I guess it shouldn't be a problem.
It could be a bit of a problem for the Metrics TCK, but we're not running the TCKs against Quarkus at the moment anyway, and I guess it could be worked around if we wanted to in the future.
We would also need a tiny change in SmallRye Metrics to be able to support an endpoint different than /metrics, but that's not a big deal either.

So I guess no problem from the Metrics side.

>
> Thoughts?
>
> --
> Guillaume
>
> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to quarkus-dev...@googlegroups.com

> <mailto:quarkus-dev+unsub...@googlegroups.com>.

[Ken Finnigan]

I agree it makes sense to consolidate non app endpoints under a single one.

Currently most MP specs mandate the path be at the root, but we can always customize that once we get to the point of running TCK tests. It's also something that MP specs should support as there will be people that want different names.

Probably worth having some kind of "management endpoint" that all these bits can attach themselves to as sub endpoints, which defaults to being localhost:8080/quarkus. But it can be configured on different endpoints or ports so you could choose to use something like localhost:9000/ if you wanted.

Could also be beneficial to have a simple webpage at the "management endpoint" root that links out to the different installed endpoints that are present.

Ken

> <mailto:quarkus-dev...@googlegroups.com>.

> Visit this group at https://groups.google.com/group/quarkus-dev.
> For more options, visit https://groups.google.com/d/optout.

--
Martin Kouba
Senior Software Engineer
Red Hat, Czech Republic

--

You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.

To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

[Martin Kouba]

I've created https://github.com/quarkusio/quarkus/issues/2450 to track
this issue.

Dne 21. 03. 19 v 14:34 Ken Finnigan napsal(a):

[Rostislav Svoboda]

On 21 Mar 2019, at 14:34, Ken Finnigan <k...@kenfinnigan.me> wrote:

I agree it makes sense to consolidate non app endpoints under a single one.

Currently most MP specs mandate the path be at the root, but we can always customize that once we get to the point of running TCK tests. It's also something that MP specs should support as there will be people that want different names.

Path at root is not just  MP TCKs requirement.

Many tools expect that too and we don’t control them.

E.g. https://prometheus.io/docs/introduction/first_steps/ :

Prometheus expects metrics to be available on targets on a path of /metrics. So this default job is scraping via the URL: http://localhost:9090/metrics.

https://prometheus.io/docs/prometheus/latest/configuration/configuration/#static_config … just host and port can be specified

https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config … metrics_path can be specified, but it’s global setting so all services must expose data on the same path

Prometheus is used for metrics in OpenShift 4

MP users are used to standard path at root, they can have tooling around those endpoint.

[Scott Stark]

How would we go about identifying what is a core quarkus extension that should even go under a /quarkus context? The various MP specs that define endpoints do default to a root level one, and at leas the health and metrics extensions already have this context configurable:

x

x

@ConfigRoot(name = "smallrye-metrics")
static final class SmallRyeMetricsConfig {

    /**
     * The path to the metrics Servlet.
     */
    @ConfigItem(defaultValue = "/metrics")
    String path;
}

SmallRyeMetricsConfig metrics;

...

@BuildStep
ServletBuildItem createServlet() {
    ServletBuildItem servletBuildItem = ServletBuildItem.builder("metrics", SmallRyeMetricsServlet.class.getName())
            .addMapping(metrics.path + (metrics.path.endsWith("/") ? "*" : "/*"))
            .build();
    return servletBuildItem;
}

x

How would it be detected that "/metrics" was not the configured endpoint location? 

If we are going to be mapping default endpoints to some other context, we should have a way to query what endpoints exist as this is always a troubleshooting issue to know where endpoints are located.

[Martin Kouba]

Dne 16. 05. 19 v 3:18 Scott Stark napsal(a):

> How would we go about identifying what is a core quarkus extension that
> should even go under a /quarkus context?

I think that any extension that registers an additional endpoint should
always use the configurable mgmt prefix (ie. /quarkus) plus its own
hardcoded or configurable path (e.g. /metrics).

I was thinking about returning JSON with the set of additional endpoints
from "GET /quarkus".

>
>
> On Wednesday, March 20, 2019 at 4:43:18 PM UTC-7, Guillaume Smet wrote:
>
> Hi,
>
> Ken has a good point here about us starting to significantly pollute
> the endpoint namespace with the extensions:

> https://github.com/quarkusio/quarkus/pull/1573#issuecomment-474506344 <https://github.com/quarkusio/quarkus/pull/1573#issuecomment-474506344>

> .
>
> /health, /openapi, /metrics, now /swagger-ui and probably others in
> the future.
>
> While I don't think /admin/ is a good choice of prefix, I wonder if
> we should have all these endpoints hosted by default with a
> /quarkus/ prefix.
>
> They can be configured if needed but at least, by default, we won't
> pollute the endpoint namespace and the /quarkus/ name makes it clear
> that it's a "reserved" namespace.
>
> What I'm wondering is: for the MicroProfile extensions, are these
> default endpoints in the spec? Or can we safely change them?
>
> Thoughts?
>
> --
> Guillaume
>

> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev...@googlegroups.com>.
> Visit this group at https://groups.google.com/group/quarkus-dev.

> To view this discussion on the web visit
> https://groups.google.com/d/msgid/quarkus-dev/c7537248-962c-4fc3-adb1-f692254689a0%40googlegroups.com
> <https://groups.google.com/d/msgid/quarkus-dev/c7537248-962c-4fc3-adb1-f692254689a0%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Martin Kouba]

Dne 15. 05. 19 v 16:49 Rostislav Svoboda napsal(a):

>
>
>> On 21 Mar 2019, at 14:34, Ken Finnigan <k...@kenfinnigan.me

>> <mailto:k...@kenfinnigan.me>> wrote:
>>
>> I agree it makes sense to consolidate non app endpoints under a single
>> one.
>>
>> Currently most MP specs mandate the path be at the root, but we can
>> always customize that once we get to the point of running TCK tests.
>> It's also something that MP specs should support as there will be
>> people that want different names.
>
> Path at root is not just  MP TCKs requirement.
> Many tools expect that too and we don’t control them.
>
> E.g. https://prometheus.io/docs/introduction/first_steps/ :
> Prometheus expects metrics to be available on targets on a path of

> |/metrics|. So this default job is scraping via the URL:

> http://localhost:9090/metrics.
> https://prometheus.io/docs/prometheus/latest/configuration/configuration/#static_config …
> just host and port can be specified
> https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config …
> metrics_path can be specified, but it’s global setting so all services

This is unfortunate :-(

> must expose data on the same path
> Prometheus is used for metrics in OpenShift 4
>
> MP users are used to standard path at root, they can have tooling around
> those endpoint.

I personally think this was a poor design decision. Anyway, if we make
it configurable it should be always possible to fall back to the "defaults".

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/50FB0E04-26F9-4D1C-AD8B-E443DFC81071%40redhat.com
> <https://groups.google.com/d/msgid/quarkus-dev/50FB0E04-26F9-4D1C-AD8B-E443DFC81071%40redhat.com?utm_medium=email&utm_source=footer>.

[Sergey Beryozkin]

One problem with /quarkus is that customers may not be willing to reveal to the outside world the details of the implementation runtime. It will probably be flagged as a security exception if it is done by default (similarly to how Server header can be flagged).

Having a simple way to override /health as also suggested by Guillaume, etc to avoid the pollution would be a good way forward IMHO

Sergey 

--

You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.

To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

Visit this group at https://groups.google.com/group/quarkus-dev.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/c7537248-962c-4fc3-adb1-f692254689a0%40googlegroups.com.

[Sergey Beryozkin]

I.e, every extension which affects a URI space with its own path segment should be mandated to have a property to customize it

Sergey

[Sergey Beryozkin]

And indeed, a configurable management prefix, but may be not 'quarkus' :-) would be nice as well, /management, etc

/mgmt/health

or

/servicehealth

where one configures a management prefix be "/" and the individual extension segment as 'servicehealth', etc

Sergey

To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

Visit this group at https://groups.google.com/group/quarkus-dev.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/a3a86a88-c444-f5d5-d97f-49b45de3a32e%40redhat.com.

[Luis Rodrigues]

+1 to:

[Sergey Beryozkin]

My only concern about a "/quarkus" being a default value is that it will be documented in the Quarkus docs and will also become part of the public API for a given web application which will use Quarkus. If I were to deploy Quarkus as a customer I'd say no to it because the public URIs are meant to be resolvable which means if I were to switch to something else but Quarkus I'd break the clients expecting the /quarkus URIs work - so it would be easy for someone to claim it causes a tie-in. Yes, people will be able to change it something else but why make them do one extra configuration step ?

May be it is only me exaggerating it, sorry :-)

Sergey 

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
Visit this group at https://groups.google.com/group/quarkus-dev.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/817797ec-fb1f-405a-92f1-fa8cef261b8a%40googlegroups.com.

[Rostislav Svoboda]

On EAP we removed Undertow headers (https://issues.jboss.org/browse/JBEAP-10266) to avoid exposing implementation details.

On community side there were questions how to disable it too - e.g. https://developer.jboss.org/thread/261639

What would be the endpoint name once we reach product phase :) Would it change ?

Rostislav

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAMsYBfUZ16RbTYnewadrWkO03wN%2BT5NnvwFVfT6cgv0SqkKbnA%40mail.gmail.com.

[Sergey Beryozkin]

Hi Rostislav

Thanks for these links, indeed, I've seen similar requests with the other stacks as well.

In this case, it is at the public URI space level, lets say a customer has a /myservice endpoint at the /app context, so the clients will access it via https://somehost/app/myservice, but to check its health state they would be asked to go to
https://somehost/app/quarkus/health, and here would be a problem for me as a would be customer, because of the difficulties with the possible migrations in the future but also, even though it may be a bit academic, with giving the attackers a chance to try to figure out a specific version of Quarkus (may be responses from quarkus/health endpoints differ in formats between Quarkus N and N+1 versions, etc) hence a security flag risk

Cheers, Sergey