Skip to main content

Kubernetes

Installation and configuration details are described in the open source ZITADEL charts repo. By default, the chart installs a secure and highly available ZITADEL instance. For running an easily testable, insecure, non-HA ZITADEL instance, run the following commands.

Helm​

Add the helm repositories for CockroachDB and ZITADEL​

helm repo add cockroachdb https://charts.cockroachdb.com/
helm repo add zitadel https://charts.zitadel.com

Install zitadel​

Install an insecure cockroachdb and zitadel release that works with localhost​

# CockroachDB
helm install crdb cockroachdb/cockroachdb \
  --set fullnameOverride=crdb \
  --set single-node=true \
  --set statefulset.replicas=1

# ZITADEL
helm install my-zitadel zitadel/zitadel \
  --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
  --set zitadel.configmapConfig.ExternalSecure=false \
  --set zitadel.configmapConfig.TLS.Enabled=false \
  --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
  --set replicaCount=1

Open your favorite internet browser and navigate to http://localhost:8080/ui/console. This is the default IAM admin users login:

  • username: zitadel-admin@zitadel.localhost
  • password: Password1!
info

In the above username, replace localhost with your configured external domain, if any. e.g. with zitadel-admin@zitadel.sso.my.domain.tld

Install an insecure zitadel release that works with localhost with a service account​

!!!Caution!!! With this setup you only get a service account with a key and no admin account where you can login directly into ZITADEL.

# CockroachDB
helm install crdb cockroachdb/cockroachdb \
  --set fullnameOverride=crdb \
  --set single-node=true \
  --set statefulset.replicas=1

# ZITADEL
helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
  --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
  --set zitadel.configmapConfig.ExternalSecure=false \
  --set zitadel.configmapConfig.TLS.Enabled=false \
  --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
  --set replicaCount=1 \
  --set zitadel.configmapConfig.FirstInstance.MachineKeyPath="/machinekey/zitadel-admin-sa.json" \
  --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Username="zitadel-admin-sa" \
  --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Name="Admin" \
  --set zitadel.configmapConfig.FirstInstance.Org.Machine.MachineKey.Type=1

When helm is done, you get a command to retrieve your machine key, which is saved as a kubernetes secret, for example:

kubectl -n zitadel get secret zitadel-admin-sa -o jsonpath='{ .data.zitadel-admin-sa\.json }' | base64 -D

This key can be used to provision resources with for example Terraform.

Forward the ZITADEL service port to your local machine​

kubectl port-forward svc/my-zitadel 8080:8080

What's next​

For running a production grade ZITADEL instance in your environment, go on with the configure ZITADEL section.

caution

The ZITADEL management console requires end-to-end HTTP/2 support

Disclaimer​

This guide is for development / demonstration purpose only and does NOT reflect a production setup.

Things such as TLS termination and email verification will not be available unless you

  • Use an API gateway with valid certificates in front of the service
  • Configure an appropriate email server