在 Kubernetes 上运行 Casdoor:官方 Helm Chart 与配置即代码
Casdoor 拥有一个官方 Helm chart。它位于主仓库的 manifests/casdoor 目录下,随每个 Casdoor 版本发布到 GHCR,并收录于 Artifact Hub。从 Casdoor v4.18.0 开始,该 chart 还可以将您的组织、应用、用户和提供商作为声明式配置进行管理:修改 values 文件,运行 helm upgrade,正在运行的 Pod 即可应用更改而无需重启。
本文将介绍如何在 Kubernetes 上进行部署,从首次执行 helm install 到实现可纳入 Git 管理的配置设置。
安装
您需要 Helm v3.8+ 和一个集群:
helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor
Chart 版本即为 Casdoor 版本,因此 --version 4.18.0 会安装 Casdoor 4.18.0。如果没有 Ingress 或 Gateway,服务只能在集群内部访问。若要尝试,请转发端口:
kubectl port-forward svc/casdoor 8000:8000
然后打开 http://localhost:8000。首次访问时,Casdoor 会要求您设置 built-in/admin 的密码;随后使用该密码登录。请参阅 登录管理控制台。
生产环境设置
默认设置仅适用于快速试用:Casdoor 将数据存储在容器内的 SQLite 中,因此当 Pod 被替换时数据会丢失。对于实际部署,请将以下设置放入 values.yaml 文件,并使用 helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor -f values.yaml 进行安装。
外部数据库
database:
driver: postgres # or mysql, cockroachdb
host: postgres.db.svc.cluster.local
user: casdoor
password: change-me
databaseName: casdoor
sslMode: require
为避免将数据库密码写入 values 文件,请将整个 app.conf 放入 Secret 中,并将 configFromSecret 设置为该 Secret 的名称。
暴露 Casdoor
该 chart 同时支持传统的 Ingress 和 Gateway API。配合 Ingress controller 和 cert-manager:
ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
hosts:
- host: door.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: casdoor-tls
hosts:
- door.example.com
使用 Gateway API(Istio、Envoy Gateway、Cilium、Kong、NGINX Gateway Fabric 等),将 HTTPRoute 附加到现有的 Gateway:
gatewayApi:
enabled: true
parentRefs:
- name: my-gateway
namespace: gateway-system
hostnames:
- door.example.com
该 chart 也可以自行创建 Gateway 并添加 HTTP 到 HTTPS 的重定向,详见 Helm 指南。
多副本部署
Casdoor 默认将登录会话保存在本地磁盘上。在运行多个副本之前,请将所有副本指向同一个 Redis,以便无论哪个 Pod 处理请求,用户都能保持登录状态。每个 app.conf 设置都可以作为环境变量传递,因此端点可以从 Secret 获取:
replicaCount: 3
envFromSecret:
- name: redisEndpoint
secretName: casdoor-redis
key: endpoint # host:port, or host:port,db,password
OAuth 设备流程的状态也使用同一个 Redis。一旦配置好 Redis,设置 autoscaling.enabled: true 就会添加一个 HorizontalPodAutoscaler。
配置即代码
在 Web UI 中点击创建组织和应用适合初步测试,但大多数团队希望像管理基础设施的其他部分一样,对身份提供者的配置进行审查和版本控制。initData 值可以实现这一点:
initData:
enabled: true
data:
organizations:
- owner: admin
name: acme
displayName: Acme
passwordType: bcrypt
applications:
- owner: admin
name: app-acme-portal
organization: acme
displayName: Acme Portal
redirectUris:
- https://portal.acme.example.com/callback
users:
- owner: acme
name: alice
displayName: Alice
password: change-me
signupApplication: app-acme-portal
roles:
- owner: acme
name: admins
displayName: Admins
users: [acme/alice]
isEnabled: true
该 chart 将数据存储在 Secret 中并挂载到 Pod 中。Casdoor 在启动时应用这些数据,之后每 30 秒检查一次(initData.watchInterval)。当您更改数据并运行 helm upgrade 时,kubelet 会更新挂载的 Secret,正在运行的 Pod 会在无需重启的情况下应用更改。
以下几条规则使得这种用法可以与 Web UI 安全地共存:
- 只管理你编写的字段。 已存在的对象会被设置为文件中指定的字段;其其他字段保留在 UI 中编辑的值。你可以只管理应用的 redirect URIs,而将其余部分留给管理控制台。
- 密码是初始密码。 用户的
password仅在创建用户时使用,因此用户可以在之后修改自己的密码。 - 不会删除任何内容。 从文件中移除某个对象并不会将其从 Casdoor 中移除。
- 错误不会导致 Casdoor 宕机。 如果某个对象应用失败,错误会被记录日志,Casdoor 会继续提供服务;每次检查时都会重试该数据,直到应用成功为止。
文件格式一直是 Casdoor 用于数据初始化的格式:包括组织、应用、用户、提供商、证书、角色、权限、组、LDAP 服务器、Webhooks、计划、定价等更多对象,且字段名称与 REST API 相同。一种快速的入门方法是使用 casdoor -export 导出现有实例,并保留你想要管理的对象。
为了避免将数据放在 values 文件中(例如由 Sealed Secrets 或 External Secrets 管理时),你可以自己创建 Secret:
initData:
enabled: true
existingSecret: casdoor-init-data
existingSecretKey: init_data.yaml
此功能在不使用 Kubernetes 的情况下同样有效。挂载 JSON 或 YAML 文件并设置:
initDataFile = /init-data/init_data.yaml
initDataMerge = true
initDataWatchInterval = 30
或者使用 Terraform
如果你更喜欢 terraform plan、导入现有对象以及漂移检测,官方 Terraform provider 通过 Casdoor API 管理相同的对象:
resource "casdoor_application" "portal" {
name = "app-acme-portal"
organization = "acme"
redirect_uris = ["https://portal.acme.example.com/callback"]
}
当配置应随部署一起交付时使用 Helm values,而当 Casdoor 是你已经用 Terraform 管理的众多系统之一时使用 Terraform。请参阅 Terraform 指南。
从旧版 chart 迁移
截至 v4.15.0,chart 曾以 oci://registry-1.docker.io/casbin/casdoor-helm-charts 的形式发布,独立的 casdoor/casdoor-helm 仓库现已归档。Docker Hub 上的 chart 仍然接收所有新版本,但新安装建议使用 GHCR 上的 chart。将现有 release 迁移过来是一次常规升级,资源名称保持不变:
helm upgrade casdoor oci://ghcr.io/casdoor/helm-charts/casdoor --version <version>
链接
- Helm chart: Artifact Hub · 源代码
- 指南: Try with Helm · 数据初始化与配置即代码 · Terraform
- 不想自己运维?Casdoor Cloud 为您提供一个由我们托管并保持更新的专用 Casdoor 实例。