Management interface reference
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, therefore, prevents undesired accesses.
1. Enabling the management interface
To enable the management interface, use the following build-time property:
quarkus.management.enabled=true
By default, management endpoints will be exposed on: http://0.0.0.0:9000/q
.
For example, if you have smallrye-health
installed, the readiness probe will be exposed at http://0.0.0.0:9000/q/health/ready
.
SmallRye Health Checks, SmallRye Metrics, Micrometer and Info endpoints will be declared as management endpoints when the management interface is enabled.
The management interface is disabled when no extensions relying on it (such as the SmallRye Health or SmallRye OpenAPI extensions) are installed. |
2. 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 9000
(9001
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, same as for the main HTTP server.
Here is a configuration example exposing the management interface on https://localhost:9002:
quarkus.management.enabled=true
quarkus.management.host=localhost
quarkus.management.port=9002
quarkus.management.ssl.certificate.key-store-file=server-keystore.jks
quarkus.management.ssl.certificate.key-store-password=secret
Key store, trust store and certificate files can be reloaded periodically.
Configure the quarkus.management.ssl.certificate.reload-period
property to specify the interval at which the certificates should be reloaded:
quarkus.http.management.certificate.files=/mount/certs/tls.crt
quarkus.http.management.certificate.key-files=/mount/certs/tls.key
quarkus.http.management.certificate.reload-period=1h
The files are reloaded from the same location as they were initially loaded from. If there is no content change, the reloading is a no-op. It the reloading fails, the server will continue to use the previous certificates.
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. |
3. Configure the root path
Management endpoints are configured differently than standard HTTP endpoints.
They use a unique root path, which is /q
by default.
This management 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:
quarkus.management.enabled=true
quarkus.management.root-path=/management
The mounting rules of the management endpoints slightly differ from 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 ishealth
and the root path ismanagement
, 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.
The |
4. Create a management endpoint in an extension
To expose an endpoint on the management interface from the code of an application, refer to the application section. |
SmallRye Health Checks, SmallRye Metrics, and Micrometer endpoints will be declared as management endpoints when the management interface is enabled.
if you do not enable the management interface, these endpoints will be served using the main HTTP server (under /q by default).
|
Extensions can create a management endpoint by defining a non application route and calling management()
method:
@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:9000/q/my-path
.
Otherwise, it will be exposed on: http://localhost:8080/q/my-path
.
Management endpoints can only be declared by extensions and not from the application code. |
5. Exposing an endpoint on the management interface (as an application)
You can expose endpoints on the management interface by registering routes on the management router. To access the router use the following code:
public void registerManagementRoutes(@Observes ManagementInterface mi) {
mi.router().get("/admin").handler(rc ->
rc.response().end("admin it is")
);
}
The io.quarkus.vertx.http.ManagementInterface
event is fired when the management interface is initialized.
So, if the management interface is not enabled, the method won’t be called.
The router()
method returns a io.vertx.ext.web.Router
object which can be used to register routes.
The paths are relative to /
.
For example, the previous snippet registers a route on /admin
.
This route is accessible on http://0.0.0.0:9000/admin
, if you use the default host and port.
More details about the Router
API can be found on the Vert.x Web documentation.
6. Management Interface Configuration
Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.
Configuration property |
Tipo |
Padrão |
||
---|---|---|---|---|
Enables / Disables the usage of a separate interface/port to expose the management endpoints. If sets to Environment variable: Show more |
boolean |
|
||
If basic auth should be enabled. Environment variable: Show more |
boolean |
|||
If this is true and credentials are present then a user will always be authenticated before the request progresses. If this is false then an attempt will only be made to authenticate the user if a permission check is performed or the current user is required for some other reason. Environment variable: Show more |
boolean |
|
||
Configures the engine to require/request client authentication. NONE, REQUEST, REQUIRED Environment variable: Show more |
|
|
||
A common root path for management endpoints. Various extension-provided management endpoints such as metrics and health are deployed under this path by default. Environment variable: Show more |
string |
|
||
If responses should be compressed. Note that this will attempt to compress all responses, to avoid compressing already compressed content (such as images) you need to set the following header: Content-Encoding: identity Which will tell vert.x not to compress the response. Environment variable: Show more |
boolean |
|
||
When enabled, vert.x will decompress the request’s body if it’s compressed. Note that the compression format (e.g., gzip) must be specified in the Content-Encoding header in the request. Environment variable: Show more |
boolean |
|
||
The compression level used when compression support is enabled. Environment variable: Show more |
int |
|||
Map the For example, if Environment variable: Show more |
Map<String,List<String>> |
|||
int |
|
|||
The HTTP port Environment variable: Show more |
int |
|
||
The HTTP host Defaults to 0.0.0.0 Defaulting to 0.0.0.0 makes it easier to deploy Quarkus to container, however it is not suitable for dev/test mode as other people on the network can connect to your development machine. Environment variable: Show more |
string |
|||
Enable listening to host:port Environment variable: Show more |
boolean |
|
||
The Please note that using MicroProfile Environment variable: Show more |
string |
|||
The credentials provider bean name. This is a bean name (as in For Vault, the credentials provider bean name is Environment variable: Show more |
string |
|||
The list of path to server certificates using the PEM format. Specifying multiple files requires SNI to be enabled. Environment variable: Show more |
list of path |
|||
The list of path to server certificates private key files using the PEM format. Specifying multiple files requires SNI to be enabled. The order of the key files must match the order of the certificates. Environment variable: Show more |
list of path |
|||
An optional keystore that holds the certificate information instead of specifying separate files. Environment variable: Show more |
path |
|||
An optional parameter to specify the type of the keystore file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|||
An optional parameter to specify a provider of the keystore file. If not given, the provider is automatically detected based on the keystore file type. Environment variable: Show more |
string |
|||
A parameter to specify the password of the keystore file. If not given, and if it can not be retrieved from Environment variable: Show more |
string |
|
||
A parameter to specify a Environment variable: Show more |
string |
|||
An optional parameter to select a specific key in the keystore. When SNI is disabled, and the keystore contains multiple keys and no alias is specified; the behavior is undefined. Environment variable: Show more |
string |
|||
An optional parameter to define the password for the key, in case it is different from Environment variable: Show more |
string |
|||
A parameter to specify a Environment variable: Show more |
string |
|||
An optional trust store that holds the certificate information of the trusted certificates. Environment variable: Show more |
path |
|||
An optional list of trusted certificates using the PEM format. If you pass multiple files, you must use the PEM format. Environment variable: Show more |
list of path |
|||
An optional parameter to specify the type of the trust store file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|||
An optional parameter to specify a provider of the trust store file. If not given, the provider is automatically detected based on the trust store file type. Environment variable: Show more |
string |
|||
A parameter to specify the password of the trust store file. If not given, it might be retrieved from Environment variable: Show more |
string |
|||
A parameter to specify a Environment variable: Show more |
string |
|||
An optional parameter to trust a single certificate from the trust store rather than trusting all certificates in the store. Environment variable: Show more |
string |
|||
When set, the configured certificate will be reloaded after the given period. Note that the certificate will be reloaded only if the file has been modified. Also, the update can also occur when the TLS certificate is configured using paths (and not in-memory). The reload period must be equal or greater than 30 seconds. If not set, the certificate will not be reloaded.
Environment variable: Show more |
||||
The cipher suites to use. If none is given, a reasonable default is selected. Environment variable: Show more |
list of string |
|||
Sets the ordered list of enabled SSL/TLS protocols. If not set, it defaults to Note that setting an empty list, and enabling SSL/TLS is invalid. You must at least have one protocol. Environment variable: Show more |
list of string |
|
||
Enables Server Name Indication (SNI), an TLS extension allowing the server to use multiple certificates. The client indicate the server name during the TLS handshake, allowing the server to select the right certificate. Environment variable: Show more |
boolean |
|
||
The name of the TLS configuration to use. If not set and the default TLS configuration is configured ( If no TLS configuration is set, and Environment variable: Show more |
string |
|||
When set to Environment variable: Show more |
boolean |
|
||
The maximum length of all headers. Environment variable: Show more |
|
|||
The maximum size of a request body. Environment variable: Show more |
|
|||
The max HTTP chunk size Environment variable: Show more |
|
|||
The maximum length of the initial line (e.g. Environment variable: Show more |
int |
|
||
The maximum length of a form attribute. Environment variable: Show more |
|
|||
Set the maximum number of fields of a form. Set to Environment variable: Show more |
int |
|
||
Set the maximum number of bytes a server can buffer when decoding a form. Set to Environment variable: Show more |
|
|||
The maximum number of HTTP request parameters permitted for incoming requests. If a client sends more than this number of parameters in a request, the connection is closed. Environment variable: Show more |
int |
|
||
The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout. Environment variable: Show more |
int |
|||
Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting. Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is Environment variable: Show more |
long |
|||
Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting. Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism. Environment variable: Show more |
long |
|||
Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is Environment variable: Show more |
int |
|||
Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is Environment variable: Show more |
long |
|||
Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is Environment variable: Show more |
int |
|||
Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is Environment variable: Show more |
||||
Http connection idle timeout Environment variable: Show more |
|
|||
Whether the files sent using If Environment variable: Show more |
boolean |
|
||
The directory where the files sent using Either an absolute path or a path relative to the current directory of the application process. Environment variable: Show more |
string |
|
||
Whether the form attributes should be added to the request parameters. If Environment variable: Show more |
boolean |
|
||
Whether the uploaded files should be removed after serving the request. If Environment variable: Show more |
boolean |
|
||
Whether the body buffer should pre-allocated based on the If Environment variable: Show more |
boolean |
|
||
A comma-separated list of Environment variable: Show more |
list of string |
|||
The accept backlog, this is how many connections can be waiting to be accepted before connections start being rejected Environment variable: Show more |
int |
|
||
Path to a unix domain socket Environment variable: Show more |
string |
|
||
Enable listening to host:port Environment variable: Show more |
boolean |
|
||
Set whether the server should use the HA Environment variable: Show more |
boolean |
|
||
If this is true then the address, scheme etc. will be set from headers forwarded by the proxy server, such as Environment variable: Show more |
boolean |
|
||
If this is true and proxy address forwarding is enabled then the standard Environment variable: Show more |
boolean |
|
||
If either this or Environment variable: Show more |
boolean |
|||
Enable override the received request’s host through a forwarded host header. Environment variable: Show more |
boolean |
|
||
Configure the forwarded host header to be used if override enabled. Environment variable: Show more |
string |
|
||
Enable prefix the received request’s path with a forwarded prefix header. Environment variable: Show more |
boolean |
|
||
Configure the forwarded prefix header to be used if prefixing enabled. Environment variable: Show more |
string |
|
||
Configure the list of trusted proxy addresses. Received Examples of a socket address in the form of
Examples of a CIDR notation:
Please bear in mind that IPv4 CIDR won’t match request sent from the IPv6 address and the other way around. Environment variable: Show more |
list of TrustedProxyCheckPart |
|
||
Determines whether the entire permission set is enabled, or not. By default, if the permission set is defined, it is enabled. Environment variable: Show more |
boolean |
|||
The HTTP policy that this permission set is linked to. There are three built-in policies: permit, deny and authenticated. Role based policies can be defined, and extensions can add their own policies. Environment variable: Show more |
string |
required |
||
The methods that this permission set applies to. If this is not set then they apply to all methods. Note that if a request matches any path from any permission set, but does not match the constraint due to the method not being listed then the request will be denied. Method specific permissions take precedence over matches that do not have any methods set. This means that for example if Quarkus is configured to allow GET and POST requests to /admin to and no other permissions are configured PUT requests to /admin will be denied. Environment variable: Show more |
list of string |
|||
The paths that this permission check applies to. If the path ends in /* then this is treated as a path prefix, otherwise it is treated as an exact match. Matches are done on a length basis, so the most specific path match takes precedence. If multiple permission sets match the same path then explicit methods matches take precedence over matches without methods set, otherwise the most restrictive permissions are applied. Environment variable: Show more |
list of string |
|||
Path specific authentication mechanism which must be used to authenticate a user. It needs to match Environment variable: Show more |
string |
|||
Indicates that this policy always applies to the matched paths in addition to the policy with a winning path. Avoid creating more than one shared policy to minimize the performance impact. Environment variable: Show more |
boolean |
|
||
Whether permission check should be applied on all matching paths, or paths specific for the Jakarta REST resources. Environment variable: Show more |
|
|
||
The roles that are allowed to access resources protected by this policy. By default, access is allowed to any authenticated user. Environment variable: Show more |
list of string |
|
||
Add roles granted to the Environment variable: Show more |
Map<String,List<String>> |
|||
Permissions granted to the Environment variable: Show more |
Map<String,List<String>> |
|||
Permissions granted by this policy will be created with a Environment variable: Show more |
string |
|
||
The path this header should be applied Environment variable: Show more |
string |
|
||
The value for this header configuration Environment variable: Show more |
string |
required |
||
The HTTP methods for this header configuration Environment variable: Show more |
list of string |
|||
A regular expression for the paths matching this configuration Environment variable: Show more |
string |
required |
||
Additional HTTP Headers always sent in the response Environment variable: Show more |
Map<String,String> |
|||
The HTTP methods for this path configuration Environment variable: Show more |
list of string |
|||
Order in which this path config is applied. Higher priority takes precedence Environment variable: Show more |
int |
About the Duration format
To write duration values, use the standard Você também pode usar um formato simplificado, começando com um número:
Em outros casos, o formato simplificado é traduzido para o formato 'java.time.Duration' para análise:
|
About the MemorySize format
A size configuration option recognizes strings in this format (shown as a regular expression): If no suffix is given, assume bytes. |
7. Running behind a reverse proxy
Quarkus can be accessed through proxies that generate headers (e.g. X-Forwarded-Host
) to preserve information about the original request.
Quarkus can be configured to automatically update information like protocol, host, port and URI to use the values from those headers.
Activating this feature can expose the server to security issues like information spoofing. 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
:
quarkus.management.proxy.proxy-address-forwarding=true
To constrain this behavior to the standard Forwarded
header (and ignore X-Forwarded
variants) by setting quarkus.management.proxy.allow-forwarded
in src/main/resources/application.properties
:
quarkus.management.proxy.allow-forwarded=true
Alternatively, you can prefer X-Forwarded-*
headers using the following configuration in src/main/resources/application.properties
(note allow-x-forwarded
instead of allow-forwarded
):
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
Supported forwarding address headers are:
-
Forwarded
-
X-Forwarded-Proto
-
X-Forwarded-Host
-
X-Forwarded-Port
-
X-Forwarded-Ssl
-
X-Forwarded-Prefix
If both header variants (Forwarded
and X-Forwarded-*
) are enabled, the Forwarded
header will have precedence.
Using both Forwarded and X-Forwarded headers can have security implications as it may allow clients to forge requests with a header that is not overwritten by the proxy.
|
Ensure that your proxy is configured to strip unexpected Forwarded
or X-Forwarded-*
headers from the client request.
8. Kubernetes
When Quarkus generates the Kubernetes metadata, it checks if the management interface is enabled and configures the probes accordingly.
The resulting descriptor defines the main HTTP port (named http
) and the management port (named management
).
Health probes (using HTTP actions) and Prometheus scrape URLs are configured using the management
port.
KNative
Until KNative#8471 is resolved, you cannot use the management interface, as KNative does not support containers will multiple exposed ports. |
9. Segurança
You can enable basic authentication using the following properties:
quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Require all access to /q/* to be authenticated
quarkus.management.auth.permission.all.policy=authenticated
quarkus.management.auth.permission.all.paths=/q/*
You can also use different permissions for different paths or use role bindings:
quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Configure a management policy if needed, here the policy `management-policy` requires users to have the role `management`.
quarkus.management.auth.policy.management-policy.roles-allowed=management
# For each endpoint you can configure the permissions
# Health used the management-policy (so requires authentication + the `management` role)
quarkus.management.auth.permission.health.paths=/q/health/*
quarkus.management.auth.permission.health.policy=management-policy
# Metrics just requires authentication
quarkus.management.auth.permission.metrics.paths=/q/metrics/*
quarkus.management.auth.permission.metrics.policy=authenticated
More details about Basic authentication in Quarkus can be found in the Basic authentication guide.
10. Injecting management URL in tests
When testing your application, you can inject the management URL using the @TestHTTPResource
annotation:
@TestHTTPResource(value="/management", management=true)
URL management;
The management
attribute is set to true
to indicate that the injected URL is for the management interface.
The context-root
is automatically added.
Thus, in the previous example, the injected URL is http://localhost:9001/q/management
.
@TestHTTPResource
is particularly useful when setting the management test-port
to 0, which indicates that the system will assign a random port to the management interface:
----]
quarkus.management.test-port=0
----