diff --git a/docs/guides/server/importExport.adoc b/docs/guides/server/importExport.adoc index 965fde242fc..ee07e2fceb8 100644 --- a/docs/guides/server/importExport.adoc +++ b/docs/guides/server/importExport.adoc @@ -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 ` 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 ` 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 --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 ` option. @@ -69,19 +74,19 @@ To export a realm to a file, you can use the `--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] --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.json. Regular and federated user files associated with a realm must be named -users-.json and -federated-users-.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 ` option as follows: <@kc.import parameters="--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. diff --git a/operator/src/main/java/org/keycloak/operator/controllers/KeycloakRealmImportController.java b/operator/src/main/java/org/keycloak/operator/controllers/KeycloakRealmImportController.java index e84b706f7b8..771b23deb34 100644 --- a/operator/src/main/java/org/keycloak/operator/controllers/KeycloakRealmImportController.java +++ b/operator/src/main/java/org/keycloak/operator/controllers/KeycloakRealmImportController.java @@ -129,8 +129,8 @@ public class KeycloakRealmImportController implements Reconciler 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