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.

Add the Helm Repositories for CockroachDB and ZITADEL​

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

After you have your repositories added, you can setup ZITADEL and either

Setup ZITADEL and a Human Admin​

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

# Install 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

# Make ZITADEL locally accessible
kubectl port-forward svc/my-zitadel 8080

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

note

This guide is based on a local setup. If you encounter an error "Instance Not Found" please read the following section: Instance not found

Setup ZITADEL and a Service Account Admin​

With this setup, you don't create a human user that has the IAM_OWNER role. Instead, you create a service account that has the IAM_OWNER role. ZITADEL will also create a key for your, with which you can authenticate to the ZITADEL API. For example, you can install ZITADEL and seemlessly provision ZITADEL resources after installation using Terraform.

caution

With this setup you only get a key for a service account. Logging in at ZITADEL using the login screen is not possible until you create a user with the ZITADEL API. 

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

# Install 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

# Make ZITADEL locally accessible
kubectl port-forward svc/my-zitadel 8080

When Helm is done, you can print your service account key from a Kubernetes secret:

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

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