Keycloak

1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/options.adoc" as opts>
4
<#import "/templates/links.adoc" as links>
5

6
<@tmpl.guide
7
title="{project_name} Realm Import"
8
priority=30
9
summary="How to perform an automated {project_name} Realm Import using the operator">
10

11
== Importing a {project_name} Realm
12

13
Using the {project_name} Operator, you can perform a realm import for the Keycloak Deployment.
14

15
[NOTE]
16
====
17
* If a Realm with the same name already exists in {project_name}, it will not be overwritten.
18

19
* The Realm Import CR only supports creation of new realms and does not update or delete those. Changes to the realm performed directly on {project_name} are not synced back in the CR.
20
====
21

22
=== Creating a Realm Import Custom Resource
23

24
The following is an example of a Realm Import Custom Resource (CR):
25

26
[source,yaml]
27
----
28
apiVersion: k8s.keycloak.org/v2alpha1
29
kind: KeycloakRealmImport
30
metadata:
31
  name: my-realm-kc
32
spec:
33
  keycloakCRName: <name of the keycloak CR>
34
  realm:
35
    ...
36
----
37

38
This CR should be created in the same namespace as the Keycloak Deployment CR, defined in the field `keycloakCRName`.
39
The `realm` field accepts a full https://www.keycloak.org/docs-api/{version}/rest-api/index.html#RealmRepresentation[RealmRepresentation].
40

41
The recommended way to obtain a `RealmRepresentation` is by leveraging the export functionality <@links.server id="importExport"/>.
42

43
. Export the Realm to a single file.
44
. Convert the JSON file to YAML.
45
. Copy and paste the obtained YAML file as body for the `realm` key, making sure the indentation is correct.
46

47
=== Applying the Realm Import CR
48

49
Use `kubectl` to create the CR in the correct cluster namespace:
50

51
Create YAML file `example-realm-import.yaml`:
52

53
[source,yaml]
54
----
55
apiVersion: k8s.keycloak.org/v2alpha1
56
kind: KeycloakRealmImport
57
metadata:
58
  name: my-realm-kc
59
spec:
60
  keycloakCRName: <name of the keycloak CR>
61
  realm:
62
    id: example-realm
63
    realm: example-realm
64
    displayName: ExampleRealm
65
    enabled: true
66
----
67

68
Apply the changes:
69

70
[source,bash]
71
----
72
kubectl apply -f example-realm-import.yaml
73
----
74

75
To check the status of the running import, enter the following command:
76

77
[source,bash]
78
----
79
kubectl get keycloakrealmimports/my-realm-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
80
----
81

82
When the import has successfully completed, the output will look like the following example:
83

84
[source,bash]
85
----
86
CONDITION: Done
87
  STATUS: true
88
  MESSAGE: 
89
CONDITION: Started
90
  STATUS: false
91
  MESSAGE: 
92
CONDITION: HasErrors
93
  STATUS: false
94
  MESSAGE:
95
----
96

97
</@tmpl.guide>
98