libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Move getting started and migration guides to main repo (#16675)

Browse source 
* Move getting started and migration guides to main repo

Closes #16575

* Fix copy images

* Remove images for Vue getting started that remains on website for now
This commit is contained in:
Stian Thorgersen 2023-02-09 10:29:41 +01:00 committed by GitHub
parent 017ddc670b
commit 6e1a58adc6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 652 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
docs/guides/pom.xml
View file

@ -40,6 +40,28 @@
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.0</version>
<executions>
<execution>
<id>copy-resources</id>
<!-- here the phase you need -->
<phase>validate</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/src/main/images</outputDirectory>
<resources>
<resource>
<directory>${basedir}/target/generated-guides/images</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-guides-maven-plugin</artifactId>
@ -57,6 +79,21 @@
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version>
<configuration>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
<toc>left</toc>
<icons>font</icons>
<sectanchors>true</sectanchors>
<idprefix/>
<idseparator>-</idseparator>
<docinfo1>true</docinfo1>
<imagesdir>../images</imagesdir>
</attributes>
</configuration>
<executions>
<execution>
<id>server-asciidoc-to-html</id>
@ -66,21 +103,7 @@
</goals>
<configuration>
<sourceDirectory>${basedir}/target/generated-guides/server</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/generated-docs/server</outputDirectory>
<backend>html5</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<imagesdir>./</imagesdir>
<toc>left</toc>
<toc>left</toc>
<icons>font</icons>
<sectanchors>true</sectanchors>
<idprefix/>
<idseparator>-</idseparator>
<docinfo1>true</docinfo1>
</attributes>
</configuration>
</execution>
<execution>
@ -91,21 +114,29 @@
</goals>
<configuration>
<sourceDirectory>${basedir}/target/generated-guides/operator</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/generated-docs/operator</outputDirectory>
<backend>html5</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<imagesdir>./</imagesdir>
<toc>left</toc>
<toc>left</toc>
<icons>font</icons>
<sectanchors>true</sectanchors>
<idprefix/>
<idseparator>-</idseparator>
<docinfo1>true</docinfo1>
</attributes>
</configuration>
</execution>
<execution>
<id>migration-asciidoc-to-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${basedir}/target/generated-guides/migration</sourceDirectory>
<outputDirectory>${project.build.directory}/generated-docs/migration</outputDirectory>
</configuration>
</execution>
<execution>
<id>getting-started-asciidoc-to-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${basedir}/target/generated-guides/getting-started</sourceDirectory>
<outputDirectory>${project.build.directory}/generated-docs/getting-started</outputDirectory>
</configuration>
</execution>
</executions>

27
docs/guides/src/main/getting-started/getting-started-docker.adoc Normal file
View file

@ -0,0 +1,27 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="Docker"
summary="Get started with Keycloak on Docker">
:containerCommand: docker
:links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
## Before you start
Make sure you have Docker installed.
include::templates/start-keycloak-container.adoc[]
include::templates/realm-config.adoc[]
include::templates/login-to-account.adoc[]
include::templates/first-app.adoc[]
include::templates/next.adoc[]
</@tmpl.guide>

103
docs/guides/src/main/getting-started/getting-started-kube.adoc Normal file
View file

@ -0,0 +1,103 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="Kubernetes"
summary="Get started with Keycloak on Kubernetes">
:links-admin-console: Keycloak Admin Console
:links-account-console: Keycloak Account Console
## Before you start
Make sure you have Minikube installed, ideally with the Ingress addon enabled.
To check if you have the Ingress addon enabled run:
[source,bash,subs="attributes+"]
----
minikube addons list
----
If the Ingress addon is not enabled run the following to enable it:
[source,bash,subs="attributes+"]
----
minikube addons enable ingress
----
## Run Keycloak
The Keycloak QuickStarts repository includes some example files to help deploy Keycloak to Kubernetes.
Let's start with creating the Keycloak deployment and service:
[source,bash,subs="attributes+"]
----
kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes-examples/keycloak.yaml
----
This will start Keycloak on Kubernetes. It will also create an initial admin user with username `admin` and password
`admin`.
### Access Keycloak with Ingress addon enabled
Start by creating an Ingress for Keycloak:
[source,bash,subs="attributes+"]
----
wget -q -O - https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes-examples/keycloak-ingress.yaml | \
sed "s/KEYCLOAK_HOST/keycloak.$(minikube ip).nip.io/" | \
kubectl create -f -
----
If you don't have `wget` and `sed` available, download the file and manually edit the file replacing `KEYCLOAK_HOST`
with `keycloak.<minikube ip address>.nip.io`.
Run the following to find out the URLs of Keycloak:
[source,bash,subs="attributes+"]
----
KEYCLOAK_URL=https://keycloak.$(minikube ip).nip.io &&
echo "" &&
echo "Keycloak: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""
----
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
right now as you will need to create the realm first.
### Access Keycloak without Ingress
If you don't have the Ingress addon enabled, first run in a separate shell:
[source,bash,subs="attributes+"]
----
minikube tunnel
----
and you can now access Keycloak from the following URL:
[source,bash,subs="attributes+"]
----
KEYCLOAK_URL=http://$(minikube ip):$(kubectl get services/keycloak -o go-template='{{(index .spec.ports 0).nodePort}}') &&
echo "" &&
echo "Keycloak: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""
----
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
right now as you will need to create the realm first.
include::templates/realm-config.adoc[]
include::templates/login-to-account.adoc[]
include::templates/first-app.adoc[]
include::templates/next.adoc[]
</@tmpl.guide>

109
docs/guides/src/main/getting-started/getting-started-openshift.adoc Normal file
View file

@ -0,0 +1,109 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="Openshift"
summary="Get started with Keycloak on Openshift">
:links-admin-console: Keycloak Admin Console
:links-account-console: Keycloak Account Console
## Before you start
Install https://code-ready.github.io/crc/[Red Hat Code Ready Containers] and follow the steps in the documentation to install a
local OpenShift cluster.
Make sure the cluster is functional by executing the following command:
[source,bash,subs="attributes+"]
----
crc status
----
If everything is OK you should see an output similar to this:
[source,bash,subs="attributes+"]
----
CRC VM: Running
OpenShift: Running
...
----
Log in as the user `developer`:
[source,bash,subs="attributes+"]
----
oc login -u developer -p developer
----
For this guide, we are going to create a new project called `keycloak`. For that, execute the following command:
[source,bash,subs="attributes+"]
----
oc new-project keycloak
----
## Run Keycloak
To spin up a Keycloak server in your project, execute the following command:
[source,bash,subs="attributes+"]
----
oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift-examples/keycloak.yaml \
-p KEYCLOAK_ADMIN=admin \
-p KEYCLOAK_ADMIN_PASSWORD=admin \
-p NAMESPACE=keycloak \
| oc create -f -
----
Once the command above completes you should see a message similar to this:
[source,bash,subs="attributes+"]
----
service/keycloak created
route.route.openshift.io/keycloak created
deploymentconfig.apps.openshift.io/keycloak created.
----
At this point, OpenShift is going to provision a Keycloak pod and related resources. As part of the process, OpenShift will
try to pull the Keycloak server image. This might take some time depending on your network connection.
To make sure Keycloak is provisioned, execute the following command:
[source,bash,subs="attributes+"]
----
oc get pods
----
After a while you will see a message similar to this when the pod is ready:
[source,bash,subs="attributes+"]
----
NAME READY STATUS RESTARTS AGE
keycloak-1-deploy 0/1 Completed 0 1h
keycloak-1-l9kdx 1/1 Running 0 1h
----
Once the server is provisioned, run the following command to find out the URLs of Keycloak:
[source,bash,subs="attributes+"]
----
KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
echo "" &&
echo "Keycloak: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""
----
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
right now as you will need to create the realm first.
include::templates/realm-config.adoc[]
include::templates/login-to-account.adoc[]
include::templates/first-app.adoc[]
include::templates/next.adoc[]
</@tmpl.guide>

27
docs/guides/src/main/getting-started/getting-started-podman.adoc Normal file
View file

@ -0,0 +1,27 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="Podman"
summary="Get started with Keycloak on Podman">
:containerCommand: podman
:links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
## Before you start
Make sure you have Podman installed.
include::templates/start-keycloak-container.adoc[]
include::templates/realm-config.adoc[]
include::templates/login-to-account.adoc[]
include::templates/first-app.adoc[]
include::templates/next.adoc[]
</@tmpl.guide>

34
docs/guides/src/main/getting-started/getting-started-zip.adoc Normal file
View file

@ -0,0 +1,34 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="OpenJDK"
summary="Get started with Keycloak on bare metal">
:links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
## Before you start
Make sure you have https://openjdk.java.net/[OpenJDK 11] or newer installed.
## Download Keycloak
First step is to download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip]
from the Keycloak website.
After extracting you should have a directory named keycloak-{version}.
include::templates/start-keycloak-localhost.adoc[]
include::templates/create-admin-localhost.adoc[]
include::templates/realm-config.adoc[]
include::templates/login-to-account.adoc[]
include::templates/first-app.adoc[]
include::templates/next.adoc[]
</@tmpl.guide>

