# Cloning a Realm to a New Cluster or Region

In scenarios where high availability, regional redundancy, or environment separation (e.g., staging to production) is required, cloning an entire Keycloak realm to a new cluster or region becomes essential. This process involves exporting the realm’s configuration and optionally user data, transferring it securely, and importing it into a fresh Keycloak instance. This guide covers all the required steps, including command-line tooling, configuration handling, and validation checks to ensure a seamless realm replication.

### **Pre-Cloning Preparation**

Before initiating the cloning process, ensure that both the source and target Keycloak clusters are accessible and running compatible versions of Keycloak. This avoids schema mismatches and import errors. Install the Keycloak Admin CLI (<span class="s3">kcadm.sh</span>) and Keycloak Configuration CLI (<span class="s3">keycloak-config-cli</span>) on your local system or CI/CD pipeline.

Deploy a new Keycloak instance in the target cluster or region. This can be done using Docker, Kubernetes, or a managed hosting provider. Example Docker command to spin up a development instance:

```bash
docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev
```

Ensure that network connectivity exists between your machine and the target Keycloak instance. Also, create an admin user for the new instance.

### **Exporting Realm Configuration from the Source Cluster**

To begin the cloning process, export the realm’s full configuration (including clients, roles, groups, and optionally users) using the Keycloak Admin CLI or built-in export tools. If using the Keycloak start command with <span class="s2">--export</span> flag, execute:

```bash
/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users skip
```

To include users in the export:

```bash
/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users all
```

If the Keycloak instance is running in Docker:

```bash
docker exec -it keycloak /opt/keycloak/bin/kc.sh export \
  --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users all
```

The exported realm will be saved as a JSON file, e.g., <span class="s1">myrealm-realm.json</span>.

### **Transferring Exported Data**

Once exported, securely transfer the generated realm export directory or file (<span class="s1">myrealm-realm.json</span>) to the target cluster or region. Depending on your infrastructure, use one of the following methods:

- SCP or SFTP for VM-to-VM transfer:

```
scp myrealm-realm.json user@target-host:/tmp/
```

- AWS S3, Azure Blob Storage, or GCS for multi-cloud environments.
- Git repositories or artifact registries for CI/CD pipelines.

Ensure that the target Keycloak container or pod has access to the file location.

### **Importing Realm into the Target Cluster**

To import the realm into the new Keycloak instance, use the same <span class="s2">kc.sh</span> tool on the target side. The import must be triggered before the Keycloak server starts. If using a container:

```bash
docker run -d --name keycloak-new \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v $(pwd)/export:/opt/keycloak/data/import \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev --import-realm
```

This command will initialize the new Keycloak instance with the cloned realm, including users if they were part of the original export.

Alternatively, if the server is already running, use <span class="s1">kcadm.sh</span> or the <span class="s1">keycloak-config-cli</span> for post-start import. The <span class="s1">keycloak-config-cli</span> is suitable for GitOps-style deployments:

```bash
docker run --rm \
  -e KEYCLOAK_URL=http://localhost:8080 \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin \
  -v "$(pwd)/myrealm:/config" \
  adorsys/keycloak-config-cli:latest
```

### **Post-Cloning Validation**

After the import is complete, validate the integrity of the cloned realm with the following checks:

- Confirm that the new realm appears in the admin console and is accessible at <span class="s1">/realms/myrealm</span>.
- Inspect clients to verify that client IDs, redirect URIs, and secrets have been preserved.
- Validate that roles, groups, and permissions are correctly replicated.
- Test login using a few sample user accounts if users were exported.
- Decode access tokens to confirm the correctness of claims, issuer, and audience.
- Check identity provider connections (e.g., Google, LDAP) and test federated logins.
- Enable auditing under <span class="s1">**Events &gt; Settings**</span> to monitor realm activity in the new instance.
- Update <span class="s1">baseUrl</span> settings for clients if moving across DNS regions.
- Ensure SMTP settings, themes, and custom scripts are present and functioning.
- Enable TLS and update public frontend URLs if applicable.
- Verify realm-specific settings like session timeout, brute force detection, and required actions.