Keycloak Setup

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
AD	Active Directory	微软活动目录
API	Application Programming Interface	应用程序编程接口
CR	Custom Resource	Kubernetes 自定义资源对象
DB	Database	数据库
GitOps	GitOps	以 Git 保存期望状态、由自动化持续协调实际状态的运维方式
HA	High Availability	高可用
HTTP	Hypertext Transfer Protocol	超文本传输协议
HTTPS	Hypertext Transfer Protocol Secure	使用 TLS 加密的 HTTP
IdP	Identity Provider	身份提供方
JWKS	JSON Web Key Set	JSON Web 密钥集，常用于验证令牌签名
LDAP	Lightweight Directory Access Protocol	轻量级目录访问协议
OIDC	OpenID Connect	基于 OAuth 2.0 的身份认证协议
OLM	Operator Lifecycle Manager	Kubernetes Operator 生命周期管理器
SAML	Security Assertion Markup Language	安全断言标记语言，用于身份联合
SMTP	Simple Mail Transfer Protocol	简单邮件传输协议
TLS	Transport Layer Security	传输层安全协议
VM	Virtual Machine	虚拟机

Links#

https://www.keycloak.org/server/containers
https://www.keycloak.org/server/configuration-production
https://www.keycloak.org/server/db
https://www.keycloak.org/server/hostname
https://www.keycloak.org/server/reverseproxy
https://www.keycloak.org/operator/installation
https://www.keycloak.org/operator/basic-deployment

1. Linux VM With systemd#

VM 部署适合小规模、传统网络、没有 Kubernetes 的环境。生产上仍然要使用 external PostgreSQL、HTTPS、反向代理和系统级监控。

layout:
    /opt/keycloak
    /etc/keycloak/keycloak.conf
    /var/log/keycloak
    /etc/keycloak/tls

Example config:

hostname=sso.example.com
http-enabled=false
https-certificate-file=/etc/keycloak/tls/tls.crt
https-certificate-key-file=/etc/keycloak/tls/tls.key

db=postgres
db-url=jdbc:postgresql://postgres.example.com:5432/keycloak
db-username=keycloak
db-password=${KC_DB_PASSWORD}

health-enabled=true
metrics-enabled=true
http-management-scheme=http
proxy-headers=xforwarded

systemd unit:

[Unit]
Description=Keycloak
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=keycloak
Group=keycloak
EnvironmentFile=/etc/keycloak/keycloak.env
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --config-file=/etc/keycloak/keycloak.conf
Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

operations:

sudo systemctl daemon-reload
sudo systemctl enable --now keycloak
sudo systemctl status keycloak
journalctl -u keycloak -f

2. Docker#

Docker local dev:

docker run --name keycloak-demo --rm -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me_now quay.io/keycloak/keycloak:latest start-dev

本地集成 Compose（固定占位密码仅用于隔离学习，不作为生产部署）：

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: change_me_db
    volumes:
      - postgres-data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command:
      - start
    environment:
      KC_HOSTNAME: sso.example.com
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "true"
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: change_me_db
      KC_HTTP_MANAGEMENT_SCHEME: "http"
      KC_HEALTH_ENABLED: "true"
      KC_METRICS_ENABLED: "true"
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: change_me_now
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:8080:8080"

volumes:
  postgres-data:

notes:

for production:
    do not use start-dev
    use managed PostgreSQL or HA PostgreSQL
    put TLS at load balancer or Keycloak
    use secrets instead of plaintext compose env
    pin image version, do not blindly use latest

3. K8S With Operator#

Keycloak has an official Operator. For production Kubernetes, prefer OLM with manual approval, or a carefully governed GitOps manifest. Community Helm charts can be useful, but treat them as third-party packaging and review upgrade behavior.

OLM baseline:

recommended:
    install Keycloak Operator through OLM
    use manual approval for Operator upgrades
    test Keycloak and Operator upgrades in staging first
    backup database before approving production upgrade

