keycloak-scim/docs/guides/operator/realm-import.adoc

<#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="{project_name} Realm Import"
priority=30
summary="How to perform an automated {project_name} Realm Import using the operator">

== Importing a {project_name} Realm

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

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

* 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.
====

=== Creating a Realm Import Custom Resource

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

[source,yaml]
----
apiVersion: k8s.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 {apidocs_adminrest_link}/index.html#RealmRepresentation[RealmRepresentation].

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

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

=== Applying the Realm Import CR

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

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

[source,yaml]
----
apiVersion: k8s.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
----

Apply the changes:

[source,bash]
----
kubectl apply -f example-realm-import.yaml
----

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

[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 has successfully completed, the output will look like the following example:

[source,bash]
----
CONDITION: Done
  STATUS: true
  MESSAGE: 
CONDITION: Started
  STATUS: false
  MESSAGE: 
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
----

=== Placeholders

Imports support placeholders referencing environment variables, see <@links.server id="importExport"/> for more. 
The `KeycloakRealmImport` CR allows you to leverage this functionality via the `spec.placeholders` stanza, for example:

[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  placeholders:
    ENV_KEY:
      secret:
        name: SECRET_NAME
        key: SECRET_KEY
    ...
----

In the above example placeholder replacement will be enabled and an environment variable with key `ENV_KEY` will be created from the Secret `SECRET_NAME`'s value for key `SECRET_KEY`. 
Currently only Secrets are supported and they must be in the same namespace as the Keycloak CR.
  
</@tmpl.guide>