KEYCLOAK-10319 Long-term Keycloak Operator architecture #54

slaskawi · 2020-03-23T14:44:24Z

This Pull Request contains a High Level Architecture overview of Keycloak Operator and its long-term vision.

Better preview is available here: https://github.com/slaskawi/keycloak-community/blob/Operator-high-level-architecture/design/operator-architecture.asciidoc

davidffrench

Excellent overview @slaskawi . Some very small feedback/edit suggestions from me.

design/operator-architecture.asciidoc

stianst

This doesn't really cover what I had in mind with regards to a vision for the operator. It's missing some details on things like:

Personas and use-cases - describe related personas and use-cases for the personas
More details on being opinionated and providing a high-level usability, rather than low-level toggles
How we will avoid feature creep - I can easily see lots of request for small things to be added, which in the end results in a complicated beast rather than a simple to use opinionated
Avoiding logic in the operator - a bit more expanding on the section on where features should be implemented to describe that advanced logic doesn't belong in the operator
Section capability levels and how we plan to properly address them

design/operator-architecture.asciidoc

stianst · 2020-03-25T09:56:32Z

Why .asciidoc when all other designs are in markdown? Would be good to just keep it all in one format

slaskawi · 2020-03-27T11:01:57Z

Why .asciidoc when all other designs are in markdown? Would be good to just keep it all in one format

@stianst I wanted to use a block with a feature implementation example. This functionality is not available in Markdown. To me, Asciidoc formats documents much better and we also use it in other projects, such as Keycloak Web and Keycloak Documentation.

I'd rather keep things consistent here. If you want to propose changing the format that's fine, but otherwise stick to what is already done. Consistency matters.

slaskawi · 2020-03-27T19:26:59Z

Personas and use-cases - describe related personas and use-cases for the personas

@stianst Added usecases

More details on being opinionated and providing a high-level usability, rather than low-level toggles

@stianst added "a way to deliver a high level usability rather than low-level toggles" to the manifesto.

How we will avoid feature creep - I can easily see lots of request for small things to be added, which in the end results in a complicated beast rather than a simple to use opinionated

@stianst To me, this sounds exactly the (although in different words) than the previous point.

Avoiding logic in the operator - a bit more expanding on the section on where features should be implemented to describe that advanced logic doesn't belong in the operator

@stianst Added "the thinnest possible layer, with the least possible logic, on top of Keycloak Container and Keycloak Server." to the manifesto.

Section capability levels and how we plan to properly address them

@stianst I can add you a dedicated section, but let me push the use cases first. Maybe that will be enough for you.

slaskawi · 2020-03-27T19:30:44Z

@davidffrench @stianst @mposolda Thank you gentlemen for the review. I addressed your comments and pushed a new version.

pedroigor · 2020-03-27T20:07:46Z

@slaskawi Does make sense to list the CRDs used by the Operator? I found one quick reference to the Keycloak CRD but not others currently supported by the operator.

Considering they play an important role, maybe a specific section about CRDs could make this part of the architecture more clear. Especially if provided:

Their lifecycle. For instance, those implicitly managed by the operator such as the Keycloak CRD and the others representing the state that map to entities in Keycloak such as User, Realm Client, etc.
Limitations and Use-Cases. Is it feasible to manage 100 realms + 1000 users + 100 clients using the operator. Considering Openshift, how that would work when the user is managing the cluster through the Openshift Console ? Is the operator going to support all the configuration we have in Keycloak for these entities?
Reconciliation. How reconciliation works in regards to CRDs. What happens when updating a CRD or the corresponding entity in Keycloak? Would the operator keep both sides in sync all the time ?
Relationship between CRDs. How the operator knows that a User Jown CRD is mapped to a Realm My Realm CRD?

slaskawi · 2020-03-30T07:36:44Z

Does make sense to list the CRDs used by the Operator? I found one quick reference to the Keycloak CRD but not others currently supported by the operator.

@pedroigor This is coming in updated documentation, see keycloak/keycloak-documentation#796

Their lifecycle. For instance, those implicitly managed by the operator such as the Keycloak CRD and the others representing the state that map to entities in Keycloak such as User, Realm Client, etc.

@pedroigor I don't want to be too specific about those CRs in this architecture vision as I see them as an implementation detail. However, this is the second time I see someone asking for a list of CRs, so let me add it.

Limitations and Use-Cases. Is it feasible to manage 100 realms + 1000 users + 100 clients using the operator. Considering Openshift, how that would work when the user is managing the cluster through the Openshift Console ? Is the operator going to support all the configuration we have in Keycloak for these entities?

@pedroigor I see those are Keycloak limitations (not necessarily the Operator). Perhaps we should have a Keycloak long term vision somewhere and put this there? What do you think, @stianst ?

Reconciliation. How reconciliation works in regards to CRDs. What happens when updating a CRD or the corresponding entity in Keycloak? Would the operator keep both sides in sync all the time ?

@pedroigor I believe this has been covered in Operator SDK manual, so repeating it here doesn't make much sense (to me).

Relationship between CRDs. How the operator knows that a User Jown CRD is mapped to a Realm My Realm CRD?

