https://github.com/zitadel/zitadel-charts
This repository contains Helm charts for running ZITADEL in Kubernetes
https://github.com/zitadel/zitadel-charts
access cloud iam identity kubernetes zitadel
Last synced: 2 months ago
JSON representation
This repository contains Helm charts for running ZITADEL in Kubernetes
- Host: GitHub
- URL: https://github.com/zitadel/zitadel-charts
- Owner: zitadel
- License: apache-2.0
- Created: 2022-05-27T14:26:53.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-28T14:16:48.000Z (3 months ago)
- Last Synced: 2025-03-28T15:04:10.509Z (3 months ago)
- Topics: access, cloud, iam, identity, kubernetes, zitadel
- Language: Go
- Homepage: https://zitadel.com
- Size: 1.2 MB
- Stars: 90
- Watchers: 6
- Forks: 66
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://artifacthub.io/packages/search?repo=zitadel)
# Zitadel
## A Better Identity and Access Management Solution
Identity infrastructure, simplified for you.
Learn more about Zitadel by checking out the [source repository on GitHub](https://github.com/zitadel/zitadel)
## What's in the Chart
By default, this chart installs a highly available Zitadel deployment.
The chart deploys a Zitadel init job, a Zitadel setup job and a Zitadel deployment.
By default, the execution order is orchestrated using Helm hooks on installations and upgrades.
## Install the Chart
Either follow the [guide for deploying Zitadel on Kubernetes](https://zitadel.com/docs/self-hosting/deploy/kubernetes) or follow one of the example guides:
- [Insecure Postgres Example](examples/1-postgres-insecure/README.md)
- [Secure Postgres Example](examples/2-postgres-secure/README.md)
- [Referenced Secrets Example](examples/3-referenced-secrets/README.md)
- [Machine User Setup Example](examples/4-machine-user/README.md)
- [TLS with Self Signed Certificate Setup Example](examples/5-self-signed/README.md)
## Upgrade from v7
> [!WARNING] The chart version 8 doesn't get updates to the default Zitadel version anymore as this might break environments that use CockroachDB.
> Please set the version explicitly using the appVersion variable if you need a newer Zitadel version.
> The upcoming version 9 will include the latest Zitadel version by default (Zitadel v3).
The default Zitadel version is now >= v2.55.
[This requires Cockroach DB to be at >= v23.2](https://zitadel.com/docs/support/advisory/a10009)
If you are using an older version of Cockroach DB, please upgrade it before upgrading Zitadel.
Note that in order to upgrade cockroach, you should not jump minor versions.
For example:
```bash
# install Cockroach DB v23.1.14
helm upgrade db cockroachdb/cockroachdb --version 11.2.4 --reuse-values
# install Cockroach DB v23.2.5
helm upgrade db cockroachdb/cockroachdb --version 12.0.5 --reuse-values
# install Cockroach DB v24.1.1
helm upgrade db cockroachdb/cockroachdb --version 13.0.1 --reuse-values
# install Zitadel v2.55.0
helm upgrade my-zitadel zitadel/zitadel --version 8.0.0 --reuse-values
```
Please refer to the docs by Cockroach Labs. The Zitadel tests run against the [official CockroachDB chart](https://artifacthub.io/packages/helm/cockroachdb/cockroachdb).
(Credits to @panapol-p and @kleberbaum :pray:)
## Upgrade from v6
- Now, you have the flexibility to define resource requests and limits separately for the machineKeyWriter,
distinct from the setupJob.
If you don't specify resource requests and limits for the machineKeyWriter,
it will automatically inherit the values used by the setupJob.
- To maintain consistency in the structure of the values.yaml file, certain properties have been renamed.
If you are using any of the following properties, kindly review the updated names and adjust the values accordingly:
| Old Value | New Value |
|---------------------------------------------|----------------------------------------------|
| `setupJob.machinekeyWriterImage.repository` | `setupJob.machinekeyWriter.image.repository` |
| `setupJob.machinekeyWriterImage.tag` | `setupJob.machinekeyWriter.image.tag` |
## Upgrade from v5
- CockroachDB is not in the default configuration anymore.
If you use CockroachDB, please check the host and ssl mode in your Zitadel Database configuration section.
- The properties for database certificates are renamed and the defaults are removed.
If you use one of the following properties, please check the new names and set the values accordingly:
| Old Value | New Value |
|--------------------------------|-------------------------------|
| `zitadel.dbSslRootCrt` | `zitadel.dbSslCaCrt` |
| `zitadel.dbSslRootCrtSecret` | `zitadel.dbSslCaCrtSecret` |
| `zitadel.dbSslClientCrtSecret` | `zitadel.dbSslAdminCrtSecret` |
| `-` | `zitadel.dbSslUserCrtSecret` |
## Uninstalling the Chart
The Zitadel chart uses Helm hooks,
[which are not garbage collected by helm uninstall, yet](https://helm.sh/docs/topics/charts_hooks/#hook-resources-are-not-managed-with-corresponding-releases).
Therefore, to also remove hooks installed by the Zitadel Helm chart,
delete them manually:
```bash
helm uninstall my-zitadel
for k8sresourcetype in job configmap secret rolebinding role serviceaccount; do
kubectl delete $k8sresourcetype --selector app.kubernetes.io/name=zitadel,app.kubernetes.io/managed-by=Helm
done
```
## Troubleshooting
### Debug Pod
For troubleshooting, you can deploy a debug pod by setting the `zitadel.debug.enabled` property to `true`.
You can then use this pod to inspect the Zitadel configuration and run zitadel commands using the zitadel binary.
For more information, print the debug pods logs using something like the following command:
```bash
kubectl logs rs/my-zitadel-debug
```
### migration already started, will check again in 5 seconds
If you see this error message in the logs of the setup job, you need to reset the last migration step once you resolved the issue.
To do so, start a [debug pod](#debug-pod) and run something like the following command:
```bash
kubectl exec -it my-zitadel-debug -- zitadel setup cleanup --config /config/zitadel-config-yaml
```
## Contributing
Lint the chart:
```bash
docker run -it --network host --workdir=/data --rm --volume $(pwd):/data quay.io/helmpack/chart-testing:v3.5.0 ct lint --charts charts/zitadel --target-branch main
```
Test the chart:
```bash
# Create a local Kubernetes cluster
kind create cluster --image kindest/node:v1.27.2
# Test the chart
go test ./...
```
Watch the Kubernetes pods if you want to see progress.
```bash
kubectl get pods --all-namespaces --watch
# Or if you have the watch binary installed
watch -n .1 "kubectl get pods --all-namespaces"
```
## Contributors
