Keycloak

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

4
<@tmpl.guide
5
title="Deploy {jdgserver_name} for HA with the {jdgserver_name} Operator"
6
summary="Building block for an {jdgserver_name} deployment on Kubernetes"
7
tileVisible="false" >
8

9
include::partials/infinispan/infinispan-attributes.adoc[]
10

11
This {section} describes the procedures required to deploy {jdgserver_name} in a multiple-cluster environment (cross-site).
12
For simplicity, this topic uses the minimum configuration possible that allows {project_name} to be used with an external {jdgserver_name}.
13

14
This {section} assumes two {ocp} clusters named `{site-a}` and `{site-b}`.
15

16
This is a building block following the concepts described in the <@links.ha id="concepts-active-passive-sync" /> {section}.
17
See the <@links.ha id="introduction" /> {section} for an overview.
18

19
== Architecture
20

21
This setup deploys two synchronously replicating {jdgserver_name} clusters in two sites with a low-latency network connection.
22
An example of this scenario could be two availability zones in one AWS region.
23

24
{project_name}, loadbalancer and database have been removed from the following diagram for simplicity.
25

26
image::high-availability/infinispan-crossdc-az.dio.svg[]
27

28
== Prerequisites
29

30
include::partials/infinispan/infinispan-prerequisites.adoc[]
31

32
== Procedure
33

34
include::partials/infinispan/infinispan-install-operator.adoc[]
35
include::partials/infinispan/infinispan-credentials.adoc[]
36
+
37
These commands must be executed on both {ocp} clusters.
38

39
. Create a service account.
40
+
41
A service account is required to establish a connection between clusters.
42
The {ispn-operator} uses it to inspect the network configuration from the remote site and to configure the local {jdgserver_name} cluster accordingly.
43
+
44
For more details, see the {infinispan-operator-docs}#managed-cross-site-connections_cross-site[Managing Cross-Site Connections] documentation.
45
+
46
.. Create a `service-account-token` secret type as follows.
47
The same YAML file can be used in both {ocp} clusters.
48
+
49
.xsite-sa-secret-token.yaml
50
[source,yaml,subs="+attributes"]
51
----
52
apiVersion: v1
53
kind: Secret
54
metadata:
55
  name: ispn-xsite-sa-token #<1>
56
  annotations:
57
    kubernetes.io/service-account.name: "{sa}" #<2>
58
type: kubernetes.io/service-account-token
59
----
60
<1> The secret name.
61
<2> The service account name.
62
.. Create the service account and generate an access token in both {ocp} clusters.
63
+
64
.Create the service account in `{site-a}`
65
[source,bash,subs="+attributes"]
66
----
67
kubectl create sa -n {ns} {sa}
68
oc policy add-role-to-user view -n {ns} -z {sa}
69
kubectl create -f xsite-sa-secret-token.yaml
70
kubectl get secrets ispn-xsite-sa-token -o jsonpath="{.data.token}" | base64 -d > {site-a}-token.txt
71
----
72
+
73
.Create the service account in `{site-b}`
74
[source,bash,subs="+attributes"]
75
----
76
kubectl create sa -n {ns} {sa}
77
oc policy add-role-to-user view -n {ns} -z {sa}
78
kubectl create -f xsite-sa-secret-token.yaml
79
kubectl get secrets ispn-xsite-sa-token -o jsonpath="{.data.token}" | base64 -d > {site-b}-token.txt
80
----
81
+
82
.. The next step is to deploy the token from `{site-a}` into `{site-b}` and the reverse:
83
+
84
.Deploy `{site-b}` token into `{site-a}`
85
[source,bash,subs="+attributes"]
86
----
87
kubectl create secret generic -n {ns} {sa-secret} \
88
  --from-literal=token="$(cat {site-b}-token.txt)"
89
----
90
+
91
.Deploy `{site-a}` token into `{site-b}`
92
[source,bash,subs="+attributes"]
93
----
94
kubectl create secret generic -n {ns} {sa-secret} \
95
  --from-literal=token="$(cat {site-a}-token.txt)"
96
----
97

98
. Create TLS secrets
99
+
100
In this {section}, {jdgserver_name} uses an {ocp} Route for the cross-site communication.
101
It uses the SNI extension of TLS to direct the traffic to the correct Pods.
102
To achieve that, JGroups use TLS sockets, which require a Keystore and Truststore with the correct certificates.
103
+
104
For more information, see the {infinispan-operator-docs}#securing-cross-site-connections_cross-site[Securing Cross Site Connections] documentation or this https://developers.redhat.com/learn/openshift/cross-site-and-cross-applications-red-hat-openshift-and-red-hat-data-grid[Red Hat Developer Guide].
105
+
106
Upload the Keystore and the Truststore in an {ocp} Secret.
107
The secret contains the file content, the password to access it, and the type of the store.
108
Instructions for creating the certificates and the stores are beyond the scope of this guide.
109
+
110
To upload the Keystore as a Secret, use the following command:
111
+
112
.Deploy a Keystore
113
[source,bash,subs="+attributes"]
114
----
115
kubectl -n {ns} create secret generic {ks-secret} \
116
  --from-file=keystore.p12="./certs/keystore.p12" \ # <1>