@pedroigor That's a good point. Let me mention here the way it has been implemented.

slaskawi · 2020-03-30T08:05:17Z

@pedroigor Pushed new version.

davidffrench · 2020-03-30T14:44:15Z

This looks good to me @slaskawi

design/operator-architecture.asciidoc

maleck13 · 2020-04-01T09:25:59Z

design/operator-architecture.asciidoc

+
+We envision Keycloak Operator as:
+
+* an opinionated way of installing and maintaining Keycloak installation on both Kubernetes and OpenShift.


should upgrades be called out or is that covered under maintaining?

nvm I see it is covered

stianst

See inline. Perhaps it would also be good to cover a section on CRs vs admin console. One/two-way sync, etc.

stianst · 2020-04-01T09:03:51Z

design/operator-architecture.asciidoc

+
+* **Status**: Draft #1
+* **JIRA**: https://issues.redhat.com/browse/KEYCLOAK-10319[KEYCLOAK-10319]
+* **Source of the images**: https://docs.google.com/presentation/d/13N5ClXXXcxKjXgor72rUdtMBN07_GneUkhTTwBsy_tE/edit?usp=sharing[Google Slides]


Remove this link as it is not public

stianst · 2020-04-01T09:05:18Z

design/operator-architecture.asciidoc

+
+* an opinionated way of installing and maintaining Keycloak installation on both Kubernetes and OpenShift.
+* a way to deliver a high level usability rather than low-level toggles
+* an example of a recommended way of installing, configuring, managing custom extension and themes.


Not sure I understand this line.

stianst · 2020-04-01T09:10:11Z

design/operator-architecture.asciidoc

+* Cluster Admin - a Kubernetes/OpenShift administrator
+* Service Infrastructure Admin - an administrator who provisions Keycloak Operator as well as Keycloak Cluster
+* Realm Admin - a Keycloak administrator, who can provision realms (both using Custom Resources and Admin UI)
+* Secured Application - either configured by an engineering team (using self registration feature) or by Keycloak Admin (or Keycloak Realm Admin).


I'm not fully convinced about these personas. Looking at the doc I sent you there are:

Cluster Admin

Service Infrastructure Admin

Service Admin

Service Consumer

Service End User

I think those are better personas then those you've created. From my perspective the description in context of the Keycloak Operator would be something like:

Cluster Admin - Provisions cluster resources. Basically, installs the Keycloak Operator.

Service Infrastructure Admin - Provisions the managed services. Basically, creates the Keycloak CR.

Service Admin - Manages the Realm. Basically, create the KeycloakRealm CR, but can also manage it through the Keycloak admin console

Service Consumer - Application developers. Basically, creates the KeycloakClient CR, but can also create clients through other means (admin console, client registration cli, etc.)

Service End User - Application users. Not sure there are any use-cases for these in this context, but worth mentioning anyways

stianst · 2020-04-01T09:06:58Z

design/operator-architecture.asciidoc

+* Realm Admin - a Keycloak administrator, who can provision realms (both using Custom Resources and Admin UI)
+* Secured Application - either configured by an engineering team (using self registration feature) or by Keycloak Admin (or Keycloak Realm Admin).
+
+The use cases we defined are based on Operatr Capability Model:


Operator, not Operatr

stianst · 2020-04-01T09:11:06Z

design/operator-architecture.asciidoc

+|Cluster Admin |Full Lifecycle| Configure Storage Class for Local Backups| Yes
+
+|Service Infrastructure Admin |Basic Install | Install Keycloak Operator | Yes
+|Service Infrastructure Admin |Basic Install | Install and manage Keycloak installation | Yes


Install and manage Keycloak installation seems a bit broad. What does it cover?

stianst · 2020-04-01T09:31:00Z

design/operator-architecture.asciidoc

+|Secured Application |Autopilot | Provide stable response time despite the load| No
+|====
+
+## History


We should just remove the History section - this is irrelevant information.

stianst · 2020-04-01T09:32:21Z

design/operator-architecture.asciidoc

+
+1. Keycloak Server needs to provide a JSON log based formatter.
+2. Keycloak Container needs to expose an environment variable, that could be switching on to use JSON formatting
+3. Keycloak Operator needs to expose proper configuration on Custom Resource level enabling JSON log formatting.


Shouldn't the Operator actually be opinionated here and just use JSON logging since that is the recommended on OpenShift/Kubernetes to have a common/parsable logging format?

stianst · 2020-04-01T09:35:59Z

design/operator-architecture.asciidoc

+
+image::img/Keycloak-operator-components.png[Keycloak Operator components]
+
+When Keycloak Operator spins up Keycloak installation, it creates:


Should make it a bit more clear in the list what types the things below are. For example keycloak-postgres is listed twice, once it doesn't say what type it is, then in the second it says in the description it's a service. Then for keycloak-discovery it more clearly says it's a Service. I would use the format: name type - description for everything

stianst · 2020-04-01T09:36:40Z

design/operator-architecture.asciidoc

+
+When Keycloak Operator spins up Keycloak installation, it creates:
+
+* `keycloak-db-secret` - used to store database username, password and other properties, such as external address (if used).