10
docs/guides/src/main/getting-started/index.adoc Normal file
View file

@ -0,0 +1,10 @@
<#list ctx.guides as guide>
:links_getting-started_${guide.id}_name: ${guide.title}
:links_getting-started_${guide.id}_url: #${guide.id}
</#list>
= Keycloak getting started guide
<#list ctx.guides as guide>
include::${guide.template}[leveloffset=+1]
</#list>

3
docs/guides/src/main/getting-started/pinned-guides Normal file
View file

@ -0,0 +1,3 @@
getting-started-zip
getting-started-docker
getting-started-podman

6
docs/guides/src/main/getting-started/templates/create-admin-localhost.adoc Normal file
View file

@ -0,0 +1,6 @@
## Create an admin user
Keycloak does not come with a default admin user, which means before you can start using Keycloak you need to create
an admin user.
To do this open http://localhost:8080/[http://localhost:8080/], then fill in the form with your preferred username and password.

36
docs/guides/src/main/getting-started/templates/first-app.adoc Normal file
View file

@ -0,0 +1,36 @@
## Secure your first app
Let's try to secure our first application. First step is to register this application with your Keycloak instance:
. Open the {links-admin-console}
. Click 'Clients'
. Click 'Create client'
. Fill in the form with the following values:
** Client type: `OpenID Connect`
** Client ID: `myclient`
. Click 'Next'
. Make sure 'Standard flow' is enabled
. Click 'Save'
image::add-client-1.png[Add Client]
After the client is created you need to update the following values for the client:
. Valid redirect URIs: `https://www.keycloak.org/app/*`
. Web origins: `https://www.keycloak.org`
Remember to click `Save`.
image::add-client-2.png[Update Client]
To make it easy for you we have a SPA testing application available on the https://www.keycloak.org/app/[Keycloak website].
ifeval::[{links-local}==true]
Open https://www.keycloak.org/app/ and click `Save` to use the default configuration.
endif::[]
ifeval::[{links-local}!=true]
Open https://www.keycloak.org/app/. Change `Keycloak URL` to the URL of your Keycloak instance. Click `Save`.
endif::[]
Now you can click `Sign in` to authenticate to this application using the Keycloak server you started earlier.

