Architectural Integration of Keycloak within K3s Ecosystems

The intersection of lightweight Kubernetes distributions and enterprise-grade identity management represents a critical pivot point for modern DevOps practitioners. Integrating Keycloak into a K3s cluster creates a robust framework for Identity and Access Management (IAM), allowing organizations to move away from static kubeconfig files and toward a dynamic, role-based access control (RBAC) model. Keycloak serves as a production-ready Identity Provider (IdP) and Identity Broker, providing native support for industry-standard authentication mechanisms including SAML (Security Assertion Markup Language) and OpenID Connect (OIDC). By deploying this on K3s—a certified, lightweight Kubernetes distribution developed by Rancher Labs—users can achieve high-density deployments suitable for everything from edge computing on Raspberry Pi clusters to production-grade cloud workloads. This integration ensures that authentication is decoupled from the application logic, centralizing user management and security policies across a distributed microservices architecture.

Fundamental Infrastructure Components

To successfully execute a Keycloak deployment on K3s, one must understand the symbiotic relationship between the orchestration layer and the identity layer. K3s simplifies the Kubernetes footprint by bundling essential components, making it an ideal target for Keycloak's resource-intensive JVM requirements.

The deployment strategy typically involves several critical components:

• The K3s Cluster: The foundational orchestration layer provided by Rancher Labs. It serves as the runtime environment for all containers and manages the lifecycle of the Keycloak pods.
• Keycloak: The core IAM solution that manages users, sessions, and authentication flows. It acts as the OIDC provider for other services within the cluster, such as Eclipse Che.
• Traefik: The default ingress controller bundled with K3s. It manages external access to the services within the cluster, routing traffic from the public internet to the internal Keycloak service using Ingress or IngressRoute resources.
• Persistent Storage: A mechanism to ensure that Keycloak configuration and user data persist across pod restarts or node failures.

Hardware Architecture and Image Compatibility

A significant hurdle in deploying Keycloak on K3s, particularly for enthusiasts using Single Board Computers (SBCs), is the processor architecture. The official JBoss Keycloak images hosted on Docker Hub (jboss/keycloak) are compiled specifically for the linux/amd64 platform.

For users running K3s on Raspberry Pi hardware, which utilizes the arm64 architecture, the standard images will fail to execute. This creates a critical failure point where the container runtime cannot execute the binary. To resolve this, custom-built images are required. Specifically, the sleighzy/keycloak images on Docker Hub provide the necessary arm64 support, ensuring that the Java runtime and Keycloak binaries are compatible with ARM-based processors. This compatibility layer is essential for maintaining stability in edge computing environments where power efficiency is prioritized over raw x86 performance.

Database Backend Strategies and Persistence

Keycloak requires a backend store for its configuration, realm data, and user credentials. The choice of database profoundly impacts the scalability and reliability of the identity provider.

The implementation supports two primary storage paths:

• H2 Embedded Database: This is a file-system backed database that comes integrated with Keycloak. It is primarily intended for development or very small-scale deployments.
• PostgreSQL Database: A production-grade relational database that provides superior concurrency, reliability, and backup capabilities.

When opting for the H2 embedded database, the deployment process necessitates the application of a specific Persistent Volume Claim (PVC) manifest, such as 300-pvc.yaml. This triggers the K3s local path provisioner storage class.

The use of the local path provisioner introduces a significant architectural constraint in multi-node clusters. Because the storage is created on the specific node where the pod is first scheduled, the data is physically tied to that machine. If the Kubernetes scheduler moves the Keycloak pod to a different node due to resource pressure or node failure, the pod will be unable to locate its configuration or user data, leading to a crash loop. To mitigate this risk, developers must implement pod affinity. Pod affinity ensures that the Keycloak container is strictly scheduled onto the same node where its local storage resides, maintaining the link between the compute resource and the data volume. Alternatively, implementing a shared storage mechanism like NFS (Network File System) would eliminate the need for pod affinity by making the data accessible from any node in the cluster.

Deployment Workflow via Helm and Kubernetes Manifests

The deployment of Keycloak on K3s is often streamlined using Helm, the package manager for Kubernetes. K3s includes a built-in Helm controller that can process HelmChart resources directly from YAML manifests.

The initialization sequence begins with the creation of a dedicated namespace to ensure resource isolation and logical organization. This is achieved by creating a keycloak-namespace.yaml file:

yaml apiVersion: v1 kind: Namespace metadata: name: keycloak

Once the namespace is applied using kubectl apply -f keycloak-namespace.yaml, the installation is handled via a HelmChart resource. This method allows for the configuration of the chart values directly within the Kubernetes manifest. A typical configuration includes the Bitnami chart repository and the specification of administrative credentials.

yaml apiVersion: Helm.cattle.io/v1 kind: HelmChart metadata: name: keycloak namespace: kube-system spec: repo: https://charts.bitnami.com/bitnami chart: keycloak targetNamespace: keycloak valuesContent: |- auth: adminUser: admin adminPassword: admin ingress: enabled: false proxy: edge production: true

In this configuration, the ingress.enabled: false setting is critical because the ingress is handled manually via a separate Traefik configuration to allow for more granular control over SSL and routing. The proxy: edge setting informs Keycloak that it is sitting behind a reverse proxy (Traefik), which is necessary for correct URI generation and header handling.

Ingress Routing and External Access

To expose Keycloak to the external network, a Traefik Ingress resource must be configured. This acts as the gateway, translating external HTTPS requests into internal cluster traffic.

