Emphasize using StatefulSet instead of Deployment

[mabartos]

Before reporting an issue

• [x] I have read and understood the above terms for submitting issues, and I understand that my issue may be closed without action if I do not follow them.

Area

operator

Describe the bug

In our docs, we explicitly do not say what Kubernetes primitive should be used for Keycloak deployment - either StatefulSet or Deployment. In some places, we even mention Deployment more, and then confusion happens in our community (same as: https://github.com/keycloak/keycloak/issues/39866)

Related to https://github.com/keycloak/keycloak/discussions/11763

Version

main

Regression

• [ ] The issue is a regression

Expected behavior

Users are aware of using StatefulSet as the Kubernetes primitive for Keycloak

Actual behavior

Users use Kubernetes Deployment and then face issues.

How to Reproduce?

...

Anything else?

No response

[keycloak-github-bot[bot]]

Due to the amount of issues reported by the community we are not able to prioritise resolving this issue at the moment.

If you are affected by this issue, upvote it by adding a :thumbsup: to the description. We would also welcome a contribution to fix the issue.

[mabartos]

Raised priority as this might be serious issue for some Keycloak installations/deployments.

[KyriosGN0]

hey @mabartos can i work on this? to make sure, the issue is about keycloak docs mentioning deployment as the k8s workload to use, as i don't see any ref in the operator specific docs

[mabartos]

@KyriosGN0 Yes, if you have time to look at it, please do.

to make sure, the issue is about keycloak docs mentioning deployment as the k8s workload to use, as i don't see any ref in the operator specific docs

Some sort of. AFAIK we don't explicitly state in the docs anything about the k8s Deployment. But we've seen that a lot of users uses k8s Deployment instead of the recommended StatefulSet as there might be several issues with deploying Keycloak as Deployment due to the embedded Infinispan.

We should emphasize more that the StatefulSet is the correct way how to proceed for now.

[shawkins]

As part of this issue we may also want to tweak or remove the lanugage around the db lock - it implies that it can be used to do simultaneous startup.

[MarcusDunn]

Would it be correct to say that if there's an external Infinispan, a deployment would be a valid way to deploy keycloak?

Edit: https://github.com/keycloak/keycloak/issues/39866#issuecomment-2911989989 It seems so.

~~If so, i~~Is this something the operator should handle? Deployments are considerably nicer to work with as compared to statefulsets and from my understanding should be preferred when possible. I would contribute this if it would be accepted.

[mabartos]

Would it be correct to say that if there's an external Infinispan, a deployment would be a valid way to deploy keycloak?

@MarcusDunn AFAIK, theoretically, it might be the case when you have the external Infinispan. However, it might show some other issues that we are not aware of.

Is this something the operator should handle? Deployments are considerably nicer to work with as compared to statefulsets and from my understanding should be preferred when possible. I would contribute this if it would be accepted.

I don't think we'd be able to support this in a short time. It'd need to be a different "mode" of the Operator that would need to possibly handle the Infinispan instances via the Infinispan Operator - or we'd need to document it in a big extent, which is probably not applicable ATM. And maintaining two modes of the Operator does not seem feasible due to our team capacity. It'd need to have a proper plan and compare all the benefits and tradeoffs of both modes.

cc: @pruivo @ryanemerson @ahus1 @vmuzikar @shawkins

[ahus1]

@MarcusDunn - there are currently two modes when there is an external Infinispan:

• When using Keycloak with the multi-site setup which is using an external Infinispan (which is only supported when you are running really in multi-AZ setup and are connecting for example two Keycloak clusters in two different Kubernetes Clusters)
• When using the "clusterless" setup, where also session information is stored in the external Infinispan, which is currently experimental.

With each of those setups, you need to setup Infinispan separately, as shown in the docs for example here: https://www.keycloak.org/high-availability/deploy-infinispan-kubernetes-crossdc

If you choose to deploy Keycloak without the Operator, you are free to use a deployment in those cases, and report back with your findings. A future version of the KC Operator could switch between Deployment and StatefulSet automatically depending on those features to be enabled. It would require some testing, we might already have an issue somewhere for that, still it hasn't made it to the top of the list of things to do.

Even if you would plan to contribute that to the KC Operator, you should check with the @keycloak/cloud-native team if they are willing to review it / maintain it in the main branch.

[ahus1]

It'd need to be a different "mode" of the Operator that would need to possibly handle the Infinispan instances via the Infinispan Operator

I thin this is out of scope, and would make this change rather big compare to "just" switching between deployment and stateful set. So I'd rather go with the docs of how to deploy an external ISPN as the next step.

[vmuzikar]

IMHO the ability to switch between Deployment and StatefulSet would add considerable amount of complexity to the Operator. Especially in terms of different behavioural nuances between the two (I can imagine bugs specific to one but not the other). Unless we'd have a very strong reason to add support for optional Deployment, -1 from me.