Deploy Keycloak with PostgreSQL on Kubernetes

Deploying Keycloak on Kubernetes with a persistent backend requires a PostgreSQL StatefulSet, NetworkPolicies to isolate the database, and an Ingress to expose the auth endpoints externally. This template configures all of that in a single manifest, giving you a complete deploy Keycloak on Kubernetes setup with PostgreSQL persistence, network-level database isolation, and external access to the Keycloak admin console and authentication endpoints.

What's Included

Architecture Overview

Keycloak runs as a Deployment configured via a ConfigMap that sets the database connection details and runtime environment. PostgreSQL runs as a StatefulSet with a PVC for data durability, exposed internally via a headless Service. A NetworkPolicy enforces that only the Keycloak pod can reach the PostgreSQL port, blocking all other cluster traffic to the database. The NGINX Ingress routes external requests to the Keycloak Service for authentication and admin console access.

Prerequisites

• A running Kubernetes cluster
• NGINX Ingress Controller installed
• A domain name pointed at your cluster's ingress IP
• KubeKanvas CLI installed and running on your computer (Optional, if you want to use one-click deployment)

How to Deploy

1. Click on the button at the top right corner of this screen to load the manifest into the editor.
2. Update the ConfigMap with your PostgreSQL connection details and Keycloak admin credentials.
3. Verify the NetworkPolicy label selectors match the pod labels in your Deployment and namespace.
4. Set your domain name in the Ingress configuration.
5. Deploy the template to your cluster via the Play button in the top right bar. If you prefer to deploy manually, download the YAML and apply it with kubectl.
6. Wait for all pods to reach Running status. You can monitor progress in the Release Monitor screen.

How to Test

1. Confirm Keycloak and PostgreSQL pods are running either using release monitor screen or using kubectl: kubectl get pods -n <namespace>.
2. Open https://<your-domain>/auth/admin and verify the Keycloak admin console loads.
3. Log in with your admin credentials and confirm the master realm is accessible.

Use Cases

• Cluster-internal SSO provider: Running Keycloak as a centralized OpenID Connect and OAuth2 server for multiple applications on the same cluster.
• Network-isolated IAM database: Enforcing that PostgreSQL is only reachable from the Keycloak pod using NetworkPolicy, with no other in-cluster access.
• Declarative identity management: Managing Keycloak deployment and configuration as Kubernetes manifests within a GitOps workflow.
• Self-hosted OAuth2 server: Replacing a third-party identity provider with a cluster-native Keycloak instance backed by a persistent database.

Summary

This template configures a Keycloak deployment on Kubernetes backed by a PostgreSQL StatefulSet, with NetworkPolicy-enforced database isolation and external ingress routing preconfigured.