mirror of
https://github.com/keycloak/keycloak.git
synced 2026-05-26 13:50:48 +00:00
Say export is not backup in the guide
Export isn't suitable for backup for a number of reasons, mention that in the guide, and tidy up some existing notes. Closes #46796 Signed-off-by: James Hewitt <james.hewitt@uk.ibm.com> Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com> Co-authored-by: Alexander Schwartz <alexander.schwartz@ibm.com>
This commit is contained in:
@@ -8,19 +8,27 @@
|
||||
|
||||
In this {section}, you are going to understand the different approaches for importing and exporting realms using JSON files.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The import / export process has limitations to be used as a backup and restore mechanism.
|
||||
Consistency of an export is not guaranteed unless all {project_name} nodes are stopped prior to running the export.
|
||||
Exported data does not include user and admin events, persisted sessions, workflow state or revoked tokens.
|
||||
====
|
||||
|
||||
== Import / Export Commands
|
||||
|
||||
The `import` and `export` commands are server launches that perform the import or export, then exit before bringing up the full server.
|
||||
|
||||
[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 is fifty, but you may use a much larger value if desired.
|
||||
The `import` and `export` commands are not designed to be run from the same machine as a running server instance, which may result in port or other conflicts.
|
||||
|
||||
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 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.
|
||||
It is required that all {project_name} nodes are stopped prior to using the `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
|
||||
@@ -74,6 +82,12 @@ 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.
|
||||
|
||||
[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.
|
||||
====
|
||||
|
||||
=== 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:
|
||||
@@ -82,8 +96,8 @@ If you do not specify a specific realm to export, all realms are exported. To ex
|
||||
|
||||
=== 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
|
||||
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
|
||||
@@ -125,7 +139,7 @@ You are able to use placeholders to resolve values from environment variables fo
|
||||
|
||||
In the example above, the value set to the `MY_REALM_NAME` environment variable is going to be used to set the `realm` property.
|
||||
|
||||
NOTE: there are currently no restrictions on what environment variables may be referenced. When environment variables are used to convey sensitive information, take care to ensure placeholders references do not inappropriately expose sensitive environment variable values.
|
||||
NOTE: There are currently no restrictions on what environment variables may be referenced. When environment variables are used to convey sensitive information, take care to ensure placeholders references do not inappropriately expose sensitive environment variable values.
|
||||
|
||||
== Importing a Realm during Startup
|
||||
|
||||
|
||||
Reference in New Issue
Block a user