feat(keycloak): extraVolumes/extraVolumeMounts for custom themes and providers (1.1.0+up26.8.0)

keycloak/values.yaml

@@ -509,6 +509,111 @@ keycloak:
   # KC_SPI_* provider settings.
   env: []
 
+  # ADDITIONAL VOLUMES AND THEIR MOUNTS - the way a file gets into this pod at
+  # all (Gitea #88). Deliberately GENERIC rather than a theme-specific key:
+  # the same pair serves a custom login theme, an SPI provider JAR and an extra
+  # root CA, and the chart does not have to decide how a theme is delivered
+  # (ConfigMap, Secret, PVC, an init container of your own filling an
+  # emptyDir). Both lists are passed through verbatim, so an entry may use any
+  # Kubernetes volume source.
+  #
+  # THE MOUNTS ARE RENDERED TWICE - ON THE build INIT CONTAINER AND ON THE
+  # SERVING CONTAINER - AND THAT IS THE POINT, NOT AN OVERSIGHT. One list, two
+  # places, because the two cases are resolved at different times:
+  #
+  #   * The SERVING container is where a THEME is read. Themes are a runtime
+  #     concern, so a theme mounted there takes effect in the running server
+  #     even though this chart serves a pre-built installation.
+  #   * The build INIT container is where `kc.sh build` runs (point 2 at the
+  #     top of this file), and a PROVIDER is a build-time concern. Upstream, on
+  #     dropping a provider JAR into providers/: "After that if you are using
+  #     `--optimized`, you must run the `build` command in order to update the
+  #     server's provider registry with the implementations from the JAR file."
+  #     This chart runs `start --optimized`, so a JAR that is mounted only on
+  #     the serving container is absent while the registry is written: it never
+  #     gets registered, the file sits there at runtime, and NOTHING reports
+  #     it - no error, no warning, just an extension that does nothing.
+  #
+  # Not on the SEED init container: it has a different layout (it only writes
+  # the shared volume at /quarkus-build and runs no Keycloak command), so a
+  # mount there would be pointless.
+  #
+  # The side effect of the second place, said out loud rather than discovered:
+  # an extra volume is present AT BUILD TIME as well. For a theme that is
+  # without consequence. For a Secret it means an init container of this pod
+  # sees it too - the same pod either way, but it belongs stated.
+  #
+  # WHAT THIS PAIR DOES NOT DO: it places files, it does not configure
+  # Keycloak. Two cases where that difference is the whole thing:
+  #
+  #   * AN EXTRA ROOT CA IS NOT TRUSTED BY BEING MOUNTED. A file in the pod is
+  #     in no truststore; Keycloak reads one only from truststore-paths, so the
+  #     mount has to be accompanied by KC_TRUSTSTORE_PATHS pointing at the
+  #     mounted DIRECTORY. That is a RUNTIME option (checked against the 26.8.0
+  #     option table, where it carries no build icon), so keycloak.env above is
+  #     the right place for it and the build-option guard does not refuse it.
+  #   * A THEME IS NOT ACTIVATED BY BEING MOUNTED, AND THIS CHART CANNOT
+  #     ACTIVATE IT. The selection lives PER REALM in Keycloak's database
+  #     (Realm settings -> Themes -> Login theme). Mounting makes a theme
+  #     selectable, never selected - so do not go looking for a bug when a
+  #     freshly mounted theme changes nothing.
+  #
+  # THE THEME CASE, AND THE ONE MISTAKE EVERYBODY MAKES EXACTLY ONCE:
+  #
+  # DO NOT MOUNT ON /opt/keycloak/themes. The image's own themes live there
+  # (base, keycloak, keycloak.v2) and a volume at that path HIDES ALL THREE -
+  # the login page is then broken rather than merely unstyled. Mount on a
+  # SUBPATH that does not exist in the image, /opt/keycloak/themes/<name>,
+  # which hides nothing. Same mechanism and same class of mistake as the
+  # "DELIBERATELY NOT MOUNTED: /opt/keycloak/conf" note in the Deployment,
+  # where an emptyDir would hide the cache-ispn.xml that cache=ispn reads.
+  #
+  #   extraVolumes:
+  #     - name: login-theme
+  #       configMap:
+  #         name: my-login-theme
+  #         # A theme's own layout is <theme>/<type>/theme.properties, and a
+  #         # ConfigMap key may not contain a slash - so the subdirectory comes
+  #         # from items[].path, which may.
+  #         items:
+  #           - key: theme.properties
+  #             path: login/theme.properties
+  #   extraVolumeMounts:
+  #     - name: login-theme
+  #       # NOT /opt/keycloak/themes - see above.
+  #       mountPath: /opt/keycloak/themes/my-theme
+  #       readOnly: true
+  #
+  # With that in place a theme.properties carrying
+  #
+  #   parent=keycloak.v2
+  #   kcLogoIdP-<alias> = fa fa-lock
+  #
+  # is what puts an icon on an identity provider's login button - Keycloak has
+  # no logo field on a provider, so a login theme is the only way to set one.
+  #
+  # FOUR PROPERTIES OF THE THEME ROUTE THAT COST TIME IF THEY ARE NOT KNOWN:
+  #
+  #   1. A ConfigMap carries binary content ONLY in binaryData (base64). An SVG
+  #      is text and fits in data; a PNG does not. And the 1 MiB limit per
+  #      ConfigMap applies - ample for a theme with SVG icons, not enough for
+  #      bundled web fonts, which belong in a PVC or an image of your own.
+  #   2. THEMES ARE CACHED, and in production that is wanted. It means a theme
+  #      change takes effect only after a pod restart. Two things add up here:
+  #      this chart hashes no user-supplied ConfigMap either (it renders none of
+  #      its own - point 1 at the top of this file), so editing the theme
+  #      ConfigMap restarts nothing by itself. Use
+  #      `kubectl rollout restart deploy/<release>-keycloak-deployment`.
+  #      Do not configure the cache away to avoid this.
+  #   3. The realm selection is not ours to make - see above.
+  #   4. A CUSTOM LOGIN THEME CAN MAKE THE IDENTITY-PROVIDER BUTTONS DISAPPEAR
+  #      ENTIRELY when its template does not include the social fragment
+  #      correctly (reported repeatedly upstream, keycloak/keycloak#42711).
+  #      After switching a realm's theme, LOOK AT THE LOGIN PAGE - a healthy
+  #      pod says nothing about whether the buttons are still there.
+  extraVolumes: []
+  extraVolumeMounts: []
+
 ingress:
   # The PUBLIC ingress - the login endpoint, the token endpoints, the account
   # console. On by default, because an identity provider nothing can reach is