<#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: 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: 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: 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.