From 57f2b744a0caf440f2d58090029846cb12ac1502 Mon Sep 17 00:00:00 2001
From: Andrea Peruffo <andrea.peruffo1982@gmail.com>
Date: Fri, 8 Apr 2022 10:56:03 +0100
Subject: [PATCH] Add RealmImport CR docs (#11037)

---
 .../src/main/operator/realm-import.adoc       | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/guides/src/main/operator/realm-import.adoc

diff --git a/docs/guides/src/main/operator/realm-import.adoc b/docs/guides/src/main/operator/realm-import.adoc
new file mode 100644
index 0000000000..8bdb0be2da
--- /dev/null
+++ b/docs/guides/src/main/operator/realm-import.adoc
@@ -0,0 +1,92 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/kc.adoc" as kc>
+<#import "/templates/options.adoc" as opts>
+<#import "/templates/links.adoc" as links>
+
+<@tmpl.guide
+title="Keycloak Realm Import"
+summary="How to perform an automated Keyacloak Realm Import">
+
+== Keycloak Realm Import
+
+The Keycloak Operator ships with the feature of automatically perform a realm import for the Keycloak Deployment.
+
+.Note:
+[NOTE]
+If a Realm with the same name already exists in Keycloak it will not be overwritten.
+
+.Note:
+[NOTE]
+The Realm Import CR only supports creation of new realms and doesn't updates or delete those. +
+Changes to the realm performed directly on Keycloak are not synched back in the CR.
+
+=== Writing Realm Import CR
+
+A Realm Import Custom Resource(CR) looks like follows:
+
+[source,yaml]
+----
+apiVersion: keycloak.org/v2alpha1
+kind: KeycloakRealmImport
+metadata:
+  name: my-realm-kc
+spec:
+  keycloakCRName: <name of the keycloak CR>
+  realm:
+    ...
+----
+
+This CR should be created in the same namespace as the Keycloak Deployment CR defined in the field `keycloakCRName`.
+The `realm` field accepts a full https://www.keycloak.org/docs-api/{version}/rest-api/index.html#_realmrepresentation[RealmRepresentation].
+
+The suggested way to obtain a `RealmRepresentation` is leveraging the export functionality <@links.server id="importExport"/>
+
+* export the Realm to a single file
+* convert the json to yaml
+* copy-paste the obtained yaml as body for the `realm` key (make sure the indentation is correct)
+
+=== Applying the Realm Import CR
+
+Use `kubectl` to create the CR in the correct cluster namespace:
+
+[source,bash]
+----
+cat <<EOF >> example-realm-import.yaml
+apiVersion: keycloak.org/v2alpha1
+kind: KeycloakRealmImport
+metadata:
+  name: my-realm-kc
+spec:
+  keycloakCRName: <name of the keycloak CR>
+  realm:
+    id: example-realm
+    realm: example-realm
+    displayName: ExampleRealm
+    enabled: true
+EOF
+kubectl|oc apply -f example-realm-import.yaml
+----
+
+And you can check the progress of the Import by running:
+
+[source,bash]
+----
+kubectl get keycloakrealmimports/my-realm-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
+----
+
+When the import successfully completed the output will look like follow:
+
+[source,bash]
+----
+CONDITION: Done
+  STATUS: true
+  MESSAGE: 
+CONDITION: Started
+  STATUS: false
+  MESSAGE: 
+CONDITION: HasErrors
+  STATUS: false
+  MESSAGE:
+----
+
+</@tmpl.guide>