Keycloak Pipeline自动化配置方案咨询：REST API导入realm问题及替代方案需求

Hey there, let's work through this Keycloak automation challenge you're hitting in your pipeline. Your initial import/export approach ran into the 'Script upload is disabled' error, and since that feature's deprecated, it's smart to shift to a more future-proof solution. Here are the best alternatives for your Docker-hosted Keycloak 15.0.1 setup:

1. Use the Keycloak Admin CLI (kcadm.sh) #

Keycloak's official Admin CLI is built exactly for automation tasks like this, and it avoids the script upload issues you're facing. Here's how to integrate it into your pipeline:

• Wait for Keycloak to be ready: Before running any commands, confirm the Keycloak service is fully up with a simple curl loop checking the master realm endpoint.
• Authenticate with kcadm.sh: Use the initial admin credentials (set via environment variables like KEYCLOAK_USER and KEYCLOAK_PASSWORD in your Docker run command) to log in:

  docker exec <your-keycloak-container-name> /opt/jboss/keycloak/bin/kcadm.sh config credentials \
    --server http://localhost:8080/auth \
    --realm master \
    --user $KEYCLOAK_USER \
    --password $KEYCLOAK_PASSWORD
  

• Apply your configuration: You can either run individual commands to create realms, clients, users, etc., or import a pre-defined JSON config file (exported via kcadm.sh, not the web UI's problematic export):
  • Create a realm directly:

    docker exec <your-keycloak-container-name> /opt/jboss/keycloak/bin/kcadm.sh create realms \
      -s realm=my-pipeline-realm \
      -s enabled=true
    

  • Import a full realm config from a JSON file (mount the file into your container first):

    docker exec <your-keycloak-container-name> /opt/jboss/keycloak/bin/kcadm.sh create realms \
      -f /opt/jboss/keycloak/config/my-realm.json
    

Wrap all these steps into a shell script that your pipeline executes right after starting the Keycloak container.

2. Use Keycloak Startup Scripts #

Keycloak's Docker image automatically runs any scripts placed in the /opt/jboss/startup-scripts/ directory when the container starts. This is perfect for hands-off setup automation.

• Create a startup script: Write a bash script that waits for Keycloak to initialize, authenticates, and applies your configuration. Here's an example:

  #!/bin/bash
  
  # Wait for Keycloak to be ready
  until curl -s http://localhost:8080/auth/realms/master > /dev/null; do
      echo "Waiting for Keycloak to start..."
      sleep 5
  done
  
  # Log in to the admin CLI
  /opt/jboss/keycloak/bin/kcadm.sh config credentials \
    --server http://localhost:8080/auth \
    --realm master \
    --user $KEYCLOAK_USER \
    --password $KEYCLOAK_PASSWORD
  
  # Create your custom realm
  /opt/jboss/keycloak/bin/kcadm.sh create realms \
    -s realm=my-pipeline-realm \
    -s enabled=true \
    -s displayName="Pipeline Test Realm"
  
  # Add a public client for your application
  /opt/jboss/keycloak/bin/kcadm.sh create clients -r my-pipeline-realm \
    -s clientId=pipeline-test-client \
    -s enabled=true \
    -s publicClient=true \
    -s redirectUris=["http://localhost:3000/*"]
  

• Mount the script to your container: When starting Keycloak, mount your script into the startup directory and set admin credentials via environment variables:

  docker run -d \
    -p 8080:8080 \
    -e KEYCLOAK_USER=admin \
    -e KEYCLOAK_PASSWORD=secure-password \
    -v $(pwd)/keycloak-startup.sh:/opt/jboss/startup-scripts/keycloak-startup.sh \
    quay.io/keycloak/keycloak:15.0.1
  

3. Build a Preconfigured Custom Docker Image #

If your Keycloak configuration doesn't change often, build a custom Docker image that includes your pre-setup realm. Your pipeline can then start this image and get a fully configured environment instantly.

• Export your realm config: Use kcadm.sh to export your manually configured realm (this avoids the web UI's script-related export issues):

  docker exec <running-keycloak-container> /opt/jboss/keycloak/bin/kcadm.sh get realms/my-realm -o my-realm.json
  

• Create a Dockerfile: Base it on the official Keycloak image, copy your realm config and an import script:

  FROM quay.io/keycloak/keycloak:15.0.1
  
  # Copy realm config and import script
  COPY my-realm.json /opt/jboss/keycloak/my-realm.json
  COPY import-realm.sh /opt/jboss/startup-scripts/import-realm.sh
  
  # Make the script executable
  RUN chmod +x /opt/jboss/startup-scripts/import-realm.sh
  

• Write the import script: Similar to the startup script, it waits for Keycloak to start and imports the realm:

  #!/bin/bash
  until curl -s http://localhost:8080/auth/realms/master > /dev/null; do
      sleep 5
  done
  
  /opt/jboss/keycloak/bin/kcadm.sh config credentials \
    --server http://localhost:8080/auth \
    --realm master \
    --user $KEYCLOAK_USER \
    --password $KEYCLOAK_PASSWORD
  
  /opt/jboss/keycloak/bin/kcadm.sh create realms -f /opt/jboss/keycloak/my-realm.json
  

• Build and use the image:

  docker build -t my-preconfigured-keycloak .
  

  Your pipeline can pull or run this image directly, no extra setup steps needed.

Important Notes #

• For Keycloak 15.0.1, the kcadm.sh path is /opt/jboss/keycloak/bin/kcadm.sh (newer Quarkus-based Keycloak versions use kc.sh instead, but the core logic stays similar for future upgrades).
• Always wait for Keycloak to fully initialize before running configuration commands—this prevents connection errors.
• All these approaches use official, supported tools, so they'll stay compatible with future Keycloak versions (unlike the deprecated script upload feature).

内容的提问来源于stack exchange，提问作者Stefan Beller