1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/links.adoc" as links>
6
title="Importing and Exporting Realms"
7
summary="An overview about how to import and export realms">
9
In this {section}, you are going to understand the different approaches for importing and exporting realms using JSON files.13
Exporting and importing into single files can produce large files, so if your database contains more than 500 users, export to a directory and not a single file.
14
Using a directory performs better as the directory provider uses a separate transaction for each "page" (a file of users).
15
The default count of users per file and per transaction is fifty.
16
Increasing this to a larger number leads to an exponentially increasing execution time.
19
== Providing options for database connection parameters
21
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.22
As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file.
23
Use the `--help` command line option for each command to see the available options.
25
Some of the configuration options are build time configuration options.
26
As default, {project_name} will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter.28
If you have built an optimized version of {project_name} with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time.29
When doing this, remove the build time options from the command line and keep only the runtime options.
31
== Exporting a Realm to a Directory
33
To export a realm, you can use the `export` command. Your {project_name} server instance must not be started when invoking this command.35
<@kc.export parameters="--help"/>
37
To export a realm to a directory, you can use the `--dir <dir>` option.
39
<@kc.export parameters="--dir <dir>"/>
41
When exporting realms to a directory, the server is going to create separate files for each realm being exported.
43
=== Configuring how users are exported
45
You are also able to configure how users are going to be exported by setting the `--users <strategy>` option. The values available for this
48
* *different_files*: Users export into different json files, depending on the maximum number of users per file set by `--users-per-file`. This is the default value.
50
* *skip*: Skips exporting users.
52
* *realm_file*: Users will be exported to the same file as the realm settings. For a realm named "foo", this would be "foo-realm.json" with realm data and users.
54
* *same_file*: All users are exported to one explicit file. So you will get two json files for a realm, one with realm data and one with users.
56
If you are exporting users using the `different_files` strategy, you can set how many users per file you want by setting the `--users-per-file` option. The default value is `50`.
58
<@kc.export parameters="--dir <dir> --users different_files --users-per-file 100"/>
60
== Exporting a Realm to a File
62
To export a realm to a file, you can use the `--file <file>` option.
64
<@kc.export parameters="--file <file>"/>
66
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.
68
== Exporting a specific realm
70
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:
72
<@kc.export parameters="[--dir|--file] <path> --realm my-realm"/>
74
== Importing a Realm from a Directory
76
To import a realm, you can use the `import` command. Your {project_name} server instance must not be started when invoking this command.78
<@kc.import parameters="--help"/>
80
After exporting a realm to a directory, you can use the `--dir <dir>` option to import the realm back to the server as follows:
82
<@kc.import parameters="--dir <dir>"/>
84
When importing realms using the `import` command, you are able to set if existing realms should be skipped, or if they should be overridden with the new configuration. For that,
85
you can set the `--override` option as follows:
87
<@kc.import parameters="--dir <dir> --override false"/>
89
By default, the `--override` option is set to `true` so that realms are always overridden with the new configuration.
91
== Importing a Realm from a File
93
To import a realm previously exported in a single file, you can use the `--file <file>` option as follows:
95
<@kc.import parameters="--file <file>"/>
97
== Importing a Realm during Startup
99
You are also able to import realms when the server is starting by using the `--import-realm` option.
101
<@kc.start parameters="--import-realm"/>
103
When you set the `--import-realm` option, the server is going to try to import any realm configuration file from the `data/import` directory. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored.
105
NOTE: For the {project_name} containers, the import directory is `/opt/keycloak/data/import`107
If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating
108
realms and potentially loose state between server restarts.
110
To re-create realms you should explicitly run the `import` command prior to starting the server.
112
Importing the `master` realm is not supported because as it is a very sensitive operation.
114
=== Using Environment Variables within the Realm Configuration Files
116
When importing a realm at startup, you are able to use placeholders to resolve values from environment variables for any realm configuration.
118
.Realm configuration using placeholders
122
"realm": "${r"${MY_REALM_NAME}"}",128
In the example above, the value set to the `MY_REALM_NAME` environment variable is going to be used to set the `realm` property.