10
docs/guides/src/main/getting-started/templates/login-to-account.adoc Normal file
View file

@ -0,0 +1,10 @@
## Login to account console
Let's now try to login to the account console to verify the user is configured correctly.
. Open the {links-account-console}
. Login with `myuser` and the password you created earlier
You should now be logged-in to the account console where users can manage their accounts.
image::account-console.png[Keycloak Account Console]

9
docs/guides/src/main/getting-started/templates/next.adoc Normal file
View file

@ -0,0 +1,9 @@
## Next
Before you go and run Keycloak in production there are a few more things that you will want to do, including:
* Switch to a production ready database such as PostgreSQL
* Configure SSL with your own certificates
* Switch the admin password to a more secure password
For more information check out the https://www.keycloak.org/guides#server[server guides].

43
docs/guides/src/main/getting-started/templates/realm-config.adoc Normal file
View file

@ -0,0 +1,43 @@
## Login to the admin console
Go to the {links-admin-console} and login with the username and password
you created earlier.
## Create a realm
A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users. By default
there is a single realm in Keycloak called `master`. This is dedicated to manage Keycloak and should not be used for
your own applications.
Let's create our first realm.
. Open the {links-admin-console}
. Hover the mouse over the dropdown in the top-left corner where it says `master`, then click on `Create realm`
. Fill in the form with the following values:
** Realm name: `myrealm`
. Click `Create`
image::add-realm.png[Add Realm]
## Create a user
Initially there are no users in a new realm, so let's create one:
. Open the {links-admin-console}
. Click `Users` (left-hand menu)
* Click `Create new user` (top-right corner of table)
. Fill in the form with the following values:
** Username: `myuser`
** First Name: Your first name
** Last Name: Your last name
. Click `Create`
image::add-user.png[Add User]
The user will need an initial password set to be able to login. To do this:
. Click `Credentials` (top of the page)
. Fill in the `Set password` form with a password
. Click `ON` next to `Temporary` to prevent having to update password on first login
image::set-password.png[Set Password]