Operator install without OLM:

kubectl create namespace keycloak
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.3/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.3/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl -n keycloak apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.3/kubernetes/kubernetes.yml

Minimal Keycloak CR:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
  namespace: keycloak
spec:
  instances: 3
  db:
    vendor: postgres
    host: postgres.example.com
    database: keycloak
    usernameSecret:
      name: keycloak-db
      key: username
    passwordSecret:
      name: keycloak-db
      key: password
  hostname:
    hostname: sso.example.com
  http:
    tlsSecret: keycloak-tls
  additionalOptions:
    - name: health-enabled
      value: "true"
    - name: metrics-enabled
      value: "true"
    - name: http-management-scheme
      value: "http"

Verify:

kubectl -n keycloak get pods
kubectl -n keycloak get keycloak
kubectl -n keycloak logs deploy/keycloak -f
kubectl -n keycloak describe keycloak keycloak

Network policy baseline:

allow ingress:
    from ingress controller namespace to Keycloak HTTP/HTTPS port

allow egress:
    to PostgreSQL
    to external LDAP / AD if User Federation is used
    to upstream IdP metadata / JWKS endpoints
    to SMTP if email is used

deny:
    random namespace to admin endpoint

4. High Availability#

HA requirements:
    at least 2-3 Keycloak replicas
    external HA PostgreSQL
    shared hostname behind load balancer
    sticky sessions can help, but do not rely on a single pod
    readiness probe and rolling update configured
    DB connection pool sized for replicas

Capacity starting point:

estimate:
    peak login requests per minute
    token refresh rate
    admin/API automation rate
    number of apps / clients
    external LDAP / AD lookup latency if User Federation is used

scale:
    increase replicas for stateless HTTP pressure
    increase DB capacity for session/event/write pressure
    tune cache and DB pool only after metrics show bottleneck

Backup:

must backup:
    PostgreSQL database
    Keycloak signing keys
    custom themes
    realm config export
    secret manager entries

restore test:
    restore DB snapshot into isolated environment
    start Keycloak with same version
    verify admin login
    verify OIDC discovery
    verify one OIDC app and one SAML app

5. Operations#

Rolling restart:

kubectl -n keycloak rollout restart deployment/keycloak
kubectl -n keycloak rollout status deployment/keycloak

Useful checks:

# 此处明确配置 KC_HTTP_MANAGEMENT_SCHEME=http；管理端口不发布到公网。
# 选中一个 Keycloak Pod，另一终端保持 port-forward 运行：
kubectl -n keycloak port-forward pod/REPLACE_KEYCLOAK_POD 9000:9000 --address=127.0.0.1
# 新终端：
curl -fsS http://127.0.0.1:9000/health/ready
curl -fsS http://127.0.0.1:9000/metrics
curl -fsS https://sso.example.com/realms/master/.well-known/openid-configuration

Upgrade checklist:

before:
    read Keycloak release notes
    backup database
    export realm config
    test upgrade in staging

during:
    upgrade one environment at a time
    watch logs, HTTP 5xx, DB pool, login errors
    verify OIDC, SAML, LDAP federation, admin console

rollback:
    rollback container/version only if DB schema is compatible
    otherwise restore DB snapshot into previous version
    keep version-specific runbook for major upgrades

Common diagnostics:

kubectl -n keycloak get pods -o wide
kubectl -n keycloak describe pod REPLACE_POD_NAME
kubectl -n keycloak logs <pod> --previous
kubectl -n keycloak top pod
kubectl -n keycloak get events --sort-by=.lastTimestamp

管理端口默认 9000，HTTP/HTTPS 必须与实际配置一致。VM 路径在主机回环访问；Kubernetes 路径使用私有管理 Service/探针及 NetworkPolicy，禁止在公网反向代理暴露该端口。官方管理接口。完整部署与恢复见生产演练。