206 lines
No EOL
9.4 KiB
Text
206 lines
No EOL
9.4 KiB
Text
|
|
// MOVED TO SEPARATE UPGRADE GUIDE!
|
|
// Add Keycloak migration changes to upgrading/topics/keycloak/changes.adoc
|
|
|
|
|
|
== Migration from older versions
|
|
|
|
To upgrade to a new version of Keycloak first download and install the new version of Keycloak. Once the new version
|
|
is installed migrate the config files, database, keycloak-server.json, providers, themes and applications to the new applications.
|
|
|
|
This chapter contains some general migration details which are applicable to all versions. There are instructions for
|
|
migration that is only applicable to a specific release. If you are upgrading from a very old version you need to go
|
|
through all intermediate version specific migration.
|
|
|
|
It's highly recommended that you backup your database prior to upgrading Keycloak.
|
|
|
|
Migration from a candidate release (CR) to a Final release is not supported. We do however recommend that you test
|
|
migration for a CR so we can resolve any potential issues before the Final is released.
|
|
|
|
=== Migration of config files using migration scripts
|
|
As part of your migration, you should use your old versions of config files `standalone.xml`, `standalone-ha.xml`, and/or `domain.xml`.
|
|
These files typically contain configuration that is unique to your own environment. So, the first thing to do as part
|
|
of a migration is to copy those files to the new Keycloak server installation, replacing the default versions.
|
|
|
|
If migrating from Keycloak version 2.1.0 or older, you should also copy `keycloak-server.json` to `standalone/configuration`
|
|
and/or `domain/configuration`.
|
|
|
|
There will be configuration in those config files that pertains to Keycloak, which will need to be upgraded. For that,
|
|
you should run one or more of the appropriate upgrade scripts. They are `migrate-standalone.cli`, `migrate-standalone-ha.cli`,
|
|
`migrate-domain-standalone.cli` and `migrate-domain-clustered.cli`.
|
|
|
|
The server should not be running when you execute a migration script.
|
|
|
|
.Example for running migrate-standalone.cli
|
|
[source]
|
|
----
|
|
$ .../bin/jboss-cli.sh --file=migrate-standalone.cli
|
|
----
|
|
|
|
Note that for upgrading domain.xml, there are two migration scripts, `migrate-domain-standalone.cli` and
|
|
`migrate-domain-clustered.cli`. These scripts migrate separate profiles within your domain.xml that were
|
|
originally shipped with Keycloak. If you have changed the name of the profile there is a variable near
|
|
the top of the script that you will need to change.
|
|
|
|
If you are migrating `keycloak-server.json`, this will also be migrated as needed. If you prefer,
|
|
you can migrate `keycloak-server.json` beforehand using the instructions in the next section.
|
|
|
|
One thing to note is that the migration scripts only work for Keycloak versions 1.8.1 forward. If migrating an older
|
|
version you will need to manually upgrade your config files to at least be 1.8.1 compliant.
|
|
|
|
Lastly, you may want to examine the contents of the scripts before running. They show exactly what will be changed
|
|
for each version. They also have values at the top of the script that you may need to change based on your
|
|
environment.
|
|
|
|
=== Migrate and convert keycloak-server.json
|
|
If you ran one of the migration scripts from the previous section then you have probably already migrated
|
|
your keycloak-server.json. This section is kept here for reference. If you prefer, you can follow the
|
|
instructions in this section before running the migration scripts above.
|
|
|
|
You should copy `standalone/configuration/keycloak-server.json` from the old version to make sure any configuration changes you've done are added to the new installation.
|
|
The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another.
|
|
|
|
Keycloak is moving away from the use of keycloak-server.json. For this release, the server will still work
|
|
if this file is in `standalone/configuration/keycloak-server.json`, but it is highly recommended that
|
|
you convert to using standalone.xml, standalone-ha.xml, or domain.xml for configuration. We may soon remove
|
|
support for keycloak-server.json.
|
|
|
|
To convert your keycloak-server.json, you will use a jboss-cli operation called `migrate-json`.
|
|
It is recommended that you run this operation while the server is not running.
|
|
|
|
The `migrate-json` operation assumes you are migrating with an xml configuration file from an old version. For example,
|
|
you should not try to migrate your keycloak-server.json to a standalone.xml file that already contains <spi> and <theme>
|
|
tags under the keycloak subsystem. Before migration, your keycloak subsystem should look like the one below:
|
|
|
|
.standalone.xml
|
|
[source,xml]
|
|
----
|
|
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
|
|
<web-context>auth</web-context>
|
|
</subsystem>
|
|
----
|
|
|
|
The jboss-cli tool is discussed in detail in link:{installguide_link}[{installguide_name}].
|
|
|
|
==== migrate-json in Standalone Mode
|
|
|
|
For standalone, you will issue the `migrate-json` operation in `embed` mode without
|
|
the server running.
|
|
|
|
.Standalone keycloak-server.json migration
|
|
[source]
|
|
----
|
|
$ .../bin/jboss-cli.sh
|
|
[disconnected /] embed-server --server-config=standalone.xml
|
|
[standalone@embedded /] /subsystem=keycloak-server/:migrate-json
|
|
----
|
|
The `migrate-json` operation will look for your keycloak-server.json file in
|
|
the `standalone/configuration` directory. You also have the option of using
|
|
the `file` argument as shown in the domain mode example below.
|
|
|
|
==== migrate-json in Domain Mode
|
|
|
|
For a domain, you will stop the Keycloak server and
|
|
issue the `migrate-json` operation against the running domain controller.
|
|
If you choose not to stop the Keycloak server, the operation will still work,
|
|
but your changes will not take affect until the Keycloak server is restarted.
|
|
|
|
Domain mode migration requires that you use the `file` parameter to upload your
|
|
keycloak-server.json from a local directory. The example below shows connecting
|
|
to localhost. You will need to substitute the address of your domain controller.
|
|
|
|
.Domain mode keycloak-server.json migration
|
|
[source]
|
|
----
|
|
$ .../bin/jboss-cli.sh -c --controller=localhost:9990
|
|
[domain@localhost:9990 /] cd profile=auth-server-clustered
|
|
[domain@localhost:9990 profile=auth-server-clustered] cd subsystem=keycloak-server
|
|
[domain@localhost:9990 subsystem=keycloak-server] :migrate-json(file="./keycloak-server.json")
|
|
----
|
|
You will need to repeat the `migrate-json` operation for each profile containing a `keycloak-server` subsystem.
|
|
|
|
=== Migrate database
|
|
|
|
Keycloak can automatically migrate the database schema, or you can choose to do it manually.
|
|
|
|
==== Relational database
|
|
|
|
To enable automatic upgrading of the database schema set the `migrationStrategy` property to `update` for
|
|
the default `connectionsJpa` provider:
|
|
|
|
.Edit xml
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsJpa">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
...
|
|
<property name="migrationStrategy" value="update"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
.Equivalent CLI command for above
|
|
[source]
|
|
----
|
|
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
|
|
----
|
|
|
|
When you start the server with this setting your database will automatically be migrated if the database schema has
|
|
changed in the new version.
|
|
|
|
To manually migrate the database set the `migrationStrategy` to `manual`. When you start the server with this
|
|
configuration it will check if the database needs migration. If changes are needed the required changes are written
|
|
to an SQL file that you can review and manually run against the database.
|
|
|
|
There's also the option to disable migration by setting the `migrationStrategy` to `validate`. With this configuration
|
|
the database will be checked at startup and if it is not migrated the server will exit.
|
|
|
|
==== Mongo
|
|
|
|
Mongo doesn't have a schema, but there may still be things like collections and indexes that are added to new releases.
|
|
To enable automatic creation of these set the `migrationStrategy` property to `update` for the default `connectionsMongo`
|
|
provider:
|
|
|
|
.Edit xml
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsMongo">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
...
|
|
<property name="migrationStrategy" value="update"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
.Equivalent CLI command for above
|
|
[source]
|
|
----
|
|
/subsystem=keycloak-server/spi=connectionsMongo/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
|
|
----
|
|
|
|
The Mongo provider does not have the option to manually apply the required changes.
|
|
|
|
There's also the option to disable migration by setting the `migrationStrategy` to `validate`. With this configuration
|
|
the database will be checked at startup and if it is not migrated the server will exit.
|
|
|
|
=== Migrate providers
|
|
|
|
If you have implemented any SPI providers you need to copy them to the new server.
|
|
The version specific section below will mention if any of the SPI's have changed.
|
|
If they have you may have to update your code accordingly.
|
|
|
|
=== Migrate themes
|
|
|
|
If you have created a custom theme you need to copy them to the new server.
|
|
The version specific section below will mention if changes have been made to themes.
|
|
If there is you may have to update your themes accordingly.
|
|
|
|
=== Migrate application
|
|
|
|
If you deploy applications directly to the Keycloak server you should copy them to the new server.
|
|
For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter.
|
|
The version specific section below will mention if any changes are required to applications. |