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

---

conseil

Don't want to run it yourself? Casdoor Cloud gives you a dedicated Casdoor instance that we host and keep upgraded for you, from $29/month with no per-user fees. New accounts get $20 in free credit to try it.

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:

Paramètre	Description	Par défaut
replicaCount	Nombre de réplicas de l'application Casdoor à exécuter.	1
image.repository	Répertoire pour l'image Docker de Casdoor.	casbin
image.name	Nom de l'image Docker de Casdoor.	casdoor
image.pullPolicy	Politique de téléchargement pour l'image Docker de Casdoor.	IfNotPresent
image.tag	Étiquette pour l'image Docker de Casdoor.	""
config	Paramètres de configuration pour l'application Casdoor.	See values.yaml
database.driver	Database driver to use (mysql, postgres, cockroachdb, sqlite).	sqlite
database.user	Nom d'utilisateur de la base de données.	""
database.password	Mot de passe de la base de données.	""
database.host	Hôte de la base de données.	""
database.port	Port de la base de données.	""
database.databaseName	Nom de la base de données utilisée par Casdoor.	casdoor
database.sslMode	Mode SSL pour la connexion à la base de données.	disable
service.type	Type of Kubernetes service (ClusterIP, NodePort, LoadBalancer).	ClusterIP
service.port	Numéro de port pour le service Casdoor.	8000
ingress.enabled	Que ce soit pour activer Ingress pour Casdoor.	false
ingress.annotations	Annotations pour la ressource Ingress.	{}
ingress.hosts	Noms d'hôte pour la ressource Ingress.	[]
resources	Demandes de ressources et limites pour le conteneur Casdoor.	{}
autoscaling.enabled	Que ce soit pour activer l'Horizontal Pod Autoscaler pour Casdoor.	false
autoscaling.minReplicas	Minimum number of replicas for HPA.	1
autoscaling.maxReplicas	Maximum number of replicas for HPA.	100
autoscaling.targetCPUUtilizationPercentage	Target CPU utilization percentage for HPA.	80
nodeSelector	Étiquettes de nœuds pour l'assignation de pods.	{}
tolerations	Étiquettes de tolérance pour l'assignation de pods.	[]
affinity	Paramètres d'affinité pour l'assignation de pods.	{}
extraContainersEnabled	Que ce soit pour activer des conteneurs sidecar supplémentaires.	false
extraContainers	Conteneurs sidecar supplémentaires.	""
extraVolumeMounts	Montages de volumes supplémentaires pour le conteneur Casdoor.	[]
extraVolumes	Volumes supplémentaires pour le conteneur Casdoor.	[]
envFromSecret	Environment variables from individual Secret keys.	[]
envFromConfigmap	Environment variables from individual ConfigMap keys.	[]
envFrom	Environment variables from entire Secrets or ConfigMaps.	[]

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.

Attach to an existing Gateway

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

Paramètre	Libellé descriptif	Default
gatewayApi.enabled	Enable HTTPRoute creation	false
gatewayApi.createGateway	Also create a Gateway resource	false
gatewayApi.annotations	Annotations for the HTTPRoute	{}
gatewayApi.labels	Extra labels for the HTTPRoute	{}
gatewayApi.parentRefs	Parent Gateway references	[]
gatewayApi.hostnames	Hostnames to match (Host header)	[]
gatewayApi.rules	Routing rules (matches, filters, backendRefs)	PathPrefix /
gatewayApi.gateway.name	Gateway name (defaults to chart fullname)	""
gatewayApi.gateway.gatewayClassName	GatewayClass name (required when createGateway=true)	""
gatewayApi.gateway.listeners	Gateway listeners	HTTP:80
gatewayApi.httpsRedirect.enabled	Enable HTTP→HTTPS redirect HTTPRoute	false
gatewayApi.httpsRedirect.statusCode	Redirect response code	301
gatewayApi.httpsRedirect.hostnames	Hostnames for redirect route	[]
gatewayApi.httpsRedirect.parentRefs	Override parentRefs for redirect route	[]

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>

note

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