diff --git a/docs/documentation/release_notes/topics/25_0_0.adoc b/docs/documentation/release_notes/topics/25_0_0.adoc index e4736ee20b..1551de6b0c 100644 --- a/docs/documentation/release_notes/topics/25_0_0.adoc +++ b/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. diff --git a/docs/documentation/tests/src/test/resources/ignored-links b/docs/documentation/tests/src/test/resources/ignored-links index a0d459af1d..26f0877a45 100644 --- a/docs/documentation/tests/src/test/resources/ignored-links +++ b/docs/documentation/tests/src/test/resources/ignored-links @@ -35,4 +35,5 @@ https://developer.paypal.com/developer/applications 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 \ No newline at end of file +https://stackapps.com/apps/oauth/register +https://www.keycloak.org/server/management-interface \ No newline at end of file diff --git a/docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc index 40a842fa4c..0eb0369cad 100644 --- a/docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc @@ -93,4 +93,17 @@ 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. \ No newline at end of file +`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]. \ No newline at end of file diff --git a/docs/guides/operator/advanced-configuration.adoc b/docs/guides/operator/advanced-configuration.adoc index 206c23458f..c4b874c342 100644 --- a/docs/guides/operator/advanced-configuration.adoc +++ b/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"/>. diff --git a/docs/guides/server/configuration-metrics.adoc b/docs/guides/server/configuration-metrics.adoc index 0d6e4d3bd3..76c551b90d 100644 --- a/docs/guides/server/configuration-metrics.adoc +++ b/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: diff --git a/docs/guides/server/health.adoc b/docs/guides/server/health.adoc index 6ab73a4f3a..880349c260 100644 --- a/docs/guides/server/health.adoc +++ b/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. diff --git a/docs/guides/server/management-interface.adoc b/docs/guides/server/management-interface.adoc new file mode 100644 index 0000000000..453ddabed9 --- /dev/null +++ b/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. +==== + + \ No newline at end of file diff --git a/docs/guides/server/pinned-guides b/docs/guides/server/pinned-guides index 420eef9366..cd63457ab4 100644 --- a/docs/guides/server/pinned-guides +++ b/docs/guides/server/pinned-guides @@ -12,6 +12,7 @@ features configuration-provider logging fips +management-interface health configuration-metrics importExport