Add a section on the admin console partial import/export capability

Closes #25490

Signed-off-by: Stefan Guilhen <sguilhen@redhat.com>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>
Signed-off-by: andymunro <48995441+andymunro@users.noreply.github.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
This commit is contained in:
Stefan Guilhen 2024-03-14 04:50:54 -03:00 committed by GitHub
parent 970a78fe7a
commit be6f0bc520
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -127,4 +127,45 @@ When importing a realm at startup, you are able to use placeholders to resolve v
In the example above, the value set to the `MY_REALM_NAME` environment variable is going to be used to set the `realm` property.
</@tmpl.guide>
== 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,
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
named `realm-export.json`. Also, all sensitive values like passwords and client secrets will be masked with `+*+` symbols.
To export a realm using the Admin Console, perform these steps:
. Select a realm.
. Click *Realm settings* in the menu.
. Point to the *Action* menu in the top right corner of the realm settings screen, and select *Partial export*.
+
A list of resources appears along with the realm configuration.
. Select the resources you want to export.
. Click *Export*.
NOTE: Realms exported from the Admin Console are not suitable for backups or data transfer between servers.
Only CLI exports are suitable for backups or data transfer between servers.
WARNING: If the realm contains many groups, roles, and clients, the operation may cause the server to be
unresponsive to user requests for a while. Use this feature with caution, especially on a production system.
In a similar way, you can import a previously exported realm. Perform these steps:
. Click *Realm settings* in the menu.
. Point to the *Action* menu in the top right corner of the realm settings screen, and select *Partial import*.
+
A prompt appears where you can select the file you want to import. Based on this file, you see the resources you can import along with the realm settings.
. Click *Import*.
You can also control what {project_name} should do if the imported resource already exists. These options exist
* `Fail import` - aborts the import.
* `Skip` - skips the duplicate resources without aborting the process
* `Overwrite` - replaces 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
current realm.
</@tmpl.guide>