Keycloak
222 строки · 8.9 Кб
1<#import "/templates/guide.adoc" as tmpl>
2<#import "/templates/links.adoc" as links>
3
4<@tmpl.guide
5title="Deploy {jdgserver_name} for HA with the {jdgserver_name} Operator"
6summary="Building block for an {jdgserver_name} deployment on Kubernetes"
7tileVisible="false" >
8
9include::partials/infinispan/infinispan-attributes.adoc[]
10
11This {section} describes the procedures required to deploy {jdgserver_name} in a multiple-cluster environment (cross-site).
12For simplicity, this topic uses the minimum configuration possible that allows {project_name} to be used with an external {jdgserver_name}.
13
14This {section} assumes two {ocp} clusters named `{site-a}` and `{site-b}`.
15
16This is a building block following the concepts described in the <@links.ha id="concepts-active-passive-sync" /> {section}.
17See the <@links.ha id="introduction" /> {section} for an overview.
18
19== Architecture
20
21This setup deploys two synchronously replicating {jdgserver_name} clusters in two sites with a low-latency network connection.
22An 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
26image::high-availability/infinispan-crossdc-az.dio.svg[]
27
28== Prerequisites
29
30include::partials/infinispan/infinispan-prerequisites.adoc[]
31
32== Procedure
33
34include::partials/infinispan/infinispan-install-operator.adoc[]
35include::partials/infinispan/infinispan-credentials.adoc[]
36+
37These commands must be executed on both {ocp} clusters.
38
39. Create a service account.
40+
41A service account is required to establish a connection between clusters.
42The {ispn-operator} uses it to inspect the network configuration from the remote site and to configure the local {jdgserver_name} cluster accordingly.
43+
44For 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.
47The same YAML file can be used in both {ocp} clusters.
48+
49.xsite-sa-secret-token.yaml
50[source,yaml,subs="+attributes"]
51----
52apiVersion: v1
53kind: Secret
54metadata:
55name: ispn-xsite-sa-token #<1>
56annotations:
57kubernetes.io/service-account.name: "{sa}" #<2>
58type: 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----
67kubectl create sa -n {ns} {sa}
68oc policy add-role-to-user view -n {ns} -z {sa}
69kubectl create -f xsite-sa-secret-token.yaml
70kubectl 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----
76kubectl create sa -n {ns} {sa}
77oc policy add-role-to-user view -n {ns} -z {sa}
78kubectl create -f xsite-sa-secret-token.yaml
79kubectl 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----
87kubectl 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----
94kubectl create secret generic -n {ns} {sa-secret} \
95--from-literal=token="$(cat {site-a}-token.txt)"
96----
97
98. Create TLS secrets
99+
100In this {section}, {jdgserver_name} uses an {ocp} Route for the cross-site communication.
101It uses the SNI extension of TLS to direct the traffic to the correct Pods.
102To achieve that, JGroups use TLS sockets, which require a Keystore and Truststore with the correct certificates.
103+
104For 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+
106Upload the Keystore and the Truststore in an {ocp} Secret.
107The secret contains the file content, the password to access it, and the type of the store.
108Instructions for creating the certificates and the stores are beyond the scope of this guide.
109+
110To upload the Keystore as a Secret, use the following command:
111+
112.Deploy a Keystore
113[source,bash,subs="+attributes"]
114----
115kubectl -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+
124To upload the Truststore as a Secret, use the following command:
125+
126.Deploy a Truststore
127[source,bash,subs="+attributes"]
128----
129kubectl -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+
138NOTE: Keystore and Truststore must be uploaded in both {ocp} clusters.
139
140. Create an {jdgserver_name} Cluster with Cross-Site enabled
141+
142The {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+
144A 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----
149include::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+
166For `{site-b}`, the {jdgserver_name} CR looks similar to the above.
167Note the differences in point 4, 11 and 13.
168+
169.The {jdgserver_name} CR for `{site-b}`
170[source,yaml]
171----
172include::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+
179The {jdgserver_name} {infinispan-operator-docs}#creating-caches[Cache CR] allows deploying the caches in the {jdgserver_name} cluster.
180Cross-site needs to be enabled per cache as documented by {infinispan-xsite-docs}[Cross Site Documentation].
181The documentation contains more details about the options used by this {section}.
182The following example shows the Cache CR for `{site-a}`.
183+
184.sessions in `{site-a}`
185[source,yaml]
186----
187include::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.
190Set 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+
194For `{site-b}`, the Cache CR is similar except in point 2.
195+
196.session in `{site-b}`
197[source,yaml]
198----
199include::examples/generated/ispn-site-b.yaml[tag=infinispan-cache-sessions]
200----
201
202== Verifying the deployment
203
204Confirm 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----
209kubectl 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----
215kubectl wait --for condition=CrossSiteViewFormed --timeout=300s infinispans.infinispan.org -n {ns} {cluster-name}
216----
217
218== Next steps
219
220After 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