From 665f4140da4c140e7e9b23e5beefbba0f8cdc56a Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Tue, 2 Sep 2025 22:47:12 +0200 Subject: [PATCH] Adding missing docs for 26.4 release notes Closes #42252 Signed-off-by: Alexander Schwartz Signed-off-by: Alexander Schwartz Co-authored-by: Vinod Anandan --- .../release_notes/topics/26_4_0.adoc | 41 +++++++++++++++++++ .../organizations/managing-organization.adoc | 2 +- .../documentation/test/GuideTest.java | 8 ++-- .../high-availability/introduction.adoc | 4 +- .../concepts-memory-and-cpu-sizing.adoc | 2 +- .../multi-cluster/introduction.adoc | 6 +-- .../single-cluster/concepts-threads.adoc | 2 +- .../single-cluster/introduction.adoc | 7 ++-- ...roubleshooting-clustering-and-network.adoc | 2 +- ...s-for-troubleshooting-embedded-caches.adoc | 2 +- .../metrics-for-troubleshooting-http.adoc | 4 +- docs/guides/server/logging.adoc | 2 +- 12 files changed, 62 insertions(+), 20 deletions(-) diff --git a/docs/documentation/release_notes/topics/26_4_0.adoc b/docs/documentation/release_notes/topics/26_4_0.adoc index d7d4050fece..86482bc7fb6 100644 --- a/docs/documentation/release_notes/topics/26_4_0.adoc +++ b/docs/documentation/release_notes/topics/26_4_0.adoc @@ -56,3 +56,44 @@ It is now possible to change which identity providers are shown in the account c the `Show in Account console` setting. You can choose to show only those linked with a user or not show them at all. For more information, please see link:{adminguide_link}#_general-idp-config[General configuration] section in the {adminguide_name}. + += Email domain for organizations is now optional + +In earlier versions, each organization required at least one email domain, which was a limitation for some scenarios. +Starting with this release, an email domain is optional. +Thank you to https://github.com/SferaDev[@SferaDev] for contributing this. + +When no domain is specified, organization members will not be validated against domain restrictions during authentication and profile validation. + += Enhancements for single-cluster and multi-cluster setups + +This release renamed multi-az to multi-cluster. +It adds a separate guide for single-cluster setups, which includes details of how {project_name} clusters can be optionally "stretched" across multiple availability-zones for increased availability. +The {project_name} Operator now deploys {project_name} across multiple availability zones within a Kubernetes cluster by default. {project_name} also detects split-brains within a cluster. + +This should provide better availability for users who are running {project_name} in Kubernetes clusters that span multiple availability zones. + += Translations managed via Weblate + +The {project_name} distribution now includes 35 community translations. With Kazakh, Azerbaijani and Slovenian added in this release. +Community volunteers now maintain some of the translations in https://hosted.weblate.org/projects/keycloak/[Weblate] to keep them up to date. + +If you want to volunteer to maintain an existing or a new translation via Weblate, you can find the necessary steps in the https://github.com/keycloak/keycloak/blob/main/docs/translation.md[translation guide]. + += Setting up OTP can enfore set up of recovery codes + +If you have enabled OTPs and recovery codes as a second factor for authentication, you can configure the OTP required action to ask users to set up recovery codes once they set up an OTP. +Thank you to https://github.com/dasniko[@dasniko] for contributing this. + += MDC logging to correlate messages with realms and clients + +As a new preview feature, you can include in all log messages in the mapped diagnostic context (MDC) of each message realm name, client ID and other information. +This helps you to correlate error messages to a specific realm or client. +Thank you to https://github.com/eicki[@eicki] for contributing this. + +See the https://www.keycloak.org/server/logging[Logging guide] for more information. + += Supported OAuth standards listed on one page + +There is now a new guide listing https://www.keycloak.org/securing-apps/specifications[all implemented OpenID Connect related specifications]. +Thank you to https://github.com/tnorimat[@tnorimat] for contributing this. diff --git a/docs/documentation/server_admin/topics/organizations/managing-organization.adoc b/docs/documentation/server_admin/topics/organizations/managing-organization.adoc index 3299ba5a04e..d221dd78daa 100644 --- a/docs/documentation/server_admin/topics/organizations/managing-organization.adoc +++ b/docs/documentation/server_admin/topics/organizations/managing-organization.adoc @@ -47,7 +47,7 @@ Redirect URL:: After completing registration or accepting an invitation to the organization sent via email, the user is automatically redirected to the specified redirect url. If left empty, the user will be redirected to the account console by default. Domains:: -A set of zero or more domains that belongs to this organization. A domain cannot be shared by different organizations within a realm. When no domains are specified, organization members will not be validated against domain restrictions during authentication and profile validation. +A set of zero or more domains that belongs to this organization. A domain cannot be shared by different organizations within a realm. When no domain is specified, organization members will not be validated against domain restrictions during authentication and profile validation. Description:: A free-text field to describe the organization. diff --git a/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/GuideTest.java b/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/GuideTest.java index e4f7607b22d..c1fbf2e3ffb 100644 --- a/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/GuideTest.java +++ b/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/GuideTest.java @@ -15,28 +15,28 @@ public class GuideTest { @MethodSource("org.keycloak.documentation.test.Guides#guides()") public void checkVariables(String guideName) throws IOException { Set missingVariables = DocUtils.findMissingVariables(new Guide(guideName)); - checkFailures("Variables not found ", missingVariables); + checkFailures("Variables not found in guide " + guideName, missingVariables); } @ParameterizedTest @MethodSource("org.keycloak.documentation.test.Guides#guides()") public void checkIncludes(String guideName) throws IOException { Set missingIncludes = DocUtils.findMissingIncludes(new Guide(guideName)); - checkFailures("Includes not found", missingIncludes); + checkFailures("Includes not found in guide " + guideName, missingIncludes); } @ParameterizedTest @MethodSource("org.keycloak.documentation.test.Guides#guides()") public void checkImages(String guideName) throws IOException { Set failures = LinkUtils.getInstance().findInvalidImages(new Guide(guideName)); - checkFailures("Images not found", failures); + checkFailures("Images not found in guide " + guideName, failures); } @ParameterizedTest @MethodSource("org.keycloak.documentation.test.Guides#guides()") public void checkInternalAnchors(String guideName) throws IOException { Set invalidInternalAnchors = LinkUtils.getInstance().findInvalidInternalAnchors(new Guide(guideName)); - checkFailures("Internal anchors not found", invalidInternalAnchors); + checkFailures("Internal anchors not found in guide " + guideName, invalidInternalAnchors); } private void checkFailures(String message, Set failures) { diff --git a/docs/guides/high-availability/introduction.adoc b/docs/guides/high-availability/introduction.adoc index 8aed38092a8..5e41a25cbaf 100644 --- a/docs/guides/high-availability/introduction.adoc +++ b/docs/guides/high-availability/introduction.adoc @@ -14,7 +14,7 @@ for your deployments. The following architectures are supported by {project_name}. -=== Single cluster +=== Single-cluster deployments Deploy {project_name} in a single cluster, optionally "stretched" across multiple availability-zones, using <@links.ha id="single-cluster-introduction" />. @@ -27,7 +27,7 @@ Disadvantages:: * {kubernetes} cluster is a single point of failure: ** Control-plane failures could impact all {project_name} pods -=== Multi cluster +=== Multi-cluster deployments Connect two {project_name} clusters deployed for example in different {kubernetes} clusters in two availability zones to increase availability using <@links.ha id="multi-cluster-introduction" />. diff --git a/docs/guides/high-availability/multi-cluster/concepts-memory-and-cpu-sizing.adoc b/docs/guides/high-availability/multi-cluster/concepts-memory-and-cpu-sizing.adoc index 1ec3d76f04f..abba23e8388 100644 --- a/docs/guides/high-availability/multi-cluster/concepts-memory-and-cpu-sizing.adoc +++ b/docs/guides/high-availability/multi-cluster/concepts-memory-and-cpu-sizing.adoc @@ -24,7 +24,7 @@ include::../partials/concepts/perf_recommendations.adoc[] include::../partials/concepts/perf_single_cluster_calculation.adoc[] -=== Sizing a multi cluster setup +=== Sizing a multi-cluster setup To create the sizing an active-active Keycloak setup with two AZs in one AWS region, following these steps: diff --git a/docs/guides/high-availability/multi-cluster/introduction.adoc b/docs/guides/high-availability/multi-cluster/introduction.adoc index 17f7792718d..b9669bd6621 100644 --- a/docs/guides/high-availability/multi-cluster/introduction.adoc +++ b/docs/guides/high-availability/multi-cluster/introduction.adoc @@ -3,7 +3,7 @@ <#import "/templates/profile.adoc" as profile> <@tmpl.guide -title="Multi cluster deployments" +title="Multi-cluster deployments" summary="Connect multiple {project_name} deployments in independent {kubernetes} clusters" > {project_name} supports deployments that consist of multiple {project_name} instances that connect to each other using its embedded Infinispan caches. Load balancers can distribute the load evenly across those instances. @@ -12,9 +12,9 @@ Those setups are intended for a transparent networks, see <@links.ha id="single- A multi-cluster setup adds additional components, which allows non-transparent networks to be bridged, in order to provide additional high availability that may be needed for some environments. -== When to use a multi cluster setup +== When to use a multi-cluster setup -The multi cluster deployment capabilities of {project_name} are targeted at use cases that: +The multi-cluster deployment capabilities of {project_name} are targeted at use cases that: * Are constrained to a single <@profile.ifProduct> diff --git a/docs/guides/high-availability/single-cluster/concepts-threads.adoc b/docs/guides/high-availability/single-cluster/concepts-threads.adoc index e8d5cbd1c51..fa1282aa4b5 100644 --- a/docs/guides/high-availability/single-cluster/concepts-threads.adoc +++ b/docs/guides/high-availability/single-cluster/concepts-threads.adoc @@ -18,7 +18,7 @@ For a configuration where this is applied, visit <@links.ha id="single-cluster-d // remove this paragraph once OpenJDK 17 is no longer supported on the server side. // https://github.com/keycloak/keycloak/issues/31101 -JGroups communications, which is used in single cluster setups for the communication between {project_name} nodes, +JGroups communications, which is used in single-cluster setups for the communication between {project_name} nodes, benefits from the use of virtual threads which are available in OpenJDK 21 when at least two cores are available for {project_name}. This reduces the memory usage and removes the need to configure thread pool sizes. Therefore, the use of OpenJDK 21 is recommended. diff --git a/docs/guides/high-availability/single-cluster/introduction.adoc b/docs/guides/high-availability/single-cluster/introduction.adoc index 90fb245bf41..83ca6412af3 100644 --- a/docs/guides/high-availability/single-cluster/introduction.adoc +++ b/docs/guides/high-availability/single-cluster/introduction.adoc @@ -3,11 +3,12 @@ <#import "/templates/profile.adoc" as profile> <@tmpl.guide -title="Single cluster deployments" +title="Single-cluster deployments" summary="Deploy a single Keycloak cluster, optionally stretched across multiple availability-zones" > -== When to use a single cluster setup -The {project_name} single cluster architecture is targeted at use cases that: +== When to use a single-cluster setup + +The {project_name} single-cluster setup is targeted at use cases that: * Deploy to an infrastructure with transparent networking, like for example a single {kubernetes} cluster. * Are constrained to a single diff --git a/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc b/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc index 60f2ec94d6f..0c1d2c77fbf 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc @@ -17,7 +17,7 @@ tileVisible="false" Deploying multiple {project_name} nodes allows the load to be distributed amongst them, but this requires communication between the nodes. This section describes metrics that are useful for monitoring the communication between {project_name} in order to identify possible faults. -NOTE: This is relevant only for single cluster deployments. +NOTE: This is relevant only for single-cluster deployments. When multiple clusters are used, as described in <@links.ha id="multi-cluster-introduction"/>, {project_name} nodes are not clustered together and therefore there is no communication between them directly. include::partials/jgrp_metrics.adoc[leveloffset=+1] diff --git a/docs/guides/observability/metrics-for-troubleshooting-embedded-caches.adoc b/docs/guides/observability/metrics-for-troubleshooting-embedded-caches.adoc index 612bd154d22..5965893ee87 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-embedded-caches.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-embedded-caches.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Embedded Infinispan metrics for single cluster deployments" +title="Embedded Infinispan metrics for single-cluster deployments" summary="Use metrics to monitor caching health and cluster replication." tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-http.adoc b/docs/guides/observability/metrics-for-troubleshooting-http.adoc index b0a0c48634f..be1a9715376 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-http.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-http.adoc @@ -82,7 +82,7 @@ include::partials/histogram_note_http.adoc[] Return back to the <@links.observability id="metrics-for-troubleshooting"/> or, -* For single cluster deployments proceed to <@links.observability id="metrics-for-troubleshooting-clustering-and-network"/>, -* and for multi cluster deployments proceed to <@links.observability id="metrics-for-troubleshooting-embedded-caches-multi-cluster"/> +* For single-cluster deployments, proceed to <@links.observability id="metrics-for-troubleshooting-clustering-and-network"/>, +* and for multi-cluster deployments, proceed to <@links.observability id="metrics-for-troubleshooting-embedded-caches-multi-cluster"/> diff --git a/docs/guides/server/logging.adoc b/docs/guides/server/logging.adoc index 7f809ed8d59..2f29a2a2c3c 100644 --- a/docs/guides/server/logging.adoc +++ b/docs/guides/server/logging.adoc @@ -89,7 +89,7 @@ Use the option `log-mdc-enabled` to enable it. .Example output ---- -2025-06-20 14:13:01,772 {kc.clientId=security-admin-console, kc.realm=master} INFO ... +2025-06-20 14:13:01,772 {kc.clientId=security-admin-console, kc.realmName=master} INFO ... ---- Specify which keys to be added by setting the configuration option `log-mdc-keys`.