Install Zitadel

The customer must install Zitadel, an Identity and Access Management (IdAM) service to use the Istari Digital Platform. The Istari Digital Platform will use Zitadel to log users into the Istari Digital frontend as well as manage permissions for which resources the user can access in the Istari Digital Platform.

info

When configuring Zitadel, you will need to save a number of values that will later be referenced when installing the Istari Platform. Details on these are covered below.

Zitadel Setup, Installation, and Configuration

If a customer does not have an ICAM system currently, Istari Digital has a suggested configuration of an Identity and Access Management (IdAM) service using the Zitadel Open Source project. This configuration will install Zitadel and an additional PostgreSQL database into the customer’s Kubernetes cluster. It is recommended that a separate PostgreSQL database is used for Zitadel, to minimize risk of losing all data and users in the event of a disaster. The database implementation, however, is left up to the customer.

Adding the Zitadel Repository

In a terminal run:

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

Prerequisites

Before installing Zitadel, ensure the PostgreSQL database used by Zitadel is owned by the PostgreSQL user configured for Zitadel (zitadel). This allows Zitadel to perform schema migrations and grant permissions during initialization. Refer to your platform's database setup for AWS or Azure

zitadel-values.yaml

A zitadel-values.yaml will have to be created to configure the Zitadel installation. The example zitadel-values.yaml requires some values to be filled in by the Customer. These values are in the table below with some example values. The Customer should make sure they set these values in the beginning of the zitadel-values.yaml or replace the Helm variables with the correct values.

Key	Description
Master Key	32-character master encryption key for Zitadel
Customer Domain	The base domain for Zitadel
Database Host	PostgreSQL host (AWS RDS or Azure PostgreSQL)
Postgres Password	Password for the PostgreSQL user 'zitadel'

warning

The PostgreSQL password ends up becoming part of a URI connection string and thus the characters used must be limited to the following due to URI escaping rules: A–Z a–z 0–9 - _ . ~

Passwords must be at least 8 characters and include uppercase, lowercase, numeric, and special characters

An example zitadel-values.yaml is shown below:

zitadel-values.yaml

# ZITADEL main configuration
image:
  repository: "ghcr.io/zitadel/zitadel"
  tag: "v2.71.17"
  # # If using images from a private repo, also uncomment the
  # # following lines & replace '<image_pull_secret>' with the name of the Kubernetes secret used to pull images
  # imagePullSecrets:
  # - name: <image_pull_secret>
initJob:
  enabled: true
  command: zitadel
  podAnnotations:
    sidecar.istio.io/inject: "false"
setupJob:
  enabled: true
  machinekeyWriter:
    image:
      repository: "alpine/k8s"
      tag: "1.33.4"
  podAnnotations:
    sidecar.istio.io/inject: "false"
zitadel:
  masterkey: [Master Key] # Set the Master key to your desired key, it should be 32 characters

  configmapConfig:
    ExternalSecure: true
    ExternalPort: 443
    Port: 8080
    ExternalDomain: "zitadel.[Customer Domain]" # Replace with actual domain

    FirstInstance:
      InstanceName: "Main"
      DefaultLanguage: "en"
      Org:
        Name: "zitadel"
        Human:
          UserName: "admin"
          Email:
            Address: "admin@zitadel.[Customer Domain]" # Replace with actual email address
            Verified: true
          PreferredLanguage: "en"
          Password: [Admin User Password] # Replace with secure admin password
          PasswordChangeRequired: false
        Machine:
          Machine:
            Username: "sa"
            Name: "SA Admin"
          MachineKey:
            Type: 1

    TLS:
      Enabled: false

    Database:
      Postgres:
        Host: [Database Host] # Replace with actual PostgreSQL host
        Port: 5432 # Replace with PostgreSQL port if not using RDS
        Database: zitadel
        MaxOpenConns: 20
        MaxIdleConns: 10
        MaxConnLifetime: "30m"
        MaxConnIdleTime: "5m"
        User:
          Username: zitadel # Replace with database user if different
          SSL:
            Mode: "prefer"

  secretConfig:
    Database:
      Postgres:
        User:
          Password: [Postgres Password] # PostgreSQL password for user 'zitadel'

Install Zitadel

In a terminal opened to the directory where the Zitadel zitadel-values.yaml exists, run this command to install Zitadel:

helm upgrade --install zitadel zitadel/zitadel --version 8.7.2 -f zitadel-values.yaml

Zitadel DNS

Create a DNS record for Zitadel and an endpoint that can be used to terminate TLS for it.