The configuration requires a domain name pointing to the K3s cluster's IP address and a valid SSL certificate, preferably a wildcard subdomain certificate to support multiple services. The keycloak-ingress.yaml file defines how the traffic should be routed:

yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: keycloak-ingress namespace: keycloak annotations: traefik.ingress.kubernetes.io/redirect-entry-point: https spec: ingressClassName: traefik tls: - hosts: - keycloak.example.com rules: - host: keycloak.example.com http: paths: - path: / pathType: Prefix backend: service: name: keycloak port: number: 80

The annotation traefik.ingress.kubernetes.io/redirect-entry-point: https is a critical security measure that forces all HTTP traffic to be upgraded to HTTPS, ensuring that administrative credentials and OIDC tokens are never transmitted in plaintext.

Direct Node Access and Troubleshooting

In scenarios where the ingress is not yet configured or during initial debugging, administrators can use Kubernetes port-forwarding to access the Keycloak admin console. This bypasses the ingress layer and creates a direct tunnel from the local machine or the K3s node to the pod.

To forward the Keycloak service to port 32080 on the K3s node, the following command is used:

bash kubectl port-forward -n keycloak --address 0.0.0.0 service/keycloak 32080:http

This allows the administrator to access the Keycloak interface by navigating to the node's IP address on port 32080. This is particularly useful for verifying that the org.jboss.as Controller Boot Thread has successfully started the admin console, which is typically indicated by the log message WFLYSRV0051: Admin console listening on http://127.0.0.1:9990.

Advanced Integration: Keycloak as an OIDC Provider for K3s

Integrating Keycloak as an external identity provider for the K3s cluster itself elevates the security posture of the environment. Rather than distributing static kubeconfig files—which are essentially "golden keys" that provide permanent access—administrators can implement OpenID Connect (OIDC) for cluster authentication.

The necessity for this arises in professional team environments where roles are diversified. A typical cluster may be accessed by:

• Developers: Requiring access to specific namespaces for deployment and debugging.
• QA Engineers: Needing read-only access to logs and pod statuses.
• DevOps/SREs: Requiring full cluster-admin privileges for infrastructure management.
• Leadership/Release Management: Requiring high-level visibility into deployment status.

By using Keycloak as the OIDC provider, the cluster can validate tokens issued by Keycloak. To implement this, the user requires the oidc-login CLI tool. This tool allows the user to authenticate via the Keycloak login page; upon successful authentication, the tool retrieves an ID token and injects it into the kubectl request. This allows the Kubernetes API server to verify the user's identity and map their Keycloak groups to Kubernetes RBAC roles.

Ecosystem Synergy: Deploying Eclipse Che

One of the primary use cases for a Keycloak-backed K3s cluster is the deployment of Eclipse Che, an open-source IDE for Kubernetes. Eclipse Che relies heavily on OIDC for user authentication and workspace isolation.

The prerequisites for this integration include:

• A functioning K3s cluster.
• Traefik installed as the ingress controller.
• A registered domain and SSL certificates.
• The chectl command-line tool installed on the management machine.

Eclipse Che uses Keycloak to ensure that only authorized users can spawn development workspaces. The integration flow involves configuring the Eclipse Che installation to point toward the Keycloak OIDC endpoint created in the previous steps. This creates a seamless experience where a developer logs into the Che dashboard via Keycloak and is automatically granted access to their specific set of containers and resources based on their identity.

Comparison of Keycloak Deployment Options on K3s

The following table outlines the differences between the two primary storage and architectural paths for deploying Keycloak on a K3s cluster.

Technical Summary of Requirements and Tools

The successful deployment and integration of Keycloak within a K3s environment rely on a specific toolchain and set of configuration assets.

Necessary Tools:

• kubectl: The standard Kubernetes CLI for managing the cluster and applying YAML manifests.
• Helm: Used for deploying the Keycloak chart from the Bitnami repository.
• chectl: Required specifically for the deployment and management of Eclipse Che.
• oidc-login: Necessary for authenticating kubectl requests through Keycloak.
• Traefik v2: The ingress controller used for routing external traffic via Ingress or IngressRoute resources.

Required Manifests:

• keycloak-namespace.yaml: Isolates the identity provider.
• keycloak-chart.yaml: Defines the Helm deployment and admin credentials.
• keycloak-ingress.yaml: Configures the Traefik routing and SSL termination.
• 300-pvc.yaml: (Optional) Manages persistent storage for H2 database deployments.

Final Analysis of the K3s and Keycloak Integration

The deployment of Keycloak on K3s transforms a simple Kubernetes cluster into an enterprise-ready platform. The transition from basic authentication to an OIDC-based model provided by Keycloak is not merely a technical upgrade but a security imperative for any team scaling its operations. By leveraging the lightweight nature of K3s and the comprehensive identity management of Keycloak, administrators can implement a Zero Trust architecture where every request to the cluster is authenticated and authorized.

The critical challenge remains the management of state. The reliance on the local path provisioner for H2 databases creates a fragile link between the pod and the node, which can be solved through either the rigorous application of pod affinity or the migration to a managed PostgreSQL instance. Furthermore, the architectural awareness of CPU instruction sets—specifically the need for arm64 images on Raspberry Pi—is the difference between a successful boot and a CrashLoopBackOff. When these variables are controlled, the resulting system provides a powerful, scalable, and secure foundation for modern cloud-native development, as evidenced by the successful integration of complex tools like Eclipse Che.

Sources

1. k3s-keycloak-deployment GitHub Repository
2. k3s-keycloak-deployment README
3. Deploying Eclipse Che on K3s
4. Using Keycloak with your K3s Cluster