Introduction

Custom Keycloak themes let you brand login pages, account pages, and emails. On Kubernetes, the real challenge is not the theme files themselves, but how those files get into the Keycloak container and how you keep them versioned. For small themes, a mounted volume can work. For larger or long-lived themes, baking them into a custom image is usually cleaner.

Know Where Keycloak Looks for Themes

In modern Keycloak container images, themes typically live under /opt/keycloak/themes. A theme directory usually contains resources such as:

• 'theme.properties'
• Freemarker templates such as .ftl
• CSS and JavaScript assets
• optional image resources

Keycloak only sees the theme if the directory structure matches what it expects.

Option 1: Mount a Theme Into the Pod

For a small theme, a ConfigMap or other mounted volume can work.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: keycloak
5spec:
6  template:
7    spec:
8      containers:
9        - name: keycloak
10          image: quay.io/keycloak/keycloak:latest
11          volumeMounts:
12            - name: theme-volume
13              mountPath: /opt/keycloak/themes/mytheme
14      volumes:
15        - name: theme-volume
16          configMap:
17            name: keycloak-theme

This is convenient for lightweight customization, but large themes are awkward in ConfigMaps and harder to manage cleanly over time.

Option 2: Build a Custom Keycloak Image

For production, a custom image is often the better pattern.

FROM quay.io/keycloak/keycloak:latest
COPY themes/mytheme /opt/keycloak/themes/mytheme

This keeps the theme versioned with the container image and avoids runtime volume surprises. It also makes rollbacks much simpler because the theme and the Keycloak version are deployed together.

Enable the Theme in Keycloak

Mounting or copying the files is only half the work. You still need to select the theme in the realm settings or through configuration management.

For example, in the admin console you would typically set the login theme, account theme, and email theme to your custom theme name.

That is why “the files are in the pod” does not automatically mean “Keycloak is using the theme.”

Kubernetes-Specific Considerations

A few operational details matter on Kubernetes:

• restart pods when the mounted theme changes
• avoid storing large binary theme assets in ConfigMaps
• keep theme content and Keycloak version aligned
• validate that rolling updates do not briefly mix old and new theme states

These are deployment concerns, not just Keycloak concerns.

Common Pitfalls

• Mounting the theme into the wrong path inside the Keycloak container.
• Assuming the theme is active without selecting it in the realm configuration.
• Using ConfigMaps for theme assets that are too large or too numerous.
• Treating theme rollout as separate from Keycloak version rollout when they should be tested together.

Summary

• Keycloak themes must be placed in the directory structure Keycloak expects.
• On Kubernetes, small themes can be mounted, but larger themes are often better baked into a custom image.
• Deploying the files is not enough; the realm must also be configured to use the theme.
• Treat theme delivery as part of the deployment pipeline, not as an ad hoc manual tweak.
• The cleanest production setup usually versions the theme together with the Keycloak container.