How to properly use kc.sh in Keycloak on Kubernetes #40708

cfahrni · 2025-06-25T09:17:10Z

cfahrni
Jun 25, 2025

Hi there!

We are running some Keycloak instances using the Keycloak-Operator on Kubernetes and it is working quite good.
We are exploring more features along the way like importing and exporting users or bootstrapping a new admin-account for recovery.

A lot of these processes need the usage of kc.sh and the keycloak instance to be stopped. These commands are well documented but targeted to instances running on VMs.

Currently, i am using initContainers set via spec.unsupported.podTemplate in the keycloak CR, which runs the requested command. I could alter the args of the default keycloak container. But after the command is finished, the container/pod is restarted as part of the StatefulSet due to restartPolicy: Always. So this might lead to unwanted side-effects when the same command is ran multiple times.

The following example would create a full export of a realm to an attached PVC using the initContainer approach:

spec:
  instances: 1
  unsupported:
    podTemplate:
      spec:
        initContainers:
          - name: export
            image: quay.io/keycloak/keycloak:26.2.5
            args:
              - export
              - --dir=/transfer
              - --realm=realm-0
              - --users-per-file=500
            volumeMounts:
              - mountPath: "/transfer"
                name: transfer
            env:
            - name: KC_DB
              value: postgres
            - name: KC_DB_USERNAME
              valueFrom:
                secretKeyRef:
                  key: username
                  name: postgresql-app
            - name: KC_DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  key: password
                  name: postgresql-app
            - name: KC_DB_URL_DATABASE
              value: app
            - name: KC_DB_URL_HOST
              value: postgresql-rw
        volumes:
          - name: transfer
            persistentVolumeClaim:
              claimName: transfer

I am aware of KeycloakRealmImport but i am unsure if this approach is suited to migrate realms with 100-200k users including passwords.

What is the best way to do admin related tasks by using kc.sh when running on Kubernetes?
Thanks for your replies!

Answered by shawkins

Jun 25, 2025

What is the best way to do admin related tasks by using kc.sh when running on Kubernetes?

Unfortunately due to some of the issues you are seeing, you would not try to do this via the operator, but instead create the Job resource on your own.

View full answer

shawkins · 2025-06-25T12:33:19Z

shawkins
Jun 25, 2025
Collaborator

What is the best way to do admin related tasks by using kc.sh when running on Kubernetes?

Unfortunately due to some of the issues you are seeing, you would not try to do this via the operator, but instead create the Job resource on your own.

0 replies

cfahrni · 2025-06-25T13:35:24Z

cfahrni
Jun 25, 2025
Author

Thanks for the hint about the Jobs, that seem to work pretty well!
After scaling down the keycloak CR to 0 instances i was able to create a bootstrap admin with the following job configuration.

apiVersion: batch/v1
kind: Job
metadata:
  name: keycloak-admin-recovery
spec:
  backoffLimit: 1
  template: 
    spec:
      restartPolicy: Never
      containers:
        - name: keycloak
          image: quay.io/keycloak/keycloak:26.2.5
          args: 
            - bootstrap-admin
            - user
            - --username=temp-admin
            - --password:env=PASS_VAR
          env:
          - name: PASS_VAR
            value: CHANGE!ME
          - name: KC_DB
            value: postgres
          - name: KC_DB_URL
            valueFrom:
              secretKeyRef:
                key: jdbc-uri
                name: postgresql-app

1 reply

shawkins Jun 25, 2025
Collaborator

Yes that will work. The recommendation to shut the cluster down for bootstrap-admin is more about preventing users from trying to run the command on the same machine as the running server. Using a Job there shouldn't be a problem doing the bootstrap-admin operation with the cluster running.

Navigation Menu

Repository navigation

How to properly use kc.sh in Keycloak on Kubernetes #40708

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

How to properly use kc.sh in Keycloak on Kubernetes #40708

Uh oh!

cfahrni Jun 25, 2025

Replies: 2 comments · 1 reply

Uh oh!

shawkins Jun 25, 2025 Collaborator

Uh oh!

cfahrni Jun 25, 2025 Author

Uh oh!

shawkins Jun 25, 2025 Collaborator

cfahrni
Jun 25, 2025

Replies: 2 comments 1 reply

shawkins
Jun 25, 2025
Collaborator

cfahrni
Jun 25, 2025
Author

shawkins Jun 25, 2025
Collaborator