Run Casdoor on Kubernetes with Helm

This guide explains how to install Casdoor on a Kubernetes cluster with the official Helm chart, expose it outside the cluster, and upgrade or remove the release.

---

Learning outcomes

• Install the Casdoor Helm chart.
• Override chart values, including the database connection.
• Expose Casdoor with Ingress or the Gateway API.
• Keep organizations, applications, and users in the values file.
• Upgrade and uninstall the release.

What you need

• A Kubernetes cluster, version 1.19 or later
• Helm 3.8 or later
• For the Gateway API option: the Gateway API CRDs and a Gateway controller in the cluster

---

提示

Don't want to run it yourself? Casdoor Cloud gives you a dedicated Casdoor instance that we host and keep upgraded for you, from $25/month with no per-user fees.

Install the chart

The chart is published as an OCI artifact on GitHub Container Registry. It is listed on Artifact Hub, and its source is in the Casdoor repository.

1. Install the chart. Replace <version> with a chart version from Artifact Hub.

   helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor --version <version>

   To override values, pass your own values file:

   helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor      --version <version>      -f my-values.yaml

2. Open Casdoor at the URL of the casdoor service in your cluster. With the default values, the service is of type ClusterIP on port 8000, so it is reachable only inside the cluster until you expose it.

Customize the deployment

Override the values of values.yaml in your own values file. The main values are:

参数	描述	默认值
replicaCount	运行 Casdoor 应用的副本数量。	1
image.repository	Casdoor Docker 图像的仓库。	casbin
image.name	Casdoor Docker 图像的名称。	casdoor
image.pullPolicy	Casdoor Docker 图像的拉取策略。	IfNotPresent
image.tag	Casdoor Docker 图像的标签。	""
config	Casdoor 应用的配置设置。	See values.yaml
database.driver	要使用的数据库驱动程序（mysql、postgres、cockroachdb、sqlite）。	sqlite
database.user	数据库用户名。	""
database.password	数据库密码。	""
database.host	数据库主机。	""
database.port	数据库端口。	""
database.databaseName	Casdoor 使用的数据库名称。	casdoor
database.sslMode	数据库连接的 SSL 模式。	disable
service.type	Kubernetes服务类型（ClusterIP、NodePort、LoadBalancer）。	ClusterIP
service.port	Casdoor 服务的端口号。	8000
ingress.enabled	是否启用 Casdoor 的 Ingress。	false
ingress.annotations	Ingress 资源的注解。	{}
ingress.hosts	Ingress 资源的主机名。	[]
resources	Casdoor 容器的资源请求和限制。	{}
autoscaling.enabled	是否启用 Casdoor 的水平 Pod 自动扩展。	false
autoscaling.minReplicas	HPA 的最小副本数。	1
autoscaling.maxReplicas	HPA 的最大副本数。	100
autoscaling.targetCPUUtilizationPercentage	HPA 的目标 CPU 利用率百分比。	80
nodeSelector	Pod 分配的节点标签。	{}
tolerations	Pod 分配的容忍标签。	[]
affinity	Pod 分配的亲和性设置。	{}
extraContainersEnabled	是否启用额外的边车容器。	false
extraContainers	额外的边车容器。	""
extraVolumeMounts	Casdoor 容器的额外卷挂载。	[]
extraVolumes	Casdoor 容器的额外卷。	[]
envFromSecret	来自单个Secret密钥的环境变量。	[]
envFromConfigmap	来自单个ConfigMap密钥的环境变量。	[]
envFrom	来自整个 Secret 或 ConfigMap 的环境变量。	[]

Expose Casdoor

Choose Ingress or the Gateway API.

Expose Casdoor with Ingress

Enable Ingress in your values file:

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: casdoor.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: casdoor-tls
      hosts:
        - casdoor.example.com

Expose Casdoor with the Gateway API

The Kubernetes Gateway API is the successor to Ingress. Istio, Envoy Gateway, Cilium, Kong, NGINX Gateway Fabric, and other controllers support it.

Before you enable this option, install the Gateway API CRDs and make sure that a compatible Gateway controller runs in the cluster:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

Then use one of the following configurations.

