在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收

July 02, 2026

在 Kubernetes 上安装 Keycloak，最容易被写成一串命令，但最重要的还是装完以后，怎么判断这个 Keycloak 真的能被系统接入。

Pod run 起来还不够，Ingress 地址、Realm 路径、OIDC discovery、token endpoint、client credentials 这些东西只要有一个有问题，后面接 Harbor、网关或者后端服务时都得过来看安装配置和设置。

这篇按 Keycloak 26.x 的默认路径来写。默认情况下没有老版本常见的 /auth 前缀；如果你通过反向代理或 http-relative-path 明确把 Keycloak 暴露在 /auth 下，以 discovery document 里返回的 endpoint 为准。

准备工作

Keycloak 官方的 Kubernetes getting started 文档适合快速跑起来：用 quickstarts 里的 manifest 创建 StatefulSet 和 Service，再用 Minikube Ingress 或 NodePort 访问。它适合验证概念，不是生产模板。

接近生产时，先看官方 single-cluster deployment 文档。那里讨论的是多副本、数据库、高可用、延迟、容量和观测这些问题。Keycloak 不是一个普通无状态服务；一旦进生产，数据库、会话、升级窗口和反向代理配置都要一起设计。

我这里保留的是一个 staging / 自用集群里实际走过的 Helm 路径：用 Bitnami chart 安装，再用 OIDC discovery 和 client credentials 做最小验收。它的价值是够具体，能把常见坑暴露出来；它不是对生产环境的完整承诺。

准备条件：

一个可用的 Kubernetes 集群和当前 kubectl context。
本地有 helm、curl、jq（方便简单处理 Json）。
已经准备好自己的 keycloak-values-staging.yaml 和 keycloak-secret-staging.yaml。
知道目标 Realm 名称，或者安装后先在 Admin Console 里创建。

拉取 Helm chart

先加 Bitnami repo：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

然后拉取指定 chart：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm pull bitnami/keycloak --version 25.2.0 --untar --destination ./

如果旧 chart 或网络环境已经受 Bitnami catalog 调整影响，也可以从 OCI chart 拉：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm pull oci://registry-1.docker.io/bitnamicharts/keycloak \
  --version 25.2.0 \
  --untar \
  --destination ./

准备 namespace 和 Secret

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl create namespace infra-keycloak
kubectl apply -f ./keycloak-secret-staging.yaml

Secret 文件里通常会放管理员账号、数据库密码、外部数据库连接信息等。不要把示例密码顺手带到共享环境里。Keycloak 官方 getting started 里用 admin/admin 是为了本地入门，不应该出现在生产环境。

安装 Keycloak