117
  --from-literal=password=secret \ #<2>
118
  --from-literal=type=pkcs12 #<3>
119
----
120
<1> The filename and the path to the Keystore.
121
<2> The password to access the Keystore.
122
<3> The Keystore type.
123
+
124
To upload the Truststore as a Secret, use the following command:
125
+
126
.Deploy a Truststore
127
[source,bash,subs="+attributes"]
128
----
129
kubectl -n {ns} create secret generic {ts-secret} \
130
        --from-file=truststore.p12="./certs/truststore.p12" \  # <1>
131
        --from-literal=password=caSecret \  # <2>
132
        --from-literal=type=pkcs12  # <3>
133
----
134
<1> The filename and the path to the Truststore.
135
<2> The password to access the Truststore.
136
<3> The Truststore type.
137
+
138
NOTE: Keystore and Truststore must be uploaded in both {ocp} clusters.
139

140
. Create an {jdgserver_name} Cluster with Cross-Site enabled
141
+
142
The {infinispan-operator-docs}#setting-up-xsite[Setting Up Cross-Site] documentation provides all the information on how to create and configure your {jdgserver_name} cluster with cross-site enabled, including the previous steps.
143
+
144
A basic example is provided in this {section} using the credentials, tokens, and TLS Keystore/Truststore created by the commands from the previous steps.
145
+
146
.The {jdgserver_name} CR for `{site-a}`
147
[source,yaml]
148
----
149
include::examples/generated/ispn-site-a.yaml[tag=infinispan-crossdc]
150
----
151
<1> The cluster name
152
<2> Allows the cluster to be monitored by Prometheus.
153
<3> If using a custom credential, configure here the secret name.
154
<4> The name of the local site, in this case `{site-a}`.
155
<5> Exposing the cross-site connection using {ocp} Route.
156
<6> The secret name where the Keystore exists as defined in the previous step.
157
<7> The alias of the certificate inside the Keystore.
158
<8> The secret key (filename) of the Keystore as defined in the previous step.
159
<9> The secret name where the Truststore exists as defined in the previous step.
160
<10> The Truststore key (filename) of the Keystore as defined in the previous step.
161
<11> The remote site's name, in this case  `{site-b}`.
162
<12> The namespace of the {jdgserver_name} cluster from the remote site.
163
<13> The {ocp} API URL for the remote site.
164
<14> The secret with the access toke to authenticate into the remote site.
165
+
166
For `{site-b}`, the {jdgserver_name} CR looks similar to the above.
167
Note the differences in point 4, 11 and 13.
168
+
169
.The {jdgserver_name} CR for `{site-b}`
170
[source,yaml]
171
----
172
include::examples/generated/ispn-site-b.yaml[tag=infinispan-crossdc]
173
----
174

175
. Creating the caches for {project_name}.
176
+
177
{project_name} requires the following caches to be present: `sessions`, `actionTokens`, `authenticationSessions`, `offlineSessions`, `clientSessions`, `offlineClientSessions`, `loginFailures`, and `work`.
178
+
179
The {jdgserver_name} {infinispan-operator-docs}#creating-caches[Cache CR] allows deploying the caches in the {jdgserver_name} cluster.
180
Cross-site needs to be enabled per cache as documented by {infinispan-xsite-docs}[Cross Site Documentation].
181
The documentation contains more details about the options used by this {section}.
182
The following example shows the Cache CR for `{site-a}`.
183
+
184
.sessions in `{site-a}`
185
[source,yaml]
186
----
187
include::examples/generated/ispn-site-a.yaml[tag=infinispan-cache-sessions]
188
----
189
<1> The cross-site merge policy, invoked when there is a write-write conflict.
190
Set this for the caches `sessions`, `authenticationSessions`, `offlineSessions`, `clientSessions` and `offlineClientSessions`, and do not set it for all other caches.
191
<2> The remote site name.
192
<3> The cross-site communication, in this case, `SYNC`.
193
+
194
For `{site-b}`, the Cache CR is similar except in point 2.
195
+
196
.session in `{site-b}`
197
[source,yaml]
198
----
199
include::examples/generated/ispn-site-b.yaml[tag=infinispan-cache-sessions]
200
----
201

202
== Verifying the deployment
203

204
Confirm that the {jdgserver_name} cluster is formed, and the cross-site connection is established between the {ocp} clusters.
205

206
.Wait until the {jdgserver_name} cluster is formed
207
[source,bash,subs="+attributes"]
208
----
209
kubectl wait --for condition=WellFormed --timeout=300s infinispans.infinispan.org -n {ns} {cluster-name}
210
----
211

212
.Wait until the {jdgserver_name} cross-site connection is established
213
[source,bash,subs="+attributes"]
214
----
215
kubectl wait --for condition=CrossSiteViewFormed --timeout=300s infinispans.infinispan.org -n {ns} {cluster-name}
216
----
217

218
== Next steps
219

220
After infinispan is deployed and running, use the procedure in the <@links.ha id="connect-keycloak-to-external-infinispan"/> {section} to connect your {project_name} cluster with the {jdgserver_name} cluster.
221

222
</@tmpl.guide>
223