Skip to content

ADR-0011: Keycloak Image Base Selection for Image Hardening

  • Status: ✅ Accepted
  • Date: 2026-03-05
  • Owners: @osmank, @ilhan, @halit, @cagkan
  • Related: Image Hardening Initiative, Keycloak Operations Runbook

Context

As part of the Image Hardening initiative, we must decide which base image / Linux distribution we will use for the Keycloak container image.

This decision impacts:

  • Security posture (CVE surface, patch cadence, package set, SBOM/provenance)
  • Operations (upgrade flow, rollback capability, troubleshooting)
  • Compatibility (Helm chart scripts, init logic, OpenShift restricted SCC / runAsNonRoot)
  • Supply-chain trust (image provenance, public policies, retention guarantees)

Decision Drivers

  • Security: Smaller attack surface, predictable patching, ability to generate/verify SBOM and provenance.
  • Operational sustainability: Simple upgrades; ability to support rollback and keep required historical versions.
  • Platform compatibility: Works with existing Helm scripts and runtime assumptions; compatible with OpenShift restricted SCC (non-root).
  • Cost/ownership: Maintenance burden must be acceptable for the owning teams.

Options Considered

Option 1 — Use an image from DHI (Debian-based)

Summary: Use a Debian-based Keycloak image distributed via DHI.

Pros - Debian-based: familiar tooling and shell environment; easier script maintenance. - Common ecosystem knowledge (Docker Hub conventions); easier debugging and incident response. - Low migration cost for existing Helm/chart behaviors.

Cons - Supporting “very old” Keycloak versions may become an internal burden (even if the vendor provides them). - Potentially larger footprint / broader CVE surface compared to minimal distributions. - Hardening may require additional explicit steps (removing packages, tightening permissions, etc.).

Option 2 — Use the Keymate team’s Wolfi-based image

Summary: Use a Wolfi-distribution-based image (minimal / security-oriented).

Pros - Minimal base can reduce the overall attack surface. - Often aligns well with modern supply-chain practices (SBOM/provenance-first workflows). - Encourages staying current with Keycloak versions.

Cons - Must verify compatibility with existing Helm chart scripts and init logic. - Historical image retention (how far back images are kept) and any public retention policy may be unclear. - Operational debugging can be harder due to a less “standard” distro environment.

Note

If Wolfi is selected, we must explicitly validate availability/behavior of required shell tools and utilities (e.g., sh/bash, coreutils, curl/openssl) used by our Helm chart and init containers.

Option 3 — Build and maintain our own image on Ubuntu Chiseled

Summary: Create and operate an Appcircle-managed Keycloak image using Ubuntu Chiseled as the base.

Pros - Minimal base aligns strongly with image hardening goals (smaller footprint, fewer packages). - Full control over hardening standards: users/permissions, CA trust injection, build pipeline, SBOM/provenance, etc. - Consistent internal standards across environments.

Cons - Higher ongoing maintenance cost: rebuild cadence, patch tracking, testing, and release automation. - We become the “image vendor”: operational responsibility increases (security fixes, SLAs, regression risk). - Must continuously track upstream Keycloak changes and ensure compatibility.

Decision

We will use the DHI-provided Keycloak image (Debian-based) as the standard base for Appcircle’s Keycloak deployments.

This option provides the best balance of:

  • Operational stability and familiarity (standard Debian userland and tooling)
  • Lowest migration risk for existing Helm chart behavior and scripting
  • Faster time-to-hardening by focusing on configuration and runtime controls rather than rebuilding the image ecosystem

Note

This ADR defines the base image selection. Image hardening controls (non-root, filesystem, capabilities, etc.) are enforced via our Kubernetes manifests/Helm chart and cluster policies.

Rationale

We accepted Option 1 (DHI / Debian-based) because:

  • The Debian environment is familiar and reduces troubleshooting friction during incidents.
  • Our current Helm chart scripts and init logic are expected to work with minimal or no changes.
  • It keeps ownership boundaries clear: we harden the runtime configuration while relying on the upstream image lineage for base OS maintenance.

Consequences

  • We standardize on a Debian-based Keycloak image, which may have a larger footprint than minimal distros.
  • Hardening gains come primarily from runtime controls (securityContext, filesystem settings, policies) and supply-chain checks (SBOM/provenance), not from base distro minimization.
  • We preserve low-risk upgrades and simpler operational workflows.

Validation Checklist

  • Runs under OpenShift restricted SCC (runAsNonRoot)
  • Works with readOnlyRootFilesystem (or has explicit writable mounts where required)
  • Health/readiness probes are stable under load
  • Upgrade tested (N -> N+1) and rollback tested (N+1 -> N)
  • SBOM generation and image provenance integrated into the build pipeline
  • Helm chart + init script compatibility validated
  • Image retention policy and rollback requirements documented