11
docs/guides/src/main/getting-started/templates/start-keycloak-container.adoc Normal file
View file

@ -0,0 +1,11 @@
## Start Keycloak
From a terminal start Keycloak with the following command:
[source,bash,subs="attributes+"]
----
{containerCommand} run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev
----
This will start Keycloak exposed on the local port 8080. It will also create an initial admin user with username `admin`
and password `admin`.

17
docs/guides/src/main/getting-started/templates/start-keycloak-localhost.adoc Normal file
View file

@ -0,0 +1,17 @@
## Start Keycloak
From a terminal open the directory keycloak-{version}, then to start Keycloak run the following command.
On Linux run:
[source,bash,subs="attributes+"]
----
bin/kc.sh start-dev
----
On Windows run:
[source,bash,subs="attributes+"]
----
bin/kc.bat start-dev
----

13
docs/guides/src/main/getting-started/templates/test-app.adoc Normal file
View file

@ -0,0 +1,13 @@
## Test your setup
To make it easy for you we have a SPA testing application available on the https://www.keycloak.org/app/[Keycloak website].
ifeval::[{links-local}==true]
Open https://www.keycloak.org/app/ and click `Save` to use the default configuration.
endif::[]
ifeval::[{links-local}!=true]
Open https://www.keycloak.org/app/. Change `Keycloak URL` to the URL of your Keycloak instance. Click `Save`.
endif::[]
Now you can click `Sign in` to authenticate to this application using the Keycloak server you started earlier.

BIN
docs/guides/src/main/images/account-console.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
docs/guides/src/main/images/add-client-1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
docs/guides/src/main/images/add-client-2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 81 KiB

BIN
docs/guides/src/main/images/add-realm.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/guides/src/main/images/add-user.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/guides/src/main/images/set-password.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 27 KiB

10
docs/guides/src/main/migration/index.adoc Normal file
View file

@ -0,0 +1,10 @@
<#list ctx.guides as guide>
:links_migration_${guide.id}_name: ${guide.title}
:links_migration_${guide.id}_url: #${guide.id}
</#list>
= Keycloak migration guide
<#list ctx.guides as guide>
include::${guide.template}[leveloffset=+1]
</#list>

106
docs/guides/src/main/migration/migrating-to-quarkus.adoc Normal file
View file

