
:guide-id: management-interface
:guide-title: Configuring the Management Interface
:guide-summary: Configure {project_name}'s management interface for endpoints such as metrics and health checks.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.3.4

include::../attributes.adoc[]

[[management-interface]]
= Configuring the Management Interface

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


The management interface allows accessing management endpoints via a different HTTP server than the primary one.
It provides the possibility to hide endpoints like `/metrics` or `/health` from the outside world and, therefore, hardens the security.
The most significant advantage might be seen in Kubernetes environments as the specific management port might not be exposed.

== Management interface configuration

The management interface is turned on when something is exposed on it.
Management endpoints such as `/metrics` and `/health` are exposed on the default management port `9000` when metrics and health are enabled.
The management interface provides a set of options and is fully configurable.

NOTE: If management interface properties are not explicitly set, their values are automatically inherited from the default HTTP server.

=== Port
In order to change the port for the management interface, you can use the {project_name} option `http-management-port`.

=== Relative path
You can change the relative path of the management interface, as the prefix path for the management endpoints can be different.
You can achieve it via the {project_name} option `http-management-relative-path`.

For instance, if you set the CLI option `--http-management-relative-path=/management`, the metrics, and health endpoints will be accessed on the `/management/metrics` and `/management/health` paths.

User is automatically *redirected* to the path where {project_name} is hosted when the relative path is specified.
It means when the relative path is set to `/management`, and the user access `localhost:9000/`, the page is redirected to `localhost:9000/management`.

NOTE: If you do not explicitly set the value for it, the value from the `http-relative-path` property is used. For instance,
if you set the CLI option `--http-relative-path=/auth`, these endpoints are accessible on the `/auth/metrics` and `/auth/health` paths.

=== TLS support

When the TLS is set for the default {project_name} server, the management interface will be accessible through HTTPS as well.
The management interface can run only either on HTTP or HTTPS, not both as for the main server.

Specific {project_name} management interface options with the prefix `https-management-*` were provided for setting different TLS parameters for the management HTTP server. Their function is similar to their counterparts for the main HTTP server, for details see link:{links_server_enabletls_url}[{links_server_enabletls_name}].
When these options are not explicitly set, the TLS parameters are inherited from the default HTTP server.

=== Disable Management interface

The management interface is automatically turned off when nothing is exposed on it.
Currently, only health checks and metrics are exposed on the management interface regardless.
If you want to disable exposing them on the management interface, set the {project_name} property `legacy-observability-interface` to `true`.

[WARNING]
====
Exposing health and metrics endpoints on the default server is not recommended for security reasons, and you should always use the management interface.
Beware, the `legacy-observability-interface` option is deprecated and will be removed in future releases.
It only allows you to give more time for the migration.
====


== Relevant options

[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#`+http-management-port+`# 

[.options-description]#Port of the management interface.#

[role="options-extended"]
--
[.options-description-extended]#Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--http-management-port+` +
*Env:* `+KC_HTTP_MANAGEMENT_PORT+`
--



|[.options-default]#`+9000+`# (default)

|
[.options-key]#`+http-management-relative-path+`# [.none]#icon:tools[role=options-build]#

[.options-description]#Set the path relative to `/` for serving resources from management interface.#

[role="options-extended"]
--
[.options-description-extended]#The path must start with a `/`. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--http-management-relative-path+` +
*Env:* `+KC_HTTP_MANAGEMENT_RELATIVE_PATH+`
--



|[.options-default]#`+/+`# (default)

|
[.options-key]#`+https-management-certificate-file+`# 

[.options-description]#The file path to a server certificate or certificate chain in PEM format for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificate-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE+`
--



|

|
[.options-key]#`+https-management-certificate-key-file+`# 

[.options-description]#The file path to a private key in PEM format for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificate-key-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE+`
--



|

|
[.options-key]#`+https-management-certificates-reload-period+`# 

[.options-description]#Interval on which to reload key store, trust store, and certificate files referenced by https-management-* options for the management server.#

[role="options-extended"]
--
[.options-description-extended]#May be a java.time.Duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificates-reload-period+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD+`
--



|[.options-default]#`+1h+`# (default)

|
[.options-key]#`+https-management-client-auth+`# [.none]#icon:tools[role=options-build]#

[.options-description]#Configures the management interface to require/request client authentication.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-client-auth+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CLIENT_AUTH+`
--



|
`+none+` (default), `+request+`, `+required+`

|
[.options-key]#`+https-management-key-store-file+`# 

[.options-description]#The key store which holds the certificate information instead of specifying separate files for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-key-store-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_KEY_STORE_FILE+`
--



|

|
[.options-key]#`+https-management-key-store-password+`# 

[.options-description]#The password of the key store file for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-key-store-password+` +
*Env:* `+KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD+`
--



|[.options-default]#`+password+`# (default)

|
[.options-key]#`+legacy-observability-interface+`# [.none]#icon:tools[role=options-build]#

[.options-description]#If metrics/health endpoints should be exposed on the main HTTP server (not recommended).#

[role="options-extended"]
--
[.options-description-extended]#If set to true, the management interface is disabled.#

*CLI:* `+--legacy-observability-interface+` +
*Env:* `+KC_LEGACY_OBSERVABILITY_INTERFACE+`
--


*DEPRECATED.*


|
`+true+`, `+false+` (default)


|===
