mirror of
https://github.com/keycloak/keycloak.git
synced 2026-05-28 04:13:22 -04:00
e891336167
addresses CVE-2025-9162 closes: #42046 Signed-off-by: Steve Hawkins <shawkins@redhat.com>
131 lines
3.7 KiB
Text
131 lines
3.7 KiB
Text
<#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="Automating a realm import"
|
|
summary="Automate a 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.
|
|
|
|
* Once the realm is imported you should delete the Realm Import CR as that will cleanup the associated Kubernetes Job and Pod resources.
|
|
====
|
|
|
|
=== 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.
|
|
|
|
=== Security Considerations
|
|
|
|
[WARNING]
|
|
====
|
|
Anyone with the ability to create or edit KeycloakRealmImport CRs should be a namespace level admin.
|
|
====
|
|
|
|
Placeholder replacement gives access to all environment variables even sensitive ones.
|
|
|
|
</@tmpl.guide>
|