Skip to main content

ADR 005: Tool for Keycloak configuration

Date: 2025-09-04

Status: Accepted

Decision Makers: @cr0ssing @luckey @DerLinne

Context​

In our Kubernetes-based environment, we require a secure, reliable, and maintainable mechanism for managing Keycloak realm configurations across environments. The goal is to automate and declaratively manage realm definitions (clients, users, roles, etc.) while ensuring GitOps compatibility, idempotent application, and cloud-native integration.

Multiple approaches for realm management exist, including:

Declarative tools (e.g., keycloak-config-cli, Keycloak Operator)

Imperative scripting (e.g., curl-based usage of the Keycloak Admin API)

Static import at container startup

A thorough technical and community risk assessment was performed, focusing on factors such as maintainability, documentation, CI/CD integration, community support, and project activity. The tool keycloak-config-cli emerged as the most suitable choice for our use case.

Checked Architecture Principles​

  • [full] – Model-centric data flow
  • [full] – Distributed architecture with unified user experience
  • [full] – Modular design
  • [full] – Integration capability through defined interfaces
  • [full] – Open source as the default
  • [full] – Cloud-native architecture
  • [full] – Prefer standard solutions over custom development
  • [full] – Self-contained deployment
  • [full] – Technological consistency to ensure maintainability
  • [partial] – Multi-tenancy
    • While the tool supports realm-level separation, it does not offer dynamic realm deletion or automated multi-tenant lifecycle management.
  • [full] – Security by design

Decision​

We will use keycloak-config-cli to manage Keycloak realm configurations declaratively within our Kubernetes infrastructure.

Reasons:​

  • Declarative & Idempotent: Supports YAML/JSON configs, safe to reapply without duplication.
  • GitOps-Compatible: Works well in CI/CD, Helm, and ArgoCD environments.
  • Kubernetes-Native: Runs as a Job, InitContainer, or sidecar.
  • Well-Maintained: Active community, fast issue resolution (median 19h), recent commits.
  • Low maintenance risk: License (Apache 2.0), code review, and CI pipelines are in place.

Despite lacking native realm deletion support, this can be addressed using scripting or operator integration where necessary. The trade-off is acceptable given the operational simplicity and stability of the tool.

Consequences​

  • CIVITAS/CORE Infrastructure: Integration of keycloak-config-cli into CI/CD pipelines, Helm charts, and GitOps workflows for automated Keycloak configuration.
  • Security & Auditing: Changes to realm configurations are tracked via Git, improving auditability.
  • Onboarding & Developer Experience: Developers can model realm definitions clearly using versioned, declarative files.
  • Limitations: Realm deletions and certain advanced Keycloak features may require supplemental tooling.

Alternatives​

  • Keycloak Operator (CRDs): Discarded due to increased operational complexity, stability concerns, and limited support for advanced Keycloak features.
  • Admin REST API via curl: Discarded for being imperative, harder to maintain, and lacking reconciliation logic.
  • Startup --import-realm flag: Not suitable due to being non-idempotent and only effective on initial startup of a clean database.

See also​