From be6f0bc52026f05048f304d78a00e5efc31dbe4e Mon Sep 17 00:00:00 2001 From: Stefan Guilhen Date: Thu, 14 Mar 2024 04:50:54 -0300 Subject: [PATCH] Add a section on the admin console partial import/export capability Closes #25490 Signed-off-by: Stefan Guilhen Signed-off-by: Alexander Schwartz Signed-off-by: andymunro <48995441+andymunro@users.noreply.github.com> Co-authored-by: Alexander Schwartz Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> --- docs/guides/server/importExport.adoc | 43 +++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/docs/guides/server/importExport.adoc b/docs/guides/server/importExport.adoc index f8ccc7a76f..75df679411 100644 --- a/docs/guides/server/importExport.adoc +++ b/docs/guides/server/importExport.adoc @@ -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. - \ No newline at end of file +== 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. + +