Keycloak

1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/links.adoc" as links>
3

4
<@tmpl.guide
5
title="Connect {project_name} with an external {jdgserver_name}"
6
summary="Building block for an Infinispan deployment on Kubernetes"
7
tileVisible="false" >
8

9
This topic describes advanced {jdgserver_name} configurations for {project_name} on Kubernetes.
10

11
== Prerequisites
12

13
* <@links.ha id="deploy-keycloak-kubernetes" /> as it will be extended.
14
* <@links.ha id="deploy-infinispan-kubernetes-crossdc" />.
15

16
== Procedure
17

18
. Prepare an {jdgserver_name} Cache configuration XML from the file `cache-ispn.xml` which is part of the {project_name} distribution:
19
.. For each `distributed-cache` entry, add the tags `<persistence />` as shown following.
20
+
21
[source,xml,indent=0]
22
----
23
include::examples/src/kcb-infinispan-cache-remote-store-config.xml[tag=keycloak-ispn-remotestore]
24
----
25
<1> New tag `<persistence />` to connect it to the remote store.
26
<2> This is a workaround for issue https://github.com/keycloak/keycloak/issues/27117[keycloak#27117] and will be removed in the following versions.
27
<3> For the address to the remote store, reference two environment variables for host name and port number.
28
<4> For authentication, reference two environment variables for username and password.
29
<5> To secure the remote store connection, use the Kubernetes mechanisms of the pre-configured truststore.
30

31
.. Prepare an {jdgserver_name} Cache configuration XML from the file `cache-ispn.xml`, which is part of the {project_name} distribution. 
32
For each `replicated-cache` entry, add the tag `<persistence />` as shown below.
33
For additional information on the infinispan configuration options, see the https://docs.jboss.org/infinispan/14.0/configdocs/infinispan-config-14.0.html[infinispan configuration schema reference].
34
+
35
[source,xml,indent=0]
36
----
37
include::examples/src/kcb-infinispan-cache-remote-store-config.xml[tag=keycloak-ispn-remotestore-work]
38
----
39

40
. Place the {jdgserver_name} Cache configuration XML in a ConfigMap.
41
+
42
[source,yaml]
43
----
44
include::examples/generated/keycloak-ispn.yaml[tag=keycloak-ispn-configmap]
45
...
46
----
47

48
. Create a Secret with the username and password to connect to the external {jdgserver_name} deployment:
49
+
50
[source,yaml]
51
----
52
include::examples/generated/keycloak-ispn.yaml[tag=keycloak-ispn-secret]
53
----
54

55
. Extend the {project_name} Custom Resource with `additionalOptions` as shown below.
56
+
57
[NOTE]
58
====
59
* The new `additionalOptions` entries starting with `remote-store` used here are not official {project_name} configurations.
60
Instead, they provide their values to environment variables that are then referenced in the {jdgserver_name} XML configuration.
61
* All the memory, resource and database configurations are skipped from the CR below as they have been described in <@links.ha id="deploy-keycloak-kubernetes" /> {section} already.
62
Administrators should leave those configurations untouched.
63
====
64
+
65
[source,yaml]
66
----
67
include::examples/generated/keycloak-ispn.yaml[tag=keycloak-ispn]
68
----
69
<1> The `name` and `key` of the ConfigMap with the {jdgserver_name} Cache configuration XML created in the previous step.
70
<2> The hostname and port of the remote cache {jdgserver_name} cluster.
71
<3> The credentials required, username and password, to access the remote cache {jdgserver_name} cluster.
72
<4> The `spi-connections-infinispan-quarkus-site-name` is an arbitrary {jdgserver_name} site name which {project_name} needs for its embedded {jdgserver_name} deployment when a remote store is used.
73
This site-name is related only to the embedded {jdgserver_name} and does not need to match any value from the external {jdgserver_name} deployment.
74
If you are using multiple sites for {project_name} in a cross-DC setup such as <@links.ha id="deploy-infinispan-kubernetes-crossdc" />, the site name must be different in each site.
75

76
</@tmpl.guide>
77