Configuration command optional in Keycloak.X

[Pedro Igor]

Hi,

When configuring the server, users must run the `config` command when changing any build/static property [1] such as those related to the database.

Although this additional step is crucial to perform a number of optimizations to achieve an optional runtime, it causes some confusion and unexpected behavior if you are not aware of how configuration works.

That said, in order to improve the experience when configuring the server, I would like to propose that we decide at startup whether or not the configuration and build/static properties changed and then run the `config` command transparently.

I'm not sure about the impact of making this more transparently in terms of startup and footprint so, to be safe, I think we could provide an additional property to bypass this "automatic configuration" of the server.

Wdyt?

[1] https://github.com/keycloak/keycloak-community/blob/master/design/keycloak.x/configuration.md#config-command

[Pedro Igor Craveiro e Silva]

One thing I forgot to mention ...

Keycloak.X tries to bring to Keycloak important aspects from cloud-native applications such as immutability.

The `config` command is basically the tool users have to create an immutable server image that is fully optimized and more secure. Similar to a container image.

The problem here is more related to the usability for those trying out Keycloak so that we keep some consistency on how people are used to configure and run the server (without an additional step). However, this is not what we want for production-grade deployments where you should always consider running the configuration step prior to running or when building a container image.

--
You received this message because you are subscribed to a topic in the Google Groups "Keycloak Dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/keycloak-dev/YQAZ0hfHWzw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to keycloak-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/aa69fd47-c4a8-42c5-8ed4-828abd1dcca1n%40googlegroups.com.

[Thomas Darimont]

Hello Pedro,

I think it's fine to "infer" the config state and run the "config" command dynamically. This makes it easier for new users of the Keycloak.X distribution.

A few notes around that:

1) I think we should print a log message, which shows that the "config" command was inferred, with a hint that running the "config command" beforehand is recommended for optimized performance in actual deployments.

2) Which changes actually need the config command? Just static config changes, or also adding quarkus extensions or keycloak extensions?

Cheers,

Thomas

You received this message because you are subscribed to the Google Groups "Keycloak Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to keycloak-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/CA%2B3s2iTsLz%2BH%3DEmiXGojBszR7%3DUHWLbd6uBcL7V93xXMc%2B0eRQ%40mail.gmail.com.

[Thomas Darimont]

Looks like this is the branch for the "automatic re-augmentation" feature you're currently working on: https://github.com/pedroigor/keycloak/tree/KEYCLOAK-19306 

[Pedro Igor Craveiro e Silva]

Hey Thomas,

Yeah, that is the branch I'm using to PoC some ideas. 

The approach I'm using there is still under testing due to the fact that I'm leveraging a specific behavior of Quarkus classloading to make it possible to reload classes after re-augmentation. All that within the same JVM.

In regards to your suggestions:

* I think the message when automatic re-augmentation is pretty much aligned with your proposal.

* Whenever a static property changes the re-augmentation will happen

One of the limitations there is the fact that it does not consider deployment of providers.

One of the main cons of this first approach is the fact that we are using an unsupported API and behavior from Quarkus. As you know, Quarkus favors immutability and what I'm doing there is somewhat breaking this aspect even though there is an API that does exactly what we need. I had a chat with the Quarkus team about it and the behavior I want is not really supported and subject to break as I'm using some internal constructs (they are public but not supposed to be used by regular applications).

I really like the approach from that PR and I don't think it breaks immutability due to the fact that it exists only to improve developer and getting started experience. For production, you would always rely on running the `config` command prior to starting the server or creating container images.

There are other approaches we could consider, but they rely on updating `kc.sh`. IMO, the main drawback of using scripts is that we would need to run two JVMs (one for checking/running re-augmentation and another for starting the server). And that could affect our time to start. Plus the fact that we need to support scripts for linux and windows.

Perhaps we could only run automatic re-aug when starting in dev mode so that this behavior is specific for developing and testing the server. I don't know. This should at least pass a message like:

* Do whatever you want in dev mode, but don't complain about start-up time and footprint. Do not use it for benchmarking.

* Consider using the config command for optimized images and deploying the server into production. 

Regards.

Pedro Igor

To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/cc9181f8-e41e-46a0-b4df-595e62ef644an%40googlegroups.com.

[Thomas Darimont]

Hello Pedro,

If this re-augmentation feature is only possible in dev-mode, then it's fine. You mentioned that the mechanism you are currently using is not "officially" supported but necessary - do the quarkus guys offer an alternative solution?

I need to dig deeper into how quarkus works internally, but all other quarkus projects that run in dev-mode need to do something similar as we want to do, don't they?

> There are other approaches we could consider, but they rely on updating `kc.sh`. ... Plus the fact that we need to support scripts for linux and windows.

In my Java projects I tend to replace OS specific scripts with simple Java launcher files. Since Java 10 it's possible to run single-source java programs without compilation.

How about something like this:

