ENDOC-427 add Backing up and restoring Keycloak #427
Conversation
|  | ||
|
|
||
| ::: Note | ||
| If we are using a different environment, with a different hostname, we should import only users or set the If for resource exists to Skip |
There was a problem hiding this comment.
@nshaw Not sure what to make of this.
There was a problem hiding this comment.
"if we are" -> "if you are" & "we should" -> "you should"
"only users" -> "users only"
format "If for resource exists" (pretty sure that tag/option is labeled slightly differently ??)
There was a problem hiding this comment.
"set the flag for 'If a resource existstoSkip`"
There was a problem hiding this comment.
I think "only users" emphasizes the users as opposed to "users only" emphasizes the subject 'you', so left as is.
There was a problem hiding this comment.
it should technically be placed after; i looked it up :P i can point you the references and we can discuss in the style meeting? not a big deal tho.
There was a problem hiding this comment.
I think as an adverb, it is technically ok here? But we can discuss :)
There was a problem hiding this comment.
no worries, this is grammatically correct! into the weeds but something i was curious about
| sidebarDepth: 2 | ||
| --- | ||
|
|
||
| # Backing up and Restoring Keycloak |
| # Backing up and Restoring Keycloak | ||
|
|
||
|
|
||
| This tutorial describes how to backup and restore an active Entando Identity Management Keycloak instance when you need to migrate or restore the realm to another environment. |
There was a problem hiding this comment.
"...when you need to restore or migrate the realm to..." -- switch order of "restore" and "migrate" to fix grammar
is this sentence redundant? is there a difference between instance and realm?
There was a problem hiding this comment.
Or simplify to "This tutorial describes how to backup an active Entando Identity Management Keycloak instance and restore it in another environment."
There was a problem hiding this comment.
I think realm is the actual data of the instance
| 1. Login to the original Entando Keycloak server for which you just created the backup. | ||
| 2. From the left sidebar, go to Import. | ||
|
|
||
| 3. Click `Select file` button and `upload` the JSON file from the keycloak-backup directory. You will see the following page: |
There was a problem hiding this comment.
the Select file
should the term keycloak-backup be formatted (parentheses, backticks, etc.) to identify it as an entity and the directory name?
| -Dkeycloak.migration.file=/tmp/export/entando-prod-realm.json | ||
| ``` | ||
| 5. If there are no errors, press Ctrl+C to stop the process. | ||
| 6. Type `exit` to go back to the VM layer. |
There was a problem hiding this comment.
"to return to" sounds a bit cleaner
There was a problem hiding this comment.
Or "to close the bash shell in the pod"
| A Keycloak instance running on Entando with a database management system (DBMS) in the backend. This procedure will not work with an embedded database. | ||
|
|
||
| ## Create a Backup of Keycloak Realm | ||
| 1. From the command line, get the pod name of the Keycloak server you need to backup. |
There was a problem hiding this comment.
"wish to backup" to deemphasize urgency and highlight the versatility of this action ??
There was a problem hiding this comment.
Maybe also note this - "In a quickstart environment the pod name will begin with quickstart-kc-server-deployment-"
|
|
||
| ## Create a Backup of Keycloak Realm | ||
| 1. From the command line, get the pod name of the Keycloak server you need to backup. | ||
| 2. Shell into your VM and execute this command to connect to the pod. |
There was a problem hiding this comment.
Let's change this a bit. In a local env, you shell into a VM, but in a managed K8s you'll just use kubectl directly. -> "Use kubectl to start a bash shell in the pod."
| mkdir -p /tmp/export | ||
| ``` | ||
|
|
||
| 4. Run the following script to retrieve all the data and save it to a JSON file in the export directory. A new Keycloak server will run on a different port (offset=200) to avoid conflicts with the original Entando Keycloak instance. |
There was a problem hiding this comment.
"retrieve all the data" sounds a bit awkward and unspecified...
There was a problem hiding this comment.
"to retrieve all the data" -> "to retrieve the data for the entando realm"
| ``` | ||
| 5. If there are no errors, press Ctrl+C to stop the process. | ||
| 6. Type `exit` to go back to the VM layer. | ||
| 7. Execute this command to copy the realm data file to the proper location. |
There was a problem hiding this comment.
location. -> location:
|  | ||
|
|
||
| ::: Note | ||
| If we are using a different environment, with a different hostname, we should import only users or set the If for resource exists to Skip |
There was a problem hiding this comment.
"if we are" -> "if you are" & "we should" -> "you should"
"only users" -> "users only"
format "If for resource exists" (pretty sure that tag/option is labeled slightly differently ??)
| ``` | ||
| ## Import the Keycloak Realm | ||
| 1. Login to the original Entando Keycloak server for which you just created the backup. | ||
| 2. From the left sidebar, go to Import. |
There was a problem hiding this comment.
should Import be formatted with backticks, etc.?
| # Backing up and Restoring Keycloak | ||
|
|
||
|
|
||
| This tutorial describes how to backup and restore an active Entando Identity Management Keycloak instance when you need to migrate or restore the realm to another environment. |
There was a problem hiding this comment.
Or simplify to "This tutorial describes how to backup an active Entando Identity Management Keycloak instance and restore it in another environment."
| A Keycloak instance running on Entando with a database management system (DBMS) in the backend. This procedure will not work with an embedded database. | ||
|
|
||
| ## Create a Backup of Keycloak Realm | ||
| 1. From the command line, get the pod name of the Keycloak server you need to backup. |
There was a problem hiding this comment.
Maybe also note this - "In a quickstart environment the pod name will begin with quickstart-kc-server-deployment-"
|
|
||
| ## Create a Backup of Keycloak Realm | ||
| 1. From the command line, get the pod name of the Keycloak server you need to backup. | ||
| 2. Shell into your VM and execute this command to connect to the pod. |
There was a problem hiding this comment.
Let's change this a bit. In a local env, you shell into a VM, but in a managed K8s you'll just use kubectl directly. -> "Use kubectl to start a bash shell in the pod."
| mkdir -p /tmp/export | ||
| ``` | ||
|
|
||
| 4. Run the following script to retrieve all the data and save it to a JSON file in the export directory. A new Keycloak server will run on a different port (offset=200) to avoid conflicts with the original Entando Keycloak instance. |
There was a problem hiding this comment.
"to retrieve all the data" -> "to retrieve the data for the entando realm"
| -Dkeycloak.migration.file=/tmp/export/entando-prod-realm.json | ||
| ``` | ||
| 5. If there are no errors, press Ctrl+C to stop the process. | ||
| 6. Type `exit` to go back to the VM layer. |
There was a problem hiding this comment.
Or "to close the bash shell in the pod"
|  | ||
|
|
||
| ::: Note | ||
| If we are using a different environment, with a different hostname, we should import only users or set the If for resource exists to Skip |
There was a problem hiding this comment.
"set the flag for 'If a resource existstoSkip`"
|
|
||
| ::: Note | ||
| If we are using a different environment, with a different hostname, we should import only users or set the If for resource exists to Skip | ||
| ::: |
There was a problem hiding this comment.
Might need a final statement on the successful completion of the import?
There was a problem hiding this comment.
@jyunmitch what do you think of adding this to 6.3.2 as well? I can't think of anything preventing us.
No description provided.