Repository navigation
Replies: 8 comments 10 replies
|
This is related to the Separate configuration of underlying Quarkus from main configuration proposal. |
|
@DGuhr @pedroigor FIY |
|
cc. @vmuzikar |
|
One potential thing we could also do to make it easier to configure Keycloak is to include all configuration options commented out. This file can easily be generated from the CLI options. As an example the This idea is somewhat unrelated to this proposal though, and could be applied if we decide to stick with the current approach. It could also be named differently, for example |
|
I would keep a separate file. Ideally, we should have within the However, I'm not sure how much value this additional file would bring given that we already have the same properties from our help (now using a more consistent format) as well as from our site. I would leave this change, at least for now. |
|
I think it is not a good idea to have commented out values for all possible or recommended settings in However, being able to dump the effective configuration to the console, e.g. like mavens effective pom, can be quite useful. |
|
With regard to defaults the defaults used in Keycloak should not depend on the configuration file. Essentially an empty configuration file should result in the default configuration, and a configuration file is only used to change the value to a non-default value. This would make it easier with regard to upgrades, as the defaults can be changed without having to worry about the default existing in a configuration file copied from a previous version. |
|
What I always liked from tools is the capability to print out a config file with all internal defaults you could build upon. |
|
Wonder if that could be covered by #9597 (comment) including the default value. That way you can just uncomment the values that you want to have "sticky". |
|
Sorry didn't catched that one. Yes LGTM |
|
The arguments are very strong and your proposal seems to make things simpler while helping to provide a clear separation between our configuration and what we consider unsupported/advanced config. W.r.t. to configuration profiles, the support we have for specifying a configuration file should be enough. W.r.t. to the default configuration, we kind of have that already so that the conf file is really user-specific and does not expose any built-in configuration. One thing I was thinking though is that we kind of have a mechanism already for resolving a property from its CLI format. I need to take a closer look at it but it should be quite trivial to adapt the distribution to the proposal herein discussed. |
|
@stianst I still see value in supporting configuration profiles. If we remove that and you have a set of common configuration options, you would need to duplicate them in different files. IMO, people should be able to use whatever approach works better for them. |
|
I always thought the way profiles where defined within a single config file rather messy and hard to understand how to create, and also hard to read and understand the config file. It is probably very infrequent that people will want different profiles at all, and when they do there's probably very little in common. Profiles to me just adds an unnecessary complexity/confusion, and having two separate config files is just much cleaner and easier to reason about than the complexity of the profiles. End of the day options bring confusion, and a less opinionated approach, it brings more to document, testing, as well as more for the user to learn and understand. In general I think we should avoid options, and especially alternatives, as much as possible. |
Completely agree 🔝 Simplicity, especially in configuration, always pays off, and removing lever and knobs is highly beneficial for the user's understanding. |
|
I'm not sure about how complex profiles are but I see the reasoning about disabling them for users to avoid choices and force what we think is the best (fewer options simpler choices and more clarity). |
Config Key FormatI think that dot-based setting keys in a properties file are a better canonical representation for configurable settings than CLI arguments. How about adjusting the format of CLI config keys to look like the properties config keys?
Current: Proposal: Example for CLI Arg: Example for key in properties file: Example for key in yaml: Example for environment variable: Profile supportI think having support for configuration profiles is quite important as it allows to keep I think it's sufficient to have profile support in config files only, since CLI options or Env variables are IMHO usually Config files are rather useful when you have a lot of Keycloak customizations or SPIs with dedicated configuration. Multiple config filesAn alternative to profiles could be support for specifying multiple config files via the CLI. This approach would enable easy composition of file based configurations. |
|
I am a bit undecided about the profiles, both ways are possible and have their pros and cons. I definitely like Thomas's proposal of deriving the names from the config properties. |
|
@thomasdarimont By using the In regards to the option format, using dots in CLI is not what you usually see in CLIs. The idea is to also make the format less Java-oriented. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
The Quarkus distribution can be configured through:
keycloak.properties)There is two issues with this that could be improved:
3 different configuration key formats
There are 3 different formats for the configuration key, for example:
db.pool.initial-sizedb-pool-initial-sizeKC_DB_POOL_INITIAL_SIZEThis results in having to understand 3 different formats, and translate between them when needed. However, there is a issue with the file format as it can only be translated from, not to.
As an example File format can be translated to CLI format by replacing
.with-. However, it is not possible to translate from CLI format to File, as replacing-with.would result indb.pool.initial.size, which doesn't matchdb.pool.initial-size.In the CLI help and the documentation the
CLIoption is extensively used, as that is the most convenient way to document, as well as the easiest approach to try out new configuration, and as the CLI format can't be translated to the File format, the only way to find the key required in the configuration files would be to look it up in a table in the documentation, or perhaps with a tool in the CLI.An example from the work in progress documentation for configuring a database in the Quarkus distribution:
It would be much more convenient if one format was removed, and the configuration key was the same in the CLI argument as in the configuration file, so the above example would be:
db-pool-initial-sizedb-pool-initial-sizeKC_DB_POOL_INITIAL_SIZEJava-based configuration file format
Most Java developers are familiar with standard Java property files. Although, even for Java developers that can be confusing as the traditionally used
ISO-8859-1encoding rather than the much more internationalization friendlyutf-8encoding.However, non-Java developers are not familiar with the Java properties format, which is an issue as Keycloak should be friendly and easy to use regardless of what programming language you are familiar with.
There's a few options to choose from here:
YAML and TOML adds some structure to the configuration file, but at the cost that they are harder to create initially and are not translatable easily to/from CLI arguments and Environment variables. As Keycloak supports configuration through both CLI and Env it is important that configuration is kept simple, and does not require a complex structure. This means the additional overhead of YAML or TOML is really not needed, and we should stick with a basic config file.
The proposal here is to have a basic configuration file (
keycloak.conf) that is utf-8 encoded, and is simply a list of configuration options following the style from the CLI:Configuration files like these are common-place in Unix systems, and should be easy to understand by anyone new to Keycloak.
Configuration profiles
One side-effect of this is that we would loose the support for profiles. Profiles can be convenient, but comes at the cost of more complex configuration file formats, which are hard to write, as well as understand. Profiles also overlap with the ability to specify the configuration file.
Profiles are also not supported when using CLI or Env to configure Keycloak, which can be confusing as only 1 out of 3 configuration sources support profiles.
Profiles as a feature directly doesn't make all that much sense, as it will be very uncommon that the same Keycloak installation has different sets of configuration, and if this is required it can more easily be achieved by having two separate configuration files.
However, profiles are also used by Keycloak to select between developer and production modes. It may not be needed to support configuration files at all in developer mode, and simply ignore the configuration files when
start-devis used. Alternatively, a separate config file can be used for this purposekeycloak-dev.conf.All reactions