Skip to main content

PRD: Keycloak Theme Storage Issue

Problem Statement​

The Keycloak custom theme JAR file exceeds Kubernetes ConfigMap size limits (1MB), preventing deployment via standard Kubernetes manifests or Terraform providers.

Current Behavior​

Deployment fails with:

ConfigMap "kube-dc-theme" is invalid: []: Too long: may not be more than 1048576 bytes

Root Cause​

  1. Theme JAR file size: The kube-dc-theme.jar file is larger than 1MB
  2. ConfigMap limit: Kubernetes ConfigMaps have a hard limit of 1MB (1,048,576 bytes)
  3. Terraform limitation: The Terraform Kubernetes provider doesn't support binaryData field, requiring workarounds

Current Workaround​

Theme deployment is disabled in template.yaml:

# NOTE: keycloak-theme disabled - JAR file exceeds ConfigMap 1MB limit
# TODO: Use PVC or external storage for theme JAR

Keycloak runs with default theme.

Requirements​

Must Have​

  1. Deploy custom Keycloak theme to cluster
  2. Theme survives pod restarts
  3. Automated deployment via cdev stack

Should Have​

  1. Easy theme updates without full redeployment
  2. Version tracking for theme files

Could Have​

  1. Support multiple themes per environment
  2. Theme hot-reload without Keycloak restart

Proposed Solutions​

Option A: PersistentVolumeClaim with Init Container​

Store theme JAR in a PVC, use init container to download/copy theme.

initContainers:
  - name: theme-loader
    image: busybox
    command: ['sh', '-c', 'wget -O /themes/kube-dc-theme.jar https://storage.example.com/themes/kube-dc-theme.jar']
    volumeMounts:
      - name: themes
        mountPath: /themes
volumes:
  - name: themes
    persistentVolumeClaim:
      claimName: keycloak-themes

Pros:

  • No size limit
  • Easy to update themes
  • Standard Kubernetes pattern

Cons:

  • Requires external storage for theme source
  • Additional PVC management

Option B: Custom Keycloak Image​

Build custom Keycloak image with theme baked in.

FROM quay.io/keycloak/keycloak:latest
COPY kube-dc-theme.jar /opt/keycloak/providers/

Pros:

  • Simple deployment
  • Theme versioned with image
  • No runtime dependencies

Cons:

  • Requires image rebuild for theme changes
  • Need container registry access
  • Larger image size

Option C: Split Theme into Multiple ConfigMaps​

Split the JAR contents into multiple smaller ConfigMaps and reassemble.

Pros:

  • Works within Kubernetes native resources

Cons:

  • Complex assembly logic
  • Fragile during updates
  • Not recommended

Option D: External Theme Registry (S3/HTTP)​

Configure Keycloak to load themes from external URL.

Pros:

  • Unlimited size
  • Easy updates
  • Centralized theme management

Cons:

  • External dependency
  • Network availability requirement
  • Additional infrastructure

Option B: Custom Keycloak Image for production, with CI/CD pipeline to rebuild on theme changes.

For development/testing, Option A: PVC with Init Container using local file server.

Affected Files​

  • /home/voa/projects/kube-dc.cloud/installer/kube-dc/templates/kube-dc/template.yaml
  • /home/voa/projects/kube-dc.cloud/installer/kube-dc/templates/kube-dc/keycloak/theme-configmap.yaml
  • /home/voa/projects/kube-dc.cloud/installer/kube-dc/templates/kube-dc/keycloak/kube-dc-theme.jar

Implementation Steps​

  1. Set up container registry access (if using Option B)
  2. Create Dockerfile with theme included
  3. Build and push custom Keycloak image
  4. Update Keycloak Helm values to use custom image
  5. Remove/update theme-configmap.yaml references
  6. Test theme appears in Keycloak admin console

Success Criteria​

  1. Keycloak displays custom theme on login page
  2. Theme persists after pod restarts
  3. Deployment completes without errors
  4. Theme updates can be applied via cdev stack

Priority​

Medium - Cosmetic issue, default theme functional

File Details​

Theme JAR location: installer/kube-dc/templates/kube-dc/keycloak/kube-dc-theme.jar
Theme source: hack/keycloak-theme/
Build script: hack/keycloak-theme/build-theme.sh