I do find it a bit weird that the external address for the DB is stored within a secret ;)

stianst · 2020-04-01T09:37:38Z

design/operator-architecture.asciidoc

+When Keycloak Operator spins up Keycloak installation, it creates:
+
+* `keycloak-db-secret` - used to store database username, password and other properties, such as external address (if used).
+* `credentials-<<CR Name>>` - Admin user credentials to log into Keycloak installation


Can you elaborate on this one? I don't understand what this is used for.

stianst · 2020-04-01T09:46:08Z

Please change format to markdown to make this consistent with everything else.

lellis32 · 2020-04-08T12:05:52Z

@slaskawi hey there, I'm working on a project where I'm considering using the keycloak operator as a component. In my use case, I think it would be useful to be able to add and update Identity/User Storage Providers via CRDs. Just wondering, would something like that be out of the scope of this project? I mainly just want a way to easily add additional authentication pieces, each bundled with its relevant keycloak configuration, to a big sso system in k8s. And extending this operator to handle those type of CRDs is one idea I had, and doesn't seem terribly hard for me to do, but that could be overkill. Thanks and great job!

chlunde · 2020-07-14T11:53:45Z

design/operator-architecture.asciidoc

+* an opinionated way of installing and maintaining Keycloak installation on both Kubernetes and OpenShift.
+* a way to deliver a high level usability rather than low-level toggles
+* an example of a recommended way of installing, configuring, managing custom extension and themes.
+* the thinnest possible layer, with the least possible logic, on top of Keycloak Container and Keycloak Server.


I think I understand what you mean, but this could also be interpreted as just dumping the exported config into map[string]string.

Do you envision being able to set up and configure keycloak just by reading the documentation/CRD and creating a CRD, instead doing the setup in the UI and exporting the configuration (including the "defaults" that are included in the export)?

Our CRDs reflect Keycloak resources. A good example is RealmRepresentation JSON payload and KeycloakRealm CRD. They are very similar and, in the long-term, should be the same.

So it is perfectly doable to configure Keycloak purely through CRDs (without touching the UI).

slaskawi force-pushed the Operator-high-level-architecture branch from 27ffd58 to 4c8251d Compare March 24, 2020 10:24

slaskawi marked this pull request as ready for review March 24, 2020 10:27

davidffrench reviewed Mar 24, 2020

View reviewed changes

stianst self-assigned this Mar 24, 2020

stianst requested changes Mar 25, 2020

View reviewed changes

design/operator-architecture.asciidoc Show resolved Hide resolved

design/operator-architecture.asciidoc Outdated Show resolved Hide resolved

design/operator-architecture.asciidoc Outdated Show resolved Hide resolved

slaskawi force-pushed the Operator-high-level-architecture branch from 4c8251d to 74315bd Compare March 27, 2020 19:29

KEYCLOAK-10319 Long-term Keycloak Operator architecture

a8631dc

slaskawi force-pushed the Operator-high-level-architecture branch from 74315bd to a8631dc Compare March 30, 2020 07:40

mposolda reviewed Mar 30, 2020

View reviewed changes

design/operator-architecture.asciidoc Show resolved Hide resolved

maleck13 reviewed Apr 1, 2020

View reviewed changes

stianst reviewed Apr 1, 2020

View reviewed changes

This was referenced Apr 20, 2020

Adds kustomize. keycloak/keycloak-operator#166

Closed

KEYCLOAK-13634 Externalize images keycloak/keycloak-operator#165

Merged

chlunde reviewed Jul 14, 2020

View reviewed changes

slaskawi closed this Dec 1, 2023


		We envision Keycloak Operator as:

		* an opinionated way of installing and maintaining Keycloak installation on both Kubernetes and OpenShift.


		image::img/Keycloak-operator-components.png[Keycloak Operator components]

		When Keycloak Operator spins up Keycloak installation, it creates:


		When Keycloak Operator spins up Keycloak installation, it creates:

		* `keycloak-db-secret` - used to store database username, password and other properties, such as external address (if used).

KEYCLOAK-10319 Long-term Keycloak Operator architecture #54

KEYCLOAK-10319 Long-term Keycloak Operator architecture #54

Uh oh!

Conversation

slaskawi commented Mar 23, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidffrench left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stianst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stianst commented Mar 25, 2020

Uh oh!

slaskawi commented Mar 27, 2020 • edited by stianst Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slaskawi commented Mar 27, 2020

Uh oh!

slaskawi commented Mar 27, 2020

Uh oh!

pedroigor commented Mar 27, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slaskawi commented Mar 30, 2020

Uh oh!

slaskawi commented Mar 30, 2020

Uh oh!

davidffrench commented Mar 30, 2020

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stianst left a comment

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!

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!

stianst commented Apr 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lellis32 commented Apr 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

slaskawi commented Mar 23, 2020 •

edited

Loading

slaskawi commented Mar 27, 2020 •

edited by stianst

Loading

pedroigor commented Mar 27, 2020 •

edited

Loading

stianst commented Apr 1, 2020 •

edited

Loading

lellis32 commented Apr 8, 2020 •

edited

Loading