docs: Support management port for health and metrics (#28213)

Relates to #19334

Signed-off-by: Martin Bartoš <mabartos@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Václav Muzikář <vmuzikar@redhat.com>

docs/documentation/release_notes/topics/25_0_0.adoc

@@ -54,6 +54,17 @@ This fix will break code that relied on casting the List or its contents to `Lis
 When exporting the authorization settings for a client, the IDs for resources, scopes, and policies are no longer set. As a
 result, you can now import the settings from a client to another client.
 
+= Management port for metrics and health endpoints
+
+Metrics and health checks endpoints are no longer accessible through the standard {project_name} server port.
+As these endpoints should be hidden from the outside world, they can be accessed on a separate default management port `9000`.
+
+It allows to not expose it to the users as standard Keycloak endpoints in Kubernetes environments.
+The new management interface provides a new set of options and is fully configurable.
+
+{project_name} Operator assumes the management interface is turned on by default.
+For more details, see https://www.keycloak.org/server/management-interface[Configuring the Management Interface].
+
 = Syslog for remote logging
 
 {project_name} now supports https://en.wikipedia.org/wiki/Syslog[Syslog] protocol for remote logging.

docs/documentation/tests/src/test/resources/ignored-links

@@ -36,3 +36,4 @@ https://account.live.com/developers/applications/create
 https://developer.twitter.com/apps/
 https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#rolling-update
 https://stackapps.com/apps/oauth/register
+https://www.keycloak.org/server/management-interface

docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc

@@ -94,3 +94,16 @@ If an old version of the JS adapter is used, the `Session State (session_state)`
 = Default `http-pool-max-threads` reduced
 
 `http-pool-max-threads` if left unset will default to the greater of 50 or 4 x (available processors). Previously it defaulted to the greater of 200 or 8 x (available processors). Reducing the number or task threads for most usage scenarios will result in slightly higher performance due to less context switching among active threads.
+
+= Management port for metrics and health endpoints
+
+The `/health` and `/metrics` endpoints are accessible on the management port `9000`, which is turned on by default.
+That means these endpoints are no longer exposed to the standard Keycloak ports `8080` and `8443`.
+
+In order to reflect the old behavior, use the property `--legacy-observability-interface=true`, which will not expose these endpoints on the management port.
+However, this property is deprecated and will be removed in future releases, so it is recommended not to use it.
+
+The management interface uses a different HTTP server than the default {project_name} HTTP server, and it is possible to configure them separately.
+Beware, if no values are supplied for the management interface properties, they are inherited from the default {project_name} HTTP server.
+
+For more details, see https://www.keycloak.org/server/management-interface[Configuring the Management Interface].

docs/guides/operator/advanced-configuration.adoc

@@ -205,6 +205,27 @@ It is achieved by providing certain JVM options.
 
 For more details, see <@links.server id="containers" />.
 
+== Management Interface
+
+To change the port of the management interface, use the first-class citizen field `httpManagement.port` in the Keycloak CR.
+To change the properties of the management interface, you can do it by providing `additionalOptions` field.
+
+You can specify the `port` and the `additionalOptions` as follows:
+
+[source,yaml]
+----
+apiVersion: k8s.keycloak.org/v2alpha1
+kind: Keycloak
+metadata:
+  name: example-kc
+spec:
+  httpManagement:
+    port: 9001
+  additionalOptions:
+    - name: http-management-relative-path
+      value: /management
+----
+
 === Truststores
 
 If you need to provide trusted certificates, the Keycloak CR provides a top level feature for configuring the server's truststore as discussed in <@links.server id="keycloak-truststore"/>.

docs/guides/server/configuration-metrics.adoc

@@ -18,10 +18,11 @@ It is possible to enable metrics using the build time option `metrics-enabled`:
 
 == Querying Metrics
 
-{project_name} exposes metrics at the following endpoint:
+{project_name} exposes metrics at the following endpoint on the management interface at:
 
 * `/metrics`
 
+For more information about the management interface, see <@links.server id="management-interface" />.
 The response from the endpoint uses a `application/openmetrics-text` content type and it is based on the Prometheus (OpenMetrics) text format. The snippet bellow
 is an example of a response:
 

docs/guides/server/health.adoc

@@ -9,6 +9,7 @@ summary="Learn how to enable and use {project_name} health checks"
 includedOptions="health-enabled">
 
 {project_name} has built in support for health checks. This {section} describes how to enable and use the {project_name} health checks.
+The {project_name} health checks are exposed on the management port `9000` by default. For more details, see <@links.server id="management-interface" />
 
 == {project_name} health check endpoints
 
@@ -67,7 +68,7 @@ If {project_name} is deployed in a container, you must run this command from out
 
 [source, bash]
 ----
-curl --head -fsS http://localhost:8080/health/ready
+curl --head -fsS http://localhost:9000/health/ready
 ----
 
 If the command returns with status 0, then {project_name} is `+live+` or `+ready+`, depending on which endpoint you called. Otherwise there is a problem.

docs/guides/server/management-interface.adoc

@@ -0,0 +1,51 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/kc.adoc" as kc>
+<#import "/templates/links.adoc" as links>
+
+<@tmpl.guide
+title="Configuring the Management Interface"
+summary="Learn how to configure {project_name}'s management interface for endpoints like metrics and health checks."
+includedOptions="http-management-* https-management-* legacy-observability-interface">
+
+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 by default, so management endpoints such as `/metrics`, and `/health` are exposed on the default management port `9000`.
+In order to change the port for the management interface, you can use the {project_name} option `http-management-port`.
+
+The management interface provides a set of options and is fully configurable.
+If these options for the management HTTP server are not explicitly set, their values are automatically inherited from the default HTTP server.
+
+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.
+
+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 <@links.server id="enabletls" />.
+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.
+====
+
+</@tmpl.guide>

docs/guides/server/pinned-guides

@@ -12,6 +12,7 @@ features
 configuration-provider
 logging
 fips
+management-interface
 health
 configuration-metrics
 importExport