mirror/keycloak
1
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2026-01-06 06:49:53 -06:00
Code Issues Packages Projects Releases Wiki Activity

fix: further refining logic and docs around import/export (#40906)

Browse Source 
* fix: further refining logic and docs around import/export

closes: #40874

Signed-off-by: Steve Hawkins <shawkins@redhat.com>

* Update importExport.adoc

* Apply suggestions from code review

Co-authored-by: Alexander Schwartz <alexander.schwartz@gmx.net>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>

---------

Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>
Co-authored-by: Alexander Schwartz <alexander.schwartz@gmx.net>
This commit is contained in:
Steven Hawkins
2025-07-23 03:34:35 -04:00
committed by GitHub
parent bd676ea845
commit 8bc141d529
2 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/guides/server/importExport.adoc
View File

@@ -8,17 +8,22 @@
In this {section}, you are going to understand the different approaches for importing and exporting realms using JSON files.
== Import / Export Commands
[NOTE]
====
Exporting and importing into single files can produce large files which may run the export / import process out of memory. If your database contains more than 50,000 users, export to a directory and not a single file.
The default count of users per file and per transaction is fifty, but you may use a much larger value if desired.
The default count of users per file is fifty, but you may use a much larger value if desired.
The `import` and `export` commands are essentially server launches that exit before bringing up the full server. They are not currently designed to be run from the same machine as a running server instance, which may result in port or other conflicts.
It is recommended that all {project_name} nodes are stopped prior to using the `kc.[sh|bat] export` command. This ensures that the results will have no consistency issues with user or realm modifications during the export.
It is required that all {project_name} nodes are stopped prior to performing an `kc.[sh|bat] import` command with the override option.
The command does not attach to the cache cluster, so overwriting a realm will lead to inconsistent caches in the cluster, which then would show and use inconsistent or outdated information. Instead of overwriting a realm with the import command, consider using the Admin API to delete realms that need to be overwritten prior to running the import.
====
== Providing options for database connection parameters
=== Providing options for database connection parameters
When using the `export` and the `import` commands below, {project_name} needs to know how to connect to the database where the information about realms, clients, users and other entities is stored.
As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file.
@@ -32,7 +37,7 @@ When doing this, remove the build time options from the command line and keep on
NOTE: if you do not use `--optimized` keep in mind that an `import` or `export` command may implicitly create or update an optimized build for you - if you are running the command from the same machine as a server instance, this may impact the next start of your server.
== Exporting a Realm to a Directory
=== Exporting a Realm to a Directory
To export a realm, you can use the `export` command. Your {project_name} server instance must not be started when invoking this command.
@@ -44,7 +49,7 @@ To export a realm to a directory, you can use the `--dir <dir>` option.
When exporting realms to a directory, the server is going to create separate files for each realm being exported.
=== Configuring how users are exported
==== Configuring how users are exported
You are also able to configure how users are going to be exported by setting the `--users <strategy>` option. The values available for this
option are:
@@ -61,7 +66,7 @@ If you are exporting users using the `different_files` strategy, you can set how
<@kc.export parameters="--dir <dir> --users different_files --users-per-file 100"/>
== Exporting a Realm to a File
=== Exporting a Realm to a File
To export a realm to a file, you can use the `--file <file>` option.
@@ -69,19 +74,19 @@ To export a realm to a file, you can use the `--file <file>` option.
When exporting realms to a file, the server is going to use the same file to store the configuration for all the realms being exported.
== Exporting a specific realm
=== Exporting a specific realm
If you do not specify a specific realm to export, all realms are exported. To export a single realm, you can use the `--realm` option as follows:
<@kc.export parameters="[--dir|--file] <path> --realm my-realm"/>
== Import File Naming Conventions
=== Import File Naming Conventions
When you export a realm specific file name conventions are used, which must also be used for importing from a directory or import at startup. The realm file to be imported must be named <realm name>-realm.json.
Regular and federated user files associated with a realm must be named <realm-name>-users-<file number>.json and <realm-name>-federated-users-<file number>.json. Failure to use this convention will result in errors or
user files not being imported.
== Importing a Realm from a Directory
=== Importing a Realm from a Directory
To import a realm, you can use the `import` command. Your {project_name} server instance must not be started when invoking this command.
@@ -98,13 +103,13 @@ you can set the `--override` option as follows:
By default, the `--override` option is set to `true` so that realms are always overridden with the new configuration.
== Importing a Realm from a File
=== Importing a Realm from a File
To import a realm previously exported in a single file, you can use the `--file <file>` option as follows:
<@kc.import parameters="--file <file>"/>
== Using Environment Variables within the Realm Configuration Files
=== Using Environment Variables within the Realm Configuration Files
You are able to use placeholders to resolve values from environment variables for any realm configuration.
@@ -135,11 +140,13 @@ realms and potentially lose state between server restarts.
To re-create realms you should explicitly run the `import` command prior to starting the server.
NOTE: The server will not fully start until the imports are complete.
== Importing and Exporting by using the Admin Console
You can also import and export a realm using the Admin Console. This functionality is
different from the other CLI options described in previous sections because the Admin Console offers only the capability to
_partially_ export a realm. In this case, the current realm settings, along with some resources like clients,
different from the other CLI options described in previous sections because the Admin Console requires the cluster to be online.
The Admin Console also offers only the capability to _partially_ export a realm. In this case, the current realm settings, along with some resources like clients,
roles, and groups, can be exported. The users for that realm _cannot_ be exported using this method.
NOTE: When using the Admin Console export, the realm and the selected resources are always exported to a file
@@ -176,7 +183,7 @@ Skip:: Skip the duplicate resources without aborting the process
Overwrite:: Replace the existing resources with the ones being imported.
NOTE: The Admin Console partial import can also import files created by the CLI `export` command. In other words, full exports created
by the CLI can be imported by using the Admin Console. If the file contains users, those users will also be available for importing into the
by the CLI can be imported by using the Admin Console. If the file contains users, those users will also be available for importing into the
current realm.
</@tmpl.guide>

11
operator/src/main/java/org/keycloak/operator/controllers/KeycloakRealmImportController.java
View File

@@ -129,8 +129,8 @@ public class KeycloakRealmImportController implements Reconciler<KeycloakRealmIm
status.addStartedMessage("Import Job started");
} else if (oldStatus.getSucceeded() != null && oldStatus.getSucceeded() > 0) {
if (!lastReportedStatus.isDone()) {
Log.info("Job finished performing a rolling restart of the deployment");
rollingRestart(realmCR, client); // could be based upon a hash annotation on the deployment instead
// no need to restart Keycloak as we're only importing new realms and are not overwriting existing realms
Log.info("Job finished");
}
status.addDone();
} else if (oldStatus.getFailed() != null && oldStatus.getFailed() > 0) {
@@ -147,11 +147,4 @@ public class KeycloakRealmImportController implements Reconciler<KeycloakRealmIm
return Optional.ofNullable(existingDeployment.getStatus()).map(StatefulSetStatus::getReadyReplicas).orElse(0);
}
private void rollingRestart(KeycloakRealmImport realmCR, KubernetesClient client) {
client.apps().statefulSets()
.inNamespace(realmCR.getMetadata().getNamespace())
.withName(realmCR.getSpec().getKeycloakCRName())
.rolling().restart();
}
}