如果直接用 Bitnami chart 时遇到镜像拉取问题，可以把相关镜像仓库显式切到 bitnamilegacy/*：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm install keycloak ./keycloak \
  --namespace infra-keycloak \
  --create-namespace \
  --values ./keycloak-values-staging.yaml \
  --set image.repository=bitnamilegacy/keycloak \
  --set keycloakConfigCli.image.repository=bitnamilegacy/keycloak-config-cli \
  --set postgresql.image.repository=bitnamilegacy/postgresql \
  --set postgresql.volumePermissions.image.repository=bitnamilegacy/os-shell \
  --set postgresql.metrics.image.repository=bitnamilegacy/postgres-exporter \
  --set global.security.allowInsecureImages=true

这是一种迁移期 fallback，不是长期生产方案。Bitnami issue 里说得很直白：legacy repository 是归档旧镜像，不再接收更新、修复或支持。生产环境应该迁移到受支持的镜像、Operator、外部数据库方案，或者明确接受对应的维护成本。

后续只改 values 或镜像配置，用 helm upgrade：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm upgrade keycloak ./keycloak \
  --namespace infra-keycloak \
  --values ./keycloak-values-staging.yaml \
  --set image.repository=bitnamilegacy/keycloak \
  --set keycloakConfigCli.image.repository=bitnamilegacy/keycloak-config-cli \
  --set postgresql.image.repository=bitnamilegacy/postgresql \
  --set postgresql.volumePermissions.image.repository=bitnamilegacy/os-shell \
  --set postgresql.metrics.image.repository=bitnamilegacy/postgres-exporter \
  --set global.security.allowInsecureImages=true

安装后先看 Pod 和 Service：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl -n infra-keycloak get pods
kubectl -n infra-keycloak get svc

本地调试可以先做 port-forward：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl -n infra-keycloak port-forward svc/keycloak 8080:80

然后访问：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080

如果你环境里的 Service 名或端口不一样，以 kubectl -n infra-keycloak get svc 的结果为准。

先验收路径，不要猜 `/auth`

Keycloak 26.x 默认 root context path 下，Realm 地址通常是：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/<realm>

OIDC discovery endpoint 是：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/<realm>/.well-known/openid-configuration

用 curl 看一眼：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export KC="http://localhost:8080"
export REALM="my-realm"

curl -fsSL "$KC/realms/$REALM/.well-known/openid-configuration" \
  | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint}'

正常情况下，token_endpoint 会长这样：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/my-realm/protocol/openid-connect/token

如果你看到的是 /auth/realms/...，说明你的部署或反向代理确实把 Keycloak 放在了 /auth 下。反过来，如果你只是照旧文章写了 /auth，但 discovery document 里没有它，后面的 token 请求就会错。这里不要靠记忆，直接信 discovery。

用最小 token flow 验收

验收目标：

Realm 的 OIDC metadata 能正常返回。
一个 confidential client 能通过 client_credentials 换到 access token。

先在 Admin Console 里创建一个测试 client，比如：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

Client ID: payment-service
Client authentication: On
Service accounts roles: On
Standard flow: Off
Direct access grants: Off

保存后复制 client secret，然后请求 token：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export CLIENT_ID="payment-service"
export CLIENT_SECRET="<client-secret>"

curl -s -X POST "$KC/realms/$REALM/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  | jq '{token_type, expires_in, access_token}'

如果这里能拿到 access_token，至少说明这几件事已经搞定了：Realm 存在，token endpoint 路径正确，client 是 confidential client，client secret 生效，Keycloak 的 OIDC 基本链路可用。

能拿到 token 不等于业务权限已经配置好。后端服务如果要校验 roles、audience 或 client scopes，还要继续配置 service account roles、scope mappings、aud mapper 等。

Admin token

有时你想确认 Admin API 也能通，可以临时用 master realm 的 admin-cli 换一个 admin token：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export ADMIN_USER="admin"
export ADMIN_PASSWORD="<admin-password>"

export ADMIN_TOKEN=$(
  curl -s -X POST "$KC/realms/master/protocol/openid-connect/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=admin-cli" \
    -d "grant_type=password" \
    -d "username=$ADMIN_USER" \
    --data-urlencode "password=$ADMIN_PASSWORD" \
    | jq -r '.access_token'
)

curl -fsSL "$KC/admin/realms/$REALM/clients" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq 'length'

这只适合受控脚本、本地验证和一次性迁移。面向用户登录，不要用用户名密码直换 token。Keycloak 的 OIDC 文档已经按 OAuth 2.0 Security BCP / RFC 9700 的口径提醒，Direct Access Grants / Resource Owner Password Credentials 这条路不该用于生产环境的认证。

重点检查这几项

helm 装的是你想要的 chart，镜像 tag 和 Keycloak 应用版本单独核对过。
bitnamilegacy/* 只作为临时 fallback，没有被当成长期生产来源。
kubectl -n infra-keycloak get pods 里 Pod 稳定运行，Service 端口和 port-forward 命令对得上。
/.well-known/openid-configuration 能返回，并且 issuer、token_endpoint 是你准备给业务系统使用的地址。
Keycloak 26.x 默认路径没有 /auth；只有你显式配置了反向代理路径或 http-relative-path 时才带 /auth。
client_credentials 能拿到 access token。
如果用了 Admin API 验收，ADMIN_TOKEN 不为空，且能访问目标 Realm 的 clients 列表。

参考

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收

July 02, 2026

在 Kubernetes 上安装 Keycloak，最容易被写成一串命令，但最重要的还是装完以后，怎么判断这个 Keycloak 真的能被系统接入。

准备工作

准备条件：

一个可用的 Kubernetes 集群和当前 kubectl context。
本地有 helm、curl、jq（方便简单处理 Json）。
已经准备好自己的 keycloak-values-staging.yaml 和 keycloak-secret-staging.yaml。
知道目标 Realm 名称，或者安装后先在 Admin Console 里创建。

拉取 Helm chart

先加 Bitnami repo：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

然后拉取指定 chart：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm pull bitnami/keycloak --version 25.2.0 --untar --destination ./

如果旧 chart 或网络环境已经受 Bitnami catalog 调整影响，也可以从 OCI chart 拉：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm pull oci://registry-1.docker.io/bitnamicharts/keycloak \
  --version 25.2.0 \
  --untar \
  --destination ./

准备 namespace 和 Secret

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl create namespace infra-keycloak
kubectl apply -f ./keycloak-secret-staging.yaml

安装 Keycloak

如果直接用 Bitnami chart 时遇到镜像拉取问题，可以把相关镜像仓库显式切到 bitnamilegacy/*：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm install keycloak ./keycloak \
  --namespace infra-keycloak \
  --create-namespace \
  --values ./keycloak-values-staging.yaml \
  --set image.repository=bitnamilegacy/keycloak \
  --set keycloakConfigCli.image.repository=bitnamilegacy/keycloak-config-cli \
  --set postgresql.image.repository=bitnamilegacy/postgresql \
  --set postgresql.volumePermissions.image.repository=bitnamilegacy/os-shell \
  --set postgresql.metrics.image.repository=bitnamilegacy/postgres-exporter \
  --set global.security.allowInsecureImages=true

后续只改 values 或镜像配置，用 helm upgrade：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

helm upgrade keycloak ./keycloak \
  --namespace infra-keycloak \
  --values ./keycloak-values-staging.yaml \
  --set image.repository=bitnamilegacy/keycloak \
  --set keycloakConfigCli.image.repository=bitnamilegacy/keycloak-config-cli \
  --set postgresql.image.repository=bitnamilegacy/postgresql \
  --set postgresql.volumePermissions.image.repository=bitnamilegacy/os-shell \
  --set postgresql.metrics.image.repository=bitnamilegacy/postgres-exporter \
  --set global.security.allowInsecureImages=true

安装后先看 Pod 和 Service：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl -n infra-keycloak get pods
kubectl -n infra-keycloak get svc

本地调试可以先做 port-forward：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

kubectl -n infra-keycloak port-forward svc/keycloak 8080:80

然后访问：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080

如果你环境里的 Service 名或端口不一样，以 kubectl -n infra-keycloak get svc 的结果为准。

先验收路径，不要猜 `/auth`

Keycloak 26.x 默认 root context path 下，Realm 地址通常是：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/<realm>

OIDC discovery endpoint 是：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/<realm>/.well-known/openid-configuration

用 curl 看一眼：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export KC="http://localhost:8080"
export REALM="my-realm"

curl -fsSL "$KC/realms/$REALM/.well-known/openid-configuration" \
  | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint}'

正常情况下，token_endpoint 会长这样：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

http://localhost:8080/realms/my-realm/protocol/openid-connect/token

用最小 token flow 验收

验收目标：

Realm 的 OIDC metadata 能正常返回。
一个 confidential client 能通过 client_credentials 换到 access token。

先在 Admin Console 里创建一个测试 client，比如：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (text)

Client ID: payment-service
Client authentication: On
Service accounts roles: On
Standard flow: Off
Direct access grants: Off

保存后复制 client secret，然后请求 token：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export CLIENT_ID="payment-service"
export CLIENT_SECRET="<client-secret>"

curl -s -X POST "$KC/realms/$REALM/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  | jq '{token_type, expires_in, access_token}'

能拿到 token 不等于业务权限已经配置好。后端服务如果要校验 roles、audience 或 client scopes，还要继续配置 service account roles、scope mappings、aud mapper 等。

Admin token

有时你想确认 Admin API 也能通，可以临时用 master realm 的 admin-cli 换一个 admin token：

在 Kubernetes 上安装 Keycloak：从 Helm 到 OIDC 验收 (shell)

export ADMIN_USER="admin"
export ADMIN_PASSWORD="<admin-password>"

export ADMIN_TOKEN=$(
  curl -s -X POST "$KC/realms/master/protocol/openid-connect/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=admin-cli" \
    -d "grant_type=password" \
    -d "username=$ADMIN_USER" \
    --data-urlencode "password=$ADMIN_PASSWORD" \
    | jq -r '.access_token'
)

curl -fsSL "$KC/admin/realms/$REALM/clients" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq 'length'

重点检查这几项

helm 装的是你想要的 chart，镜像 tag 和 Keycloak 应用版本单独核对过。
bitnamilegacy/* 只作为临时 fallback，没有被当成长期生产来源。
kubectl -n infra-keycloak get pods 里 Pod 稳定运行，Service 端口和 port-forward 命令对得上。
/.well-known/openid-configuration 能返回，并且 issuer、token_endpoint 是你准备给业务系统使用的地址。
Keycloak 26.x 默认路径没有 /auth；只有你显式配置了反向代理路径或 http-relative-path 时才带 /auth。
client_credentials 能拿到 access token。
如果用了 Admin API 验收，ADMIN_TOKEN 不为空，且能访问目标 Realm 的 clients 列表。