@ -0,0 +1,106 @@
<#import "/templates/guide.adoc" as tmpl>
<@tmpl.guide
title="Migrating to Quarkus distribution"
summary="Migrate to the new Quarkus distribution from the legacy WildFly distribution">
In Keycloak 17 the default distribution is now powered by Quarkus, while the legacy WildFly powered distribution will still be around until June 2022 we highly recommend starting the migration as soon as possible.
The new distribution introduces a number of breaking changes, including:
* Configuring Keycloak has significantly changed
* Quarkus is not an application server, but rather a framework to build applications
* `/auth` removed from the default context path
* Custom providers are packaged and deployed differently
* A new operator and CRDs for Kubernetes and OpenShift
Before undertaking the migration we highly recommend reading through the new https://www.keycloak.org/guides#server[Server Guides] to understand how to install and configure the new distribution.
== Migrating configuration
The WildFly distribution of Keycloak used complicated XML files for configuration, resulting in the need for a CLI tool (`jboss-cli`) to manipulate these files. These files also brought complication to upgrading, where an error-prone script was used to upgrade the config from a previous version.
The new Quarkus powered distribution leverages a simple configuration file instead, with corresponding CLI arguments and environment variables as options, making it significantly easier to configure Keycloak. However, this results in the inability to automatically migrate the configuration from the previous distribution.
To migrate to the new Quarkus powered distribution the first step is to understand what configuration changes you are applying to the legacy distribution, and apply those that are necessary to the new distribution by following the new https://www.keycloak.org/guides#server[Server Guides].
One thing to note is the new distribution is a lot more opinionated when it comes to configuration. It aims to provide better defaults, with the need to configure less yourself. However, we may not always have the balance right, and there may be use-cases not covered.
If you are unable to configure something that you need to tweak in the new distribution, please open a discussion in https://github.com/keycloak/keycloak/discussions/categories/keycloak-x-quarkus-distribution[GitHub Discussions].
Until a new release is available it is possible to configure the new distribution by directly applying Quarkus level configuration through the `conf/quarkus.properties` file. We recommend you use this sparingly as you will be applying configuration untested and unsupported by the Keycloak team.
== Quarkus is not an application server
Unlike WildFly, Quarkus is not an application server. While an application server can dynamically deploy applications, and alter what is loaded into memory at runtime, this is not possible on Quarkus.
Quarkus on the other hand brings immutability to containers, faster startup, and more predictability.
While with the WildFly distribution you could hot-deploy custom providers, change the database vendor as a runtime configuration this is no longer supported.
Instead, the Quarkus distribution provides a separate build step that optimises the runtime. One important thing to note here is that the build step does not actually build the Keycloak sources, but rather just optimises the runtime through an augmentation process, which is fairly fast and able to fully optimise what is loaded into the runtime.
We recommend that you do this build step as a part of installing Keycloak, through CI, or by creating a custom container image that extends the base Keycloak image.
However, there is also an auto build mode that makes Keycloak behave more or less the same as the WildFly distribution in this regard. This comes with a startup time penalty, but is still able to optimise the runtime better than the WildFly distribution could.
== Setup of initial users
The Keycloak Wildfly distribution contained scripts named `add-user-keycloak.sh` to add initial users to Keycloak.
These are no longer included in the Quarkus distribution.
To add the initial admin user, set the environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` for the username and password of the user.
Keycloak uses them at the first startup to create an initial user with administration rights.
Once the first user with administrative rights exists, use the command line tool `kcadm.sh` (Linux) or `kcadm.bat` (Windows) to create additional users.
== Default context path changed
By default, the new Quarkus distribution removes `/auth` from the context-path. To re-introduce the `/auth` use the https://www.keycloak.org/server/all-config?q=http-relative-path&f=build[`http-relative-path`] build option. For example:
[code,bash]
----
bin/kc.[sh|bat] start-dev --http-relative-path /auth
----
== Migrating custom providers
Similarly to the WildFly distribution custom providers are deployed to Keycloak by copying them to a deployment directory. In the new distribution you should copy your providers to the `providers` directory instead of `standalone/deployments`, which no longer exists. Additional dependencies are also copied to the `providers` directory.
With the new distribution there is no longer a separate classpath for custom providers, so you may need to be more careful with what additional dependencies you include. In addition, the `EAR` packaging format, and `jboss-deployment-structure.xml` files, is no longer supported.
While the WildFly distribution automatically discovered custom providers, even supported the ability to hot-deploy custom providers while Keycloak is running, this is no longer supported, and when you make a change to the providers or dependencies in the `providers` directory you have to do a build afterwards, or restart the server with the auto build feature.
Depending on what APIs your providers use you may also need to make some changes to the providers. If you only leveraged classes from Keycloak SPIs you shouldn't need to, but if you used other APIs from WildFly you may need to make some changes. In addition, JavaEE APIs like session/stateless beans are no longer supported.
== Migrating using the Operator
To use the Quarkus distribution on Kubernetes and OpenShift you need to use the new Operator, the https://github.com/keycloak/keycloak-operator[old Operator] does not support the new distribution.
There is no "direct" migration path, to install Keycloak using the new Operator you need to create a new Custom Resource (CR) to end up with a new Keycloak Deployment based on the Quarkus distribution.
The old and new operator can co-exist even in the same namespace since they are using a different API Group and Version in the CRDs.
For the old operator, the apiVersion is:
[source,yaml]
----
apiVersion: keycloak.org/v1alpha1
----
For the new operator, the apiVersion is:
[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
----
When using `kubectl` commands, and the 2 CRDs are installed in the cluster, make sure to use fully qualified names including the API Group, e.g.:
[source,bash]
----
$ kubectl get keycloaks.k8s.keycloak.org
----
The new operator doesn't support Client, User and Realm CRDs directly. Instead, it provides one CRD to perform a https://www.keycloak.org/operator/realm-import.html[Realm import].
Using this new CR you can import Users, Clients and more through the wrapping Realm.
</@tmpl.guide>

4
docs/guides/src/main/operator/installation.adoc
View file

@ -27,11 +27,11 @@ On OpenShift, use the built-in OLM UI to install the Keycloak Operator.
Navigate to `Home`, `Operators`, `OperatorHub` using the menu on the left side of the OpenShift Console.
Search for "keycloak" on the search input box:
image::{generatedGuideImages}/select-operator.jpeg["Select the Keycloak Operator in the UI"]
image::select-operator.jpeg["Select the Keycloak Operator in the UI"]
Select the Keycloak Operator from the list of results. After that, follow the instructions on the screen. Make sure you are installing from the `fast` channel:
image::{generatedGuideImages}/configure-operator.jpeg["Configure Keycloak Operator"]
image::configure-operator.jpeg["Configure Keycloak Operator"]
=== Vanilla Kubernetes Installation

1
docs/guides/src/main/templates/guide.adoc
View file

@ -5,6 +5,7 @@
:guide-title: ${title}
:guide-summary: ${summary}
:guide-priority: ${priority}
:version: ${version}
[[${id}]]
= ${title}

5
docs/maven-plugin/src/main/java/org/keycloak/guides/maven/FreeMarker.java
View file

@ -18,8 +18,7 @@ public class FreeMarker {
private Map<String, Object> attributes;
private Configuration configuration;
public FreeMarker(File srcDir, File targetDir, Map<String, Object> attributes) throws IOException {
this.targetDir = targetDir;
public FreeMarker(File srcDir, Map<String, Object> attributes) throws IOException {
this.attributes = attributes;
configuration = new Configuration(Configuration.VERSION_2_3_31);
@ -29,7 +28,7 @@ public class FreeMarker {
configuration.setLogTemplateExceptions(false);
}
public void template(String template) throws IOException, TemplateException {
public void template(String template, File targetDir) throws IOException, TemplateException {
Template t = configuration.getTemplate(template);
File out = targetDir.toPath().resolve(template).toFile();

16
docs/maven-plugin/src/main/java/org/keycloak/guides/maven/GuideBuilder.java
View file

@ -2,6 +2,7 @@ package org.keycloak.guides.maven;
import freemarker.template.TemplateException;
import org.apache.maven.plugin.logging.Log;
import org.keycloak.common.Version;
import java.io.File;
import java.io.IOException;
@ -22,8 +23,9 @@ public class GuideBuilder {
Map<String, Object> globalAttributes = new HashMap<>();
globalAttributes.put("ctx", new Context(srcDir));
globalAttributes.put("version", Version.VERSION);
this.freeMarker = new FreeMarker(srcDir.getParentFile(), targetDir.getParentFile(), globalAttributes);
this.freeMarker = new FreeMarker(srcDir.getParentFile(), globalAttributes);
}
public void build() throws TemplateException, IOException {
@ -32,11 +34,21 @@ public class GuideBuilder {
}
for (String t : srcDir.list((dir, name) -> name.endsWith(".adoc"))) {
freeMarker.template(srcDir.getName() + "/" + t);
freeMarker.template(srcDir.getName() + "/" + t, targetDir.getParentFile());
if (log != null) {
log.info("Templated: " + srcDir.getName() + "/" + t);
}
}
File templatesDir = new File(srcDir, "templates");
if (templatesDir.isDirectory()) {
for (String t : templatesDir.list((dir, name) -> name.endsWith(".adoc"))) {
freeMarker.template(srcDir.getName() + "/" + templatesDir.getName() + "/" + t, targetDir.getParentFile());
if (log != null) {
log.info("Templated: " + templatesDir.getName() + "/" + t);
}
}
}
}
}