附加到现有网关

If the cluster already has a Gateway, point the HTTPRoute at it:

gatewayApi:
  enabled: true
  parentRefs:
    - name: my-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - casdoor.example.com

Create a Gateway

Let the chart create a Gateway together with the HTTPRoute. This example uses Istio:

gatewayApi:
  enabled: true
  createGateway: true
  hostnames:
    - casdoor.example.com
  gateway:
    gatewayClassName: istio
    listeners:
      - name: http
        protocol: HTTP
        port: 80
        allowedRoutes:
          namespaces:
            from: Same

Create a Gateway that redirects HTTP to HTTPS

Terminate TLS at the Gateway and redirect HTTP requests to HTTPS:

gatewayApi:
  enabled: true
  createGateway: true
  hostnames:
    - casdoor.example.com
  gateway:
    gatewayClassName: istio
    listeners:
      - name: http
        protocol: HTTP
        port: 80
        allowedRoutes:
          namespaces:
            from: Same
      - name: https
        protocol: HTTPS
        port: 443
        tls:
          certificateRefs:
            - name: casdoor-tls
              kind: Secret
        allowedRoutes:
          namespaces:
            from: Same
  httpsRedirect:
    enabled: true

Gateway API values

参数	描述	Default
gatewayApi.enabled	启用HTTPRoute创建	false
gatewayApi.createGateway	同时创建一个 Gateway 资源	false
gatewayApi.annotations	HTTPRoute 的注解	{}
gatewayApi.labels	HTTPRoute 的额外标签	{}
gatewayApi.parentRefs	父网关引用	[]
gatewayApi.hostnames	要匹配的主机名（Host标头）	[]
gatewayApi.rules	路由规则（匹配、过滤器、后端引用）	路径前缀 /
gatewayApi.gateway.name	网关名称（默认为图表全名）	""
gatewayApi.gateway.gatewayClassName	网关类名称（当createGateway=true时必填）	""
gatewayApi.gateway.listeners	网关监听器	HTTP:80
gatewayApi.httpsRedirect.enabled	启用HTTP→HTTPS重定向HTTPRoute	false
gatewayApi.httpsRedirect.statusCode	重定向响应码	301
gatewayApi.httpsRedirect.hostnames	重定向路由的主机名	[]
gatewayApi.httpsRedirect.parentRefs	覆盖重定向路由的 parentRefs	[]

Manage Casdoor objects in the values file

You can keep organizations, applications, users, providers, roles, and permissions in the values file, next to the rest of the deployment. Casdoor applies them at startup and checks them for changes every 30 seconds. A helm upgrade that changes them takes effect without restarting the pods.

initData:
  enabled: true
  data:
    organizations:
      - owner: admin
        name: acme
        displayName: Acme
        passwordType: bcrypt
    applications:
      - owner: admin
        name: app-acme
        organization: acme
        displayName: Acme Portal
        redirectUris:
          - https://portal.acme.example.com/callback

An existing object receives only the fields that you write here. Its other fields keep the values that were set in the admin console.

The chart stores the data in a Secret. To keep the data out of the values file, create the Secret yourself and set initData.existingSecret.

Parameter	Description	Default
initData.enabled	Apply initData.data (or initData.existingSecret)	false
initData.merge	Update existing objects with the given fields only; when false, they are deleted and re-created on every apply	true
initData.watchInterval	Seconds between the checks for changes, 0 applies the data only at startup	30
initData.existingSecret	Existing Secret holding the data, instead of initData.data	""
initData.existingSecretKey	Key of the file in existingSecret, .yaml/.yml keys are read as YAML	init_data.yaml
initData.data	The objects to apply, in the init data format	{}

Upgrade the release

helm upgrade casdoor oci://ghcr.io/casdoor/helm-charts/casdoor --version <version>

备注

Charts up to version 4.15.0 were published as oci://registry-1.docker.io/casbin/casdoor-helm-charts. That location still receives every release. To move an existing release to the new location, run the helm upgrade command above. Resource names stay the same.

Uninstall the release

helm uninstall casdoor

See also

• Data initialization
• Deploy on Kubernetes
• Configuration reference
• Helm documentation