Improve documentation of managed resources #1186
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,6 +5,35 @@ | |
| [](https://codecov.io/gh/adorsys/keycloak-config-cli) | ||
| [](https://github.com/adorsys/keycloak-config-cli/blob/main/LICENSE.txt) | ||
|
|
||
| # Table of Contents | ||
| - [Config Files](#config-files) | ||
| - [Variable Substitution](#variable-substitution) | ||
| - [Supported Substitutions](#supported-substitutions) | ||
| - [Logging](#logging) | ||
| - [JSON Logging Support](#json-logging-support) | ||
| - [Log Level](#log-level) | ||
| - [Supported Features](#supported-features) | ||
| - [Compatibility with Keycloak](#compatibility-with-keycloak) | ||
| - [Build this Project](#build-this-project) | ||
| - [Run Integration Tests](#run-integration-tests) | ||
| - [Run this Project](#run-this-project) | ||
| - [Docker](#docker) | ||
| - [Helm](#helm) | ||
| - [Configuration](#configuration) | ||
| - [CLI Options / Environment Variables](#cli-options--environment-variables) | ||
| - [Keycloak Options](#keycloak-options) | ||
| - [Import Options](#import-options) | ||
| - [Spring Boot Options](#spring-boot-options) | ||
| - [Perform Release](#perform-release) | ||
| - [Commercial Support](#commercial-support) | ||
|
|
||
| - [How keycloak-config-cli Tracks Resources](#how-keycloak-config-cli-tracks-resources) | ||
| - [Default Behavior](#default-behavior) | ||
| - [Customizing Resource Management](#customizing-resource-management) | ||
| - [Impact on User Federations](#impact-on-user-federations) | ||
| - [Example Configuration](#example-configuration) | ||
|
|
||
|
|
||
| # keycloak-config-cli | ||
|
|
||
| keycloak-config-cli is a Keycloak utility to ensure the desired configuration state for a realm based on a JSON/YAML file. The format of the JSON/YAML file based on the export realm format. Store and handle the configuration files inside git just like normal code. A Keycloak restart isn't required to apply the configuration. | ||
|
|
@@ -63,13 +92,28 @@ keycloak-config-cli supports logging in JSON format. To enable, set `SPRING_PROF | |
|
|
||
| ## Log level | ||
|
|
||
| ## Log Level Configuration | ||
|
|
||
| The following options allow you to configure the logging levels for different components of the `keycloak-config-cli`. Adjust these settings to control the verbosity of logs generated during execution. | ||
|
|
||
| | CLI Option | ENV Variable | Description | Default | | ||
| |-------------------------------------|---------------------------------|--------------------------------------------------------------------------------------|-------------------------------| | ||
| | `--logging.level.root` | `LOGGING_LEVEL_ROOT` | Define the root log level. This setting applies to all loggers unless overridden. | `info` | | ||
| | `--logging.level.keycloak-config-cli` | `LOGGING_LEVEL_KEYCLOAKCONFIGCLI` | Log level for keycloak-config-cli components. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. | Value of `logging.level.root` | | ||
| | `--logging.level.http` | `LOGGING_LEVEL_HTTP` | Log level for HTTP requests between keycloak-config-cli and Keycloak. | Value of `logging.level.root` | | ||
| | `--logging.level.realm-config` | `LOGGING_LEVEL_REALMCONFIG` | If set to `trace`, logs detailed information about realm configuration, including **sensitive information**. | Value of `logging.level.root` | | ||
|
|
||
| ### Example Usage | ||
|
|
||
| To set the logging level for the Keycloak configuration CLI to debug, you can use the following command: | ||
|
|
||
| ```shell | ||
| java -jar ./target/keycloak-config-cli.jar \ | ||
| --logging.level.keycloak-config-cli=debug \ | ||
| --keycloak.url=http://localhost:8080 \ | ||
| --keycloak.user=admin \ | ||
| --keycloak.password=admin123 \ | ||
| --import.files.locations=./contrib/example-config/moped.json | ||
| # Supported features | ||
|
|
||
| See: [docs/FEATURES.md](./docs/FEATURES.md) | ||
|
|
@@ -295,3 +339,34 @@ git push --follow-tags | |
| # Commercial support | ||
|
|
||
| Checkout https://adorsys.com/en/products/keycloak-config-cli/ for commercial support. | ||
|
|
||
|
There was a problem hiding this comment. please refer to the https://github.com/adorsys/keycloak-config-cli/blob/main/docs/MANAGED.md for resource management |
||
| # Resource Management in keycloak-config-cli | ||
|
|
||
| ## How keycloak-config-cli Tracks Resources | ||
|
|
||
| - keycloak-config-cli (kcc) stores information about resources it creates as realm attributes in the Keycloak database. | ||
| - This tracking mechanism allows kcc to manage these resources in subsequent runs. | ||
|
|
||
| ## Default Behavior | ||
|
|
||
| - By default, kcc will delete and recreate resources that it initially created in previous runs. | ||
| - This ensures that the Keycloak configuration always matches the state defined in your configuration files. | ||
|
|
||
| ## Customizing Resource Management | ||
|
|
||
| - The `import.managed.*` family of properties allows you to customize this behavior. | ||
| - Setting these properties to `no-delete` will prevent kcc from deleting resources, even if they're no longer present in your configuration files. | ||
|
|
||
| ## Impact on User Federations | ||
|
|
||
| - This behavior applies to user federations (such as LDAP and Active Directory). | ||
| - When a user federation is deleted and recreated, all users created by that federation will also be deleted. | ||
| - This includes associated data like offline tokens. | ||
|
|
||
| ## Example Configuration | ||
|
|
||
| To prevent deletion of specific resources: | ||
|
|
||
| ```properties | ||
| import.managed.authentication-flow=no-delete | ||
| import.managed.user-federation=no-delete | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please the closing of this code block is not clear.