Keycloak 17 docker container : How to export/import realm? (import must be done on container startup)

With Keycloak 17 running in a docker container, how can we now export/import a realm ?
This was documented for the docker image based on Wildfly but it is no more documented for the docker imaged base on Quarkus.

Previously it was possible to export a realm using this command :

docker exec -it kc /opt/jboss/keycloak/bin/standalone.sh \
-Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=export \
-Dkeycloak.migration.provider=singleFile \
-Dkeycloak.migration.realmName=my_realm \
-Dkeycloak.migration.usersExportStrategy=REALM_FILE \
-Dkeycloak.migration.file=/tmp/my_realm.json

which as you can see is very specific to the Wildfly implementation (call to the Wildfly standalone.sh script).

And the import was done using this command when starting the container :

docker run -e KEYCLOAK_USER=<USERNAME> -e KEYCLOAK_PASSWORD=<PASSWORD> \
    -e KEYCLOAK_IMPORT=/tmp/example-realm.json -v /tmp/example-realm.json:/tmp/example-realm.json jboss/keycloak

How can it now be achieved with the Quarkus based image ?

1 Like

There are import and export commands available for kc.sh.
From the command line:

$ ./kc.sh import --help
Import data from a directory or a file.

Usage:

kc.sh import [OPTIONS]

Import data from a directory or a file.

Options:

--dir <path>         Set the path to a directory where files will be created with the exported data.
--file <path>        Set the path to a file that will be created with the exported data.
-h, --help           This help message.
--override <false>   Set if existing data should be skipped or overridden. Default: true.
--realm <realm>      Set the name of the realm to export

$ ./kc.sh export --help
Export data from realms to a file or directory.

Usage:

kc.sh export [OPTIONS]

Export data from realms to a file or directory.

Options:

--dir <path>         Set the path to a directory where files will be created with the exported data.
--file <path>        Set the path to a file that will be created with the exported data.
-h, --help           This help message.
--realm <realm>      Set the name of the realm to export
--users <strategy>   Set how users should be exported. Possible values are: skip, realm_file,
                       same_file, different_files. Default: different_files.
--users-per-file <number>
                     Set the number of users per file. It?s used only if --users=different_files.
                       Default: 50.

I’m also wondering where (or why) the docs are gone and not being updated.

FYI: I just created a discussion thread on the repo: Export/Import of realm data (JSON) · Discussion #10229 · keycloak/keycloak · GitHub

2 Likes

Hello,
thanks for the answer :wink:
I understand how it will be possible to do the export once the container is running by calling kc.sh export through docker exec.

But the import of the realm needs to be done automatically when the container is started (which was the case when passing KEYCLOAK_IMPORT environment variable to the docker run command), so calling manually kc.sh import through docker exec is not a solution

is there any update on this? on 17.0.1 seems to not work

Auto-import of realms will be available again with 18.x

2 Likes

Does it still use the KEYCLOAK_IMPORT environnement variable ?
I don’t see it listed in the documentation (Running Keycloak in a container - Keycloak)

Note: Would be great to have an “Updated on” date on the documentation pages :wink:

No. There is option --import-realm for start command. See Importing a Realm during Startup in Importing and Exporting Realms - Keycloak

1 Like

Please, if you crosspost your questions in various forums/boards, add a link to the initial post/question.

Since --import-realm skips import operation if realm already exists, what is the recommended way to do incremental updates to an existing realm (Specially using a container distribution mode)?

1 Like

Hi, any thoughts about previous question?

There‘s no tooling ootb from the Keycloak project.
Community provides something useful here: GitHub - adorsys/keycloak-config-cli: Import YAML/JSON-formatted configuration files into Keycloak - Configuration as Code for Keycloak.

1 Like

Thanks, I’ll check this!

Hi, what about export, it seems that export is no more supported, we used to export data with a command-line similar to this:
docker run -it --rm
–name authenticate
–net keycloak-network
–entrypoint=’’
-v “${NEW_CONFIGURATION}”:/config.json
-e KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
-e KC_DB_USERNAME=keycloak
-e KC_DB_PASSWORD=password

/busybox/sh /opt/keycloak/bin/kc.sh
start --hostname-strict=false --http-enabled=true
-Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=singleFile
-Dkeycloak.migration.file=/config.json
-Dkeycloak.migration.realmName=${REALM_NAME}

Is it still supposed to work ?

As mentioned several times before, trying to search and read the guides/docs seems to be hard… sigh

2 Likes

Hi Dasniko, thank you for pointing out the documentation, unfortunately for me it is not working, in fact keycloak tries to connect to the database with user “sa” despite the KC_DB_USERNAME environment variable:
HHH000342: Could not obtain connection to query metadata: org.postgresql.util.PSQLException: FATAL: password authentication failed for user “sa”

Is this a known issue or am I missing something ?

I finally managed to make it work, sorry for the disturbing.

how did you do it can you please share. I am facing a similar issue while importing.

Hi, the main issue I believe was that the admin account was needed to import and was not created (fresh install + import).
All you need to do is carefully review your script making sure that all variables don’t have any typo and that KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD have correct values.
For example for import this can be:
docker run -it --rm \
–entrypoint=’’ \
-v “$KEYCLOAK_CONFIGURATION_JSON”:/config.json \
-e LOG_LEVEL=INFO \
-e HOST_IP=127.0.0.1 \
-e KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak \
-e KC_DB_USERNAME=sa \
-e KC_DB_PASSWORD=password \
-e KEYCLOAK_ADMIN=${ADMNIN} \
-e KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PWD} \
myimageofkeycloak \
/busybox/sh /opt/keycloak/bin/kc.sh \
import --file /config.json

HTH.

1 Like

Hi,

Sorry to come back and bother you, but the solution I found is not satisfying as it uses well-known login/password for the database connection.
I’m using keycloak in cluster environment, so I first build the docker image specifying --db=postgres option.
But when I want to run the “import” command, it does not allow me to specify the db command line option, it complains about unsupported options.
When I run the “import” command without db command line option it complains about:
‘Could not obtain connection to query metadata: org.postgresql.util.PSQLException: FATAL: password authentication failed for user “sa”’
Is this a bug in keycloak ?

I have to mention that i am using clustered keycloak in a distroless environment, so I can’t use shell commands, I have to launch java with its full list of arguments. Also the admin UI is not bundled in the application which leaves me with the only option to import realms from the command line.

Any help appreciated.

I have been using the import feature with Keycloak 18.

You either:

  • prepare a custom image where you ran the kc.sh build as a dockerfile step and set ENTRYPOINT ["/opt/keycloak/bin/kc.sh","start", "--import-realm"]
    Your realm files should be at /opt/keycloak/data/import/
  • Use the official image with a custom entrypoint script where you kc.sh build and them kc.sh start --import-realm