$ cat bin/kc.java  
public class kc {
  public static void main(String[] args) {
    System.out.println("Starting Keycloak.X...");
  }
}

$ java bin/kc.java  --start-dev
Starting Keycloak.X...

You might need to copy some small functions here and there, but you can get quite far with a plain Java app nowadays - btw. I usually don't use a library on the classpath here.

With this I don't need to worry about OS specific script differences since I can rely on plain Java APIs. Additionally, a big plus is, that you can (remote) debug a launcher script :) try that with a bash shell script :D

I use this pattern with great success in some of my projects, e.g.:

https://github.com/thomasdarimont/keycloak-project-example/blob/main/start.java

https://github.com/thomasdarimont/keycloak-project-example/tree/main/bin

Cheers,

Thomas

[Pedro Igor Craveiro e Silva]

On Thu, Sep 23, 2021 at 10:19 AM Thomas Darimont <thomas....@googlemail.com> wrote:

Hello Pedro,

If this re-augmentation feature is only possible in dev-mode, then it's fine. You mentioned that the mechanism you are currently using is not "officially" supported but necessary - do the quarkus guys offer an alternative solution?

I need to dig deeper into how quarkus works internally, but all other quarkus projects that run in dev-mode need to do something similar as we want to do, don't they?

There is no alternative because that is not something applications should be doing. We are talking here about an application already built and distributed rather than coding it. Our dev mode (perhaps the name is misleading) is basically a method for starting a less strict server for trying out its capabilities. Strict in a sense that you are not forced to set up a database, TLS, etc.

 

> There are other approaches we could consider, but they rely on updating `kc.sh`. ... Plus the fact that we need to support scripts for linux and windows.

In my Java projects I tend to replace OS specific scripts with simple Java launcher files. Since Java 10 it's possible to run single-source java programs without compilation.

How about something like this:

$ cat bin/kc.java  
public class kc {
  public static void main(String[] args) {
    System.out.println("Starting Keycloak.X...");
  }
}

$ java bin/kc.java  --start-dev
Starting Keycloak.X...

You might need to copy some small functions here and there, but you can get quite far with a plain Java app nowadays - btw. I usually don't use a library on the classpath here.

With this I don't need to worry about OS specific script differences since I can rely on plain Java APIs. Additionally, a big plus is, that you can (remote) debug a launcher script :) try that with a bash shell script :D

I use this pattern with great success in some of my projects, e.g.:

https://github.com/thomasdarimont/keycloak-project-example/blob/main/start.java

https://github.com/thomasdarimont/keycloak-project-example/tree/main/bin

Yeah, there is also JBang. In our case, I'm not sure if it makes sense to use JBang but looking at your examples, it seems to be a good fit.

I never considered using source-file mode and it could help to reduce the effort to run on different OSs and perform some actions before creating the server process such as running re-augmentation. As we are using Java, we should be able to calculate the need for re-augmentation similarly we are doing in that main class.

I guess we would run the server in a separate process and possibly have 2 processes for a single server start and redirect output/error from the child (server) to the parent (source-file). 

Would you be able to PoC something around that? I'm wondering how it would affect our startup when using process builder api ...

The changes in scripts should be minimal and using source-file mode should still require 2 JVMs (differently than scripts, both always running during the server lifecycle). But I'm +1 to PoC and see how it goes ... 

[Pedro Igor Craveiro e Silva]

Btw, created https://github.com/keycloak/keycloak/discussions/8468.

[Thomas Darimont]

Yeah, JBang is a much more powerful version of what I'm doing - but requires JBang to be installed first (or shipped with Keycloak).

Here is a small PoC for a Launcher (Supervisor) that can (re)start an application with some parameterization.

https://github.com/thomasdarimont/keycloak-java-launcher

In the example I run in fact 2 JVMs (1 launcher, and 2 child / app process).

Would you be available for a discussion? I'd have time tomorrow.

Thanks for the write-up.

Cheers,

Thomas

[Pedro Igor Craveiro e Silva]

Sure, that time we used to meet when doing UP work for me.

[Thomas Darimont]

Works for me too. Just send me an invite :)

[Pedro Igor Craveiro e Silva]

FYI, the original approach that was relying on an internal (and unsupported) API from Quarkus had some issues. Mainly in regards to keeping JVM updated with changes to custom providers deployed at the `providers` directory. At the end, this approach was too risky and full of variables that could impact the server behavior.

I have updated that PR (which is now in upstream as a baseline) to use scripts instead. As expected, the changes are very minimal and are enough to keep a "normal" usage of Quarkus to automatically re-configure the server when running in dev mode (our start-dev command). The maintenance burden is still low ...

I think it is also simpler and more efficient than switching to using source-code to run the server.

Please, let me know if the approach we are taking is indeed helping to provide a better experience. As we discussed, this is not yet related to dev experience which goes beyond what we are initially doing here.

Regards.

Pedro Igor