Backup / Export Keycloak Data

Run the following commands:

1. Prepare data directory for export:

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -- \
    sh -c 'rm -rf /tmp/keycloak-export'

2. Export data; note that this command does not complete by itself, it needs to be interrupted after it reports in the log that the data is exported and the server is started. This is a known issue with Keycloak.

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -it -- \
    sh /opt/jboss/keycloak/bin/ \
        -Dkeycloak.migration.action=export \
        -Dkeycloak.migration.provider=dir \
        -Dkeycloak.migration.dir=/tmp/keycloak-export \
        -Dkeycloak.migration.usersExportStrategy=DIFFERENT_FILES \
        -Dkeycloak.migration.realmName=kublr-ui \

3. Archive the exported files and download the to your client environment:

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -- \
    sh -c 'cd /tmp/keycloak-export && tar -c -f keycloak-export.tgz *'

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -- \
    cat /tmp/keycloak-export/keycloak-export.tgz > keycloak-export.tgz

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -- \
    sh -c 'rm -rf /tmp/keycloak-export'

After the commands complete, keycloak-export.tgz file should be available locally containing export files, e.g. kublr-ui-realm.json and kublr-ui-users-0.json.

You can adjust the export commands as necessary to export different realms or use different export parameters.

Refer to Keycloak documentation for more information about available options.

Import Keycloak Data

Data Import Planning

Keycloak supports different conflict resolution policies for imported objects.

It is recommended to use the safe "fail", or "skip" policies when importing Kublr realm objects to avoid disrupting authentication functionality.

After full import of Kublr realm data with "overwrite" policy it may be necessary reinitialize Kublr realm and refresh Kublr components JWKS keys as described in the corresponding solution.

It is possible to only import some categories of the realms objects and process the import data files before importing them.

For example the following simple jq script extracts only groups from the realm export file, so that only groups can be imported:

jq '{ "groups": .groups }' kublr-ui-realm.json > kublr-ui-groups.json

Similarly other categories of the realm data may be extracted and separately imported:

jq '{ "groups": .groups }' kublr-ui-realm.json > kublr-ui-groups.json

jq '{ "clients": .clients }' kublr-ui-realm.json > kublr-ui-clients.json

jq '{ "identityProviders": .identityProviders }' kublr-ui-realm.json > kublr-ui-identityProviders.json

jq '{ "roles": .roles }' kublr-ui-realm.json > kublr-ui-roles.json

jq '{ "roles": { "realm": .roles.realm }}' kublr-ui-realm.json > kublr-ui-roles-realm.json

jq '{ "roles": { "client": .roles.client }}' kublr-ui-realm.json > kublr-ui-roles-client.json

Unfortunately some objects can only be imported as a part of full realm import (for example user federation providers).

Review / Import via Keycloak UI

Keycloak export files may be imported or validated and reviewed in Keycloak UI in the "Management > Import / Export" section.

This method is convenient for validating the import data

Import via CLI

1. Prepare data directory for import and copy the import file:

kubectl exec -n kublr kcp-keycloak-0 -c keycloak -- \
    sh -c 'rm -rf /tmp/keycloak-import && mkdir -p /tmp/keycloak-import'

kubectl cp -c keycloak kublr-ui-realm.json kublr/kcp-keycloak-0:/tmp/keycloak-import

2. Run import process (adjust parameters as necessary):

The parameters that can be adjusted include:

  • the file name
  • the realm name
kubectl exec -n kublr kcp-keycloak-0 -c keycloak -it -- \
    sh /opt/jboss/keycloak/bin/ \
        -Dkeycloak.migration.action=import \
        -Dkeycloak.migration.provider=singleFile \
        -Dkeycloak.migration.file=/tmp/keycloak-import/kublr-ui-realm.json \
        -Dkeycloak.migration.strategy=IGNORE_EXISTING \
        -Dkeycloak.migration.realmName=kublr-ui \

3. Restart keycloak:

kubectl -n kublr delete pod

# OR with immediate restart

kubectl -n kublr delete pod \
  --force --grace-period=0


1. Keycloak UI shows an error during import: Error! javax.persistence.PersistenceException: org.hibernate.exception.DataException: could not execute statement

Starting with Keycloak 7 uploading scripts / JSON via UI may be disabled by default, which is indicated by the above error when attempting to import data via UI.

Use CLI import method, or enable JSON / script upload via UI by adding the following parameters to the Keycloak stateful set and restarting Keycloak:

        - name: keycloak
            - name: JAVA_OPTS
              value: >-

Reference Documentation