update documentation to expose multi-namespace install modes by edewit · Pull Request #49966 · keycloak/keycloak

edewit · 2026-06-12T14:39:59Z

fixes: #49037
Signed-off-by: Erik Jan de Wit erikjan.dewit@gmail.com

edewit · 2026-06-12T14:40:57Z

not totally sure this documentation isn't lying...

vmuzikar

As discussed offline, we'll need some code changes as well. Especially:

keycloak/operator/src/main/java/org/keycloak/operator/controllers/KeycloakSharedCsvMetadata.java

Lines 69 to 72 in c334a82

    
           @CSVMetadata.InstallMode( 
        
               type = "AllNamespaces", 
        
               supported = false 
        
           )

Also, this will need to be removed/adjusted:

keycloak/.github/workflows/operator-ci.yml

Line 208 in c334a82

    
                     kubectl patch csv keycloak-operator.v86400000.0.0 --type merge --patch '{"spec": {"installModes": [{"type": "AllNamespaces","supported": true}]}}'

edewit · 2026-06-17T10:00:18Z

done

shawkins

Either here or in a follow-up we'll need a release note about cluster wide install mode.

shawkins · 2026-06-17T12:34:56Z

+----
+
+<@profile.ifCommunity>
+[[installing_cluster_wide_with_kubectl]]


This is fine for a placeholder, but we'll mostly remove / rewrite this based upon the other PR.

shawkins · 2026-06-17T12:37:58Z

+spec: {}
+----
+
+Approve the install plan if you are using manual approval, then verify that the Operator pod is running.


We recommend only using manual approval.

shawkins · 2026-06-17T12:38:55Z

+
+Approve the install plan if you are using manual approval, then verify that the Operator pod is running.
+
+If the Operator is already installed in single-namespace mode, you can switch to cluster-wide mode by removing `spec.targetNamespaces` from the OperatorGroup:


This should be removed. It's not recommended to simply switch from single namespace to cluster-wide - a cluster-wide operator should be in it's own namespace.

shawkins · 2026-06-17T12:50:58Z

+
+==== Installing with OLM
+
+To install in `MultiNamespace` or `AllNamespaces` mode, create an OperatorGroup with the desired namespace selection, subscribe to the Operator, and approve the install plan.


I would leave MultiNamespace instructions out of the guide - that install mode is effectively going away.

I also don't see any forward support for namespace selection by label, nor is that currently supported in the java operator sdk.

So it seems better to not even mention the possibility of doing this.

Should we even expose the MultiNamespace install mode in the CSV metadata? cc @vmuzikar

Should we even expose the MultiNamespace install mode in the CSV metadata?

As discussed on the meeting yesterday, I lean towards no.

Copilot

Pull request overview

This PR addresses issue #49037 by exposing and documenting multi-namespace and cluster-wide installation modes for the Keycloak Operator, aligning OLM metadata with the Operator’s existing capabilities and expanding the installation guide accordingly.

Changes:

Enable MultiNamespace and AllNamespaces as supported OLM install modes in the Operator CSV metadata.
Extend the Operator installation guide with a new multi-namespace/cluster-wide section (OLM + non-OLM guidance).
Simplify OLM CI by removing the CSV installModes patch step now that the CSV metadata supports these modes.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
operator/src/main/java/org/keycloak/operator/controllers/KeycloakSharedCsvMetadata.java	Marks `MultiNamespace` and `AllNamespaces` as supported install modes in the shared CSV metadata.
docs/guides/operator/installation.adoc	Adds multi-namespace/cluster-wide installation documentation (OLM + non-OLM), including limitations and guidance.
.github/workflows/operator-ci.yml	Removes the CSV patch used to force `AllNamespaces` support during OLM CI testing.

shawkins

LGTM, thanks @edewit

vmuzikar · 2026-06-23T09:08:35Z

+
+* `spec.podTemplate.spec.serviceAccountName` cannot be used on a `Keycloak` custom resource. The Operator ignores this field and reports a warning.
+* The Operator does not reconcile multiple {project_name} versions in one cluster.
+* You need cluster-admin permissions, or equivalent permissions, to configure cluster-scoped RBAC for non-OLM installations.


This will need to be guarded by the community profile as non-OLM installs are supported upstream only. In other words, this bullet point must be excluded downstream.

The bullet point should've stayed, just be wrapped by profile.ifCommunity.

The bullet-point is still missing. However, thinking about it more, you need cluster-admin permissions even for OLM installations. So the bullet point should be:

* You need cluster-admin permissions, or equivalent permissions.

vmuzikar · 2026-06-23T09:25:48Z

+
+==== Installing with OLM
+
+To install in `AllNamespaces` mode, create an OperatorGroup without `spec.targetNamespaces`, subscribe to the Operator, and approve the install plan.


This makes an impression that the cluster-wide OLM install is possible only via CLI. We should mention the web console way as well.

how do you want me to put that?

We should split the instructions for CLI and web console, similarly how we have it in the chapters above for installing using OLM.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

+The Operator supports the standard OLM install modes:
+
+[cols="1,2",options="header"]
+|===
+| Install mode | Operator watches
+
+| `OwnNamespace`
+| The namespace where the Operator is installed
+
+| `SingleNamespace`
+| One namespace other than the Operator namespace
+
+| `AllNamespaces`
+| All namespaces in the cluster
+|===


Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

+
+A single {project_name} Operator can reconcile custom resources in all namespaces in the cluster. This avoids running one Operator per namespace while still allowing {project_name} instances to be deployed in separate namespaces.
+
+The Operator supports the standard OLM install modes:


vmuzikar · 2026-06-25T16:45:20Z

@edewit What is the status of this PR? It is needed for the 26.7 release.

edewit · 2026-06-26T13:04:23Z

I need to do the web console stuff, but I haven't setup my environment yet

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

vmuzikar · 2026-06-29T16:43:38Z

+
+<@profile.ifCommunity>
+[[installing_cluster_wide_with_kubectl]]
+==== Installing cluster-wide with kubectl


@edewit Thank you for the update. There's one last thing from my perspective.

#46980 is ready and will be merged sooner than this. Can you please update this chapter for installing cluster-wide with kubectl to match the current state of #46980?

Additionally, we'll need to mention kustomize in the release notes – both in the context of all-namespaces mode, as well as in the context of generally new deployment method (that the Operator can now be deployed using kustomize).

Actually, #46980 already include kustomize instructions for cluster-wide. So let's just wait until it's merged, rebase this PR and update the docs so cluster-wide instructions for OLM and kustomize are in the same chapter.

fixes: keycloak#49037 Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

also changed docs and ci to no longer mention/execute patching the csv Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

vmuzikar

Overall looks good now.

@shawkins Do you want to give it one final look too?

shawkins

LGTM, thank you @edewit

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Signed-off-by: Václav Muzikář <vmuzikar@ibm.com>

vmuzikar

I took the liberty and pushed some cosmetic changes, mainly to remove the extra + signs.

LGTM, thanks @edewit.

…k#49966) * update documentation to expose multi-namespace install modes fixes: keycloak#49037 Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * updated csv also changed docs and ci to no longer mention/execute patching the csv Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * changed experimental to preview Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * PR review commments Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * Update docs/guides/operator/installation.adoc Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * Update docs/guides/operator/installation.adoc Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * removed rbac reference Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * web based installation Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * PR comments Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * merged clusterwide with kustomize Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> * Cosmetic tweaks Signed-off-by: Václav Muzikář <vmuzikar@ibm.com> --------- Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Václav Muzikář <vmuzikar@ibm.com> Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

edewit requested a review from shawkins June 12, 2026 14:40

vmuzikar requested changes Jun 16, 2026

View reviewed changes

stianst added the team/cloud-native label Jun 17, 2026

keycloak-github-bot Bot added the flaky-test label Jun 17, 2026

keycloak-github-bot Bot mentioned this pull request Jun 17, 2026

Flaky test: org.keycloak.testsuite.saml.SamlClientTest#testLoginWithOIDCClient #49985

Closed

edewit requested a review from vmuzikar June 17, 2026 10:00

shawkins requested changes Jun 17, 2026

View reviewed changes

edewit marked this pull request as ready for review June 17, 2026 18:12

edewit requested a review from a team as a code owner June 17, 2026 18:12

Copilot AI review requested due to automatic review settings June 17, 2026 18:12

edewit requested a review from a team as a code owner June 17, 2026 18:12

Copilot started reviewing on behalf of edewit June 17, 2026 18:13 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/guides/operator/installation.adoc Outdated

vmuzikar requested a review from shawkins June 19, 2026 11:40

shawkins previously approved these changes Jun 22, 2026

View reviewed changes

vmuzikar reviewed Jun 23, 2026

View reviewed changes

edewit dismissed shawkins’s stale review via e283ef4 June 23, 2026 09:47

Copilot AI review requested due to automatic review settings June 23, 2026 09:48

Copilot started reviewing on behalf of edewit June 23, 2026 09:48 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 23, 2026 10:53

Copilot started reviewing on behalf of edewit June 23, 2026 10:53 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 26, 2026 15:34

Copilot started reviewing on behalf of edewit June 26, 2026 15:35 View session

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Copilot started reviewing on behalf of edewit June 29, 2026 10:30 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

michalvavrik approved these changes Jun 29, 2026

View reviewed changes

vmuzikar reviewed Jun 29, 2026

View reviewed changes

edewit and others added 11 commits June 30, 2026 08:34

update documentation to expose multi-namespace install modes

af5ac26

fixes: keycloak#49037 Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

updated csv

ebccba8

also changed docs and ci to no longer mention/execute patching the csv Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

changed experimental to preview

3b24c6a

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

PR review commments

9eed02c

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Update docs/guides/operator/installation.adoc

fa4421b

Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Update docs/guides/operator/installation.adoc

22d7a21

Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

Potential fix for pull request finding

7dd12bc

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Erik Jan de Wit <edewit@redhat.com> Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

removed rbac reference

cd34e6b

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

web based installation

97c17a7

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

PR comments

b5fd686

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

merged clusterwide with kustomize

17bbe6e

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>

edewit force-pushed the multi-namespace branch from 2ce7f04 to 17bbe6e Compare June 30, 2026 06:45

vmuzikar reviewed Jun 30, 2026

View reviewed changes

Comment thread docs/guides/operator/installation.adoc Outdated

Comment thread docs/guides/operator/installation.adoc Outdated

shawkins reviewed Jun 30, 2026

View reviewed changes

Comment thread docs/documentation/release_notes/topics/26_7_0.adoc

shawkins previously approved these changes Jun 30, 2026

View reviewed changes

vmuzikar dismissed shawkins’s stale review via e50c6e6 June 30, 2026 16:48

Copilot AI review requested due to automatic review settings June 30, 2026 16:48

Copilot started reviewing on behalf of vmuzikar June 30, 2026 16:50 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread docs/guides/operator/installation.adoc Outdated

Cosmetic tweaks

0482c73

Signed-off-by: Václav Muzikář <vmuzikar@ibm.com>

vmuzikar force-pushed the multi-namespace branch from e50c6e6 to 0482c73 Compare June 30, 2026 17:04

vmuzikar approved these changes Jun 30, 2026

View reviewed changes

vmuzikar enabled auto-merge (squash) June 30, 2026 17:05

vmuzikar merged commit b1c293f into keycloak:main Jun 30, 2026
89 checks passed

edewit deleted the multi-namespace branch July 2, 2026 09:03

	@CSVMetadata.InstallMode(
	type = "AllNamespaces",
	supported = false
	)


		Approve the install plan if you are using manual approval, then verify that the Operator pod is running.

		If the Operator is already installed in single-namespace mode, you can switch to cluster-wide mode by removing `spec.targetNamespaces` from the OperatorGroup:


		==== Installing with OLM

		To install in `MultiNamespace` or `AllNamespaces` mode, create an OperatorGroup with the desired namespace selection, subscribe to the Operator, and approve the install plan.


		==== Installing with OLM

		To install in `AllNamespaces` mode, create an OperatorGroup without `spec.targetNamespaces`, subscribe to the Operator, and approve the install plan.


		A single {project_name} Operator can reconcile custom resources in all namespaces in the cluster. This avoids running one Operator per namespace while still allowing {project_name} instances to be deployed in separate namespaces.

		The Operator supports the standard OLM install modes:

Uh oh!

Conversation

edewit commented Jun 12, 2026

Uh oh!

edewit commented Jun 12, 2026

Uh oh!

vmuzikar left a comment

Choose a reason for hiding this comment

Uh oh!

edewit commented Jun 17, 2026

Uh oh!

shawkins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

shawkins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

vmuzikar commented Jun 25, 2026

Uh oh!

edewit commented Jun 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vmuzikar left a comment

Choose a reason for hiding this comment

Uh oh!