Zitadel-Configurator

The Zitadel Configurator is an optional feature that automates the setup and configuration of Zitadel resources for the Istari Platform.

Zitadel requires HTTP/2 support for gRPC communication. Ensure your load balancer and ingress are configured to handle HTTP/2 traffic. OAuth endpoints (/oauth/*) must use HTTP/1.1 while all other Zitadel endpoints require HTTP/2 for gRPC. When configuring ingress rules, ensure OAuth routes have higher priority than gRPC routes.

For example, when using AWS ALB Ingress, create two ingress resources that share the same ALB:

OAuth Ingress (HTTP/1.1 - higher priority)

metadata:
  name: zitadel
  annotations:
    alb.ingress.kubernetes.io/group.name: zitadel
    alb.ingress.kubernetes.io/group.order: "100"
    alb.ingress.kubernetes.io/backend-protocol-version: HTTP1
spec:
  rules:
    - host: zitadel.customer_domain.com
      http:
        paths:
          - path: /oauth
            pathType: Prefix

gRPC Ingress (HTTP/2 - lower priority)

metadata:
  name: zitadel-grpc
  annotations:
    alb.ingress.kubernetes.io/group.name: zitadel
    alb.ingress.kubernetes.io/group.order: "200"
    alb.ingress.kubernetes.io/backend-protocol-version: HTTP2
    alb.ingress.kubernetes.io/load-balancer-attributes: routing.http2.enabled=true
spec:
  rules:
    - host: zitadel.customer_domain.com
      http:
        paths:
          - path: /
            pathType: Prefix

tip

Same group.name consolidates both ingresses into a single ALB
Lower group.order = higher priority (OAuth at 100 evaluates before gRPC at 200)

Prerequisites

This step requires that you have completed the Zitadel Installation step.

It is not a requirement for the Istari Digital Platform, but it is a useful alternative for organizations that need to quickly set up Zitadel.

info

Istari Digital needs to grant access to the Istari Digital Artifactory to allow customers to pull our helm charts.
The customer should have a username and a password before this step. Use these to set the values for the env vars ISTARI_ARTIFACTORY_USERNAME and ISTARI_ARTIFACTORY_PASSWORD below.
Above access is required to be able to pull the Zitadel Configurator helm chart and is needed for creating the docker pull secret for EKS in the next steps.

ISTARI_ARTIFACTORY_USERNAME=
ISTARI_ARTIFACTORY_PASSWORD=
kubectl create secret docker-registry docker-pull-secret \
  --docker-server="istaridigital.jfrog.io" \
  --docker-email="${ISTARI_ARTIFACTORY_USERNAME}" \
  --docker-username="${ISTARI_ARTIFACTORY_USERNAME}" \
  --docker-password="${ISTARI_ARTIFACTORY_PASSWORD}"

Helm repo setup

helm repo add istari https://istaridigital.jfrog.io/artifactory/main-helm-local --username ${ISTARI_ARTIFACTORY_USERNAME} --password ${ISTARI_ARTIFACTORY_PASSWORD}
helm repo update

Define Zitadel Configurator Values

An example custom-values.yaml is shown below:

zitadel-custom-values.yaml
image:
  # -- Docker registry where the image is hosted
  registry: istaridigital.jfrog.io
  # -- Docker repository for the image
  repository: main-docker-local/zitadel-configurator
  # -- Image pull policy (e.g., Always, IfNotPresent, Never)
  pullPolicy: IfNotPresent
  # -- Image tag to use
  tag: "1.0.0"

# -- Override the name of the chart.
nameOverride: istari-zitadel-configurator

# -- Override the name of the chart.
fullnameOverride: istari-zitadel-configurator
imagePullSecrets:
  - name: "docker-pull-secret"

# This section builds out the service account more information can be found here: https://kubernetes.io/docs/concepts/security/service-accounts/
serviceAccount:
  # Specifies whether a service account should be created
  create: true
  # Automatically mount a ServiceAccount's API credentials?
  automount: true
  # Annotations to add to the service account
  annotations: {}
  # The name of the service account to use.
  # If not set and create is true, a name is generated using the fullname template
  name: ""

# This is for setting Kubernetes Annotations to a Pod.
# For more information, check out: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/
podAnnotations: {}
# This is for setting Kubernetes Labels to a Pod.
# For more information checkout: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
podLabels: {}

# -- Security context for the Pod. For more information, see:
# https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
podSecurityContext:
  # -- Group ID for all files created by containers in the Pod
  fsGroup: 2000

# -- Security context for the container. For more information, see:
# https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
securityContext:
  # -- Drop all Linux capabilities for the container
  capabilities:
    drop:
      - ALL
  # -- Mount the root filesystem as read-only
  readOnlyRootFilesystem: true
  # -- Run the container as a non-root user
  runAsNonRoot: true
  # -- User ID to run the entrypoint of the container process
  runAsUser: 1000
  # -- Prevent privilege escalation
  allowPrivilegeEscalation: false

# -- Resource requests and limits for the container. For more information, see:
# https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
resources:
  limits:
    cpu: "1"
    memory: 512Mi
  requests:
    cpu: "1"
    memory: 512Mi

# -- Node selector for pod assignment. For more information, see:
# https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/
nodeSelector: {}

# -- Tolerations for pod assignment. For more information, see:
# https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []

# -- Affinity rules for pod assignment. For more information, see:
# https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/
affinity: {}

override:
  # -- Enable overriding terraform plan with custom pre-existing plan. If enabled is set to true, "configurator" part of the values.yaml will be ignored.
  enabled: false
  # -- Name of kubernetes secret containing terraform plan
  plan_secret_name: istari-zitadel-configurator-overrides-terraform
  # -- Name of kubernetes secret containing entrypoint script for the container
  entrypoint_secret_name: istari-zitadel-configurator-overrides-entrypoint

# We assume customer domain is "customer_domain.com", specifically "main_domain" value.
# Please change it to your domain.
configurator:
  # -- Set to true to enable debug mode for the Terraform plan; pod logs will display the planning output. Set to false to apply the Terraform changes instead.
  plan_only: false

  # -- This will determine the main domain for the Terraform configuration.
  main_domain: customer_domain.com

  # -- Enable auto configuration of subdomains. If enabled is set to true.
  # If set to true, the following domains will be assumed (Please note using customer_domain.com as an example):
  # Frontend service subdomain: https://customer_domain.com and https://v2.customer_domain.com
  # MCP service subdomain: https://mcp.customer_domain.com
  # Any additional subdomains required by Istari-Platform helm chart will take values as:
  #   http://[subdomain].customer_domain.com
  #
  # If set to false, the following values have to be provided:
  # `frontend_post_logout_redirect_uris`, `frontend_redirect_uris`, `mcp_service.post_logout_redirect_uris`, `mcp_service.redirect_uris`
  auto_configure_subdomains: true

  # -- Zitadel domain
  zitadel_domain: "zitadel.customer_domain.com"
  # -- Zitadel port
  zitadel_port: 443
  # -- Whether to connect to Zitadel over insecure channel
  zitadel_insecure: false
  # -- The secret name that is created by Zitadel helm chart
  zitadel_sa_secret_name: "zitadel-sa-user"
  # -- URLs inside this array should not end with a trailing "/"
  frontend_post_logout_redirect_uris:
    - https://customer_domain.com
  # -- URLs inside this array should not end with a trailing "/"
  frontend_redirect_uris:
    - https://customer_domain.com
  # -- MCP service
  mcp_service:
    # -- Whether to create MCP application in Zitadel
    enabled: false
    # -- URLs inside this array should not end with a trailing "/". Required only if MCP is enabled.
    post_logout_redirect_uris:
      - https://mcp.customer_domain.com
    # -- URLs inside this array should not end with a trailing "/". Required only if MCP is enabled.
    redirect_uris:
      - https://mcp.customer_domain.com
    # -- In case auto_configure_subdomains is enabled, this might be used to configure additional domains for the application in Zitadel.
    additional_redirect_uris: []
  # -- Display name of the organization
  org_name: "istari"
  # -- Organization owner user
  org_owner:
    email: "local_admin@customer_domain.com"
    firstname: "local"
    lastname: "admin"
    temporary_password: "IstariLocalPassword1!"
    username: "local_admin"
  # -- Privacy policy link
  privacy_link: "https://customer_domain.com/privacy-policy"
  # -- Display name of the project
  project_name: "istari"
  # -- Terms of service link
  tos_link: "https://customer_domain.com/terms-of-service"
  smtp:
    # -- Whether to create SMTP application in Zitadel
    enabled: false
    # -- Recommended way to configure SMTP settings. Indicates whether to use an existing secret or create a new one.
    existing_secret: true
    # -- The key in the existing secret that contains the SMTP password.
    existing_secret_key: "smtp_password"
    # -- The name of the existing secret that contains the SMTP settings.
    existing_secret_name: "configurator-secrets"
    # -- SMTP Host
    host: ""
    # -- Not recommended. if smtp_existing_secret is true, this will be ignored
    password: ""
    # -- SMTP Port
    port: 587
    # -- Email address to use for sending out emails
    sender_address: ""
    # -- Name to use for sending out emails
    sender_name: ""
    # -- Whether to use TLS for SMTP communication
    tls: true
    # -- Username to use for SMTP authentication
    username: ""

Configure Customer Domains

This section defines the core behavior of the Zitadel Configurator module. It controls how the Helm chart applies infrastructure changes and how domains are generated.

plan_only: true lets you toggle between preview and apply mode for Terraform operations. When true, the Zitadel Configurator only prints the plan without making changes which is ideal for debugging.

main_domain: customer_domain.com establishes the customer’s root domain. All platform subdomains derive from this base (e.g., mcp.customer_domain.com).

auto_configure_subdomains: true determines whether subdomains and redirect URIs are automatically generated based on the main domain. When disabled, you must explicitly define redirect URIs for each service.

zitadel-custom-values.yaml
# We assume customer domain is "customer_domain.com", specifically "main_domain" value.
# Please change it to your domain.
configurator:
  # -- Set to true to enable debug mode for the Terraform plan; pod logs will display the planning output. Set to false to apply the Terraform changes instead.
  plan_only: false

  # -- This will determine the main domain for the Terraform configuration.
  main_domain: customer_domain.com

  # -- Enable auto configuration of subdomains. If enabled is set to true.
  # If set to true, the following domains will be assumed (Please note using customer_domain.com as an example):
  # Frontend service subdomain: https://customer_domain.com and https://v2.customer_domain.com
  # MCP service subdomain: https://mcp.customer_domain.com
  # Any additional subdomains required by Istari-Platform helm chart will take values as:
  #   http://[subdomain].customer_domain.com
  #
  # If set to false, the following values have to be provided:
  # `frontend_post_logout_redirect_uris`, `frontend_redirect_uris`, `mcp_service.post_logout_redirect_uris`, `mcp_service.redirect_uris`
  auto_configure_subdomains: true

Zitadel Configuration

These values control how the Configurator connects to your Zitadel identity instance.

zitadel_domain, zitadel_port, and zitadel_insecure specify how to reach Zitadel (e.g., secure HTTPS vs HTTP).

zitadel_sa_secret_name points to the Kubernetes Secret created by the Zitadel Helm chart which contain the service account credentials required for management API access. The secret is usually named, "sa"

This ensures the Configurator can authenticate to Zitadel to create organizations, projects, and applications automatically.

zitadel-custom-values.yaml
# -- Zitadel domain
zitadel_domain: "zitadel.customer_domain.com"
# -- Zitadel port
zitadel_port: 443
# -- Whether to connect to Zitadel over insecure channel
zitadel_insecure: false
# -- The secret name that is created by Zitadel helm chart
zitadel_sa_secret_name: "zitadel-sa-user"
# -- URLs inside this array should not end with a trailing "/"

Frontend

This section defines how redirect URIs and post-logout URIs are registered in Zitadel for frontend and MCP (Management Control Plane) applications.

If auto_configure_subdomains: true these values are generated automatically.

Otherwise, frontend_post_logout_redirect_uris, frontend_redirect_uris, and the corresponding mcp_service fields must be manually provided.

zitadel-custom-values.yaml
frontend_post_logout_redirect_uris:
  - https://customer_domain.com
# -- URLs inside this array should not end with a trailing "/"
frontend_redirect_uris:
  - https://customer_domain.com

The mcp_service subsection can also be fully disabled by setting mcp_service: false should the MCP service not be needed.

Optional fields like additional_redirect_uris let you define extra callback URLs if your deployment spans multiple domains or app versions.

zitadel-custom-values.yaml
# -- MCP service
mcp_service:
  # -- Whether to create MCP application in Zitadel
  enabled: false
  # -- URLs inside this array should not end with a trailing "/". Required only if MCP is enabled.
  post_logout_redirect_uris:
    - https://mcp.customer_domain.com
  # -- URLs inside this array should not end with a trailing "/". Required only if MCP is enabled.
  redirect_uris:
    - https://mcp.customer_domain.com
  # -- In case auto_configure_subdomains is enabled, this might be used to configure additional domains for the application in Zitadel.
  additional_redirect_uris: []
# -- Display name of the organization

Zitadel Org and Admin UserLogin

These parameters describe the default Zitadel organization and project created by the Configurator.

org_name and project_name define naming within Zitadel’s internal structure.

The org_owner object seeds the first administrative user for the organization. This includes their email, username, and temporary password.

These values are especially important during the first deployment, as they establish the initial administrative access for Zitadel management.

zitadel-custom-values.yaml
org_name: "istari"
# -- Organization owner user
org_owner:
  email: "local_admin@customer_domain.com"
  firstname: "local"
  lastname: "admin"
  temporary_password: "IstariLocalPassword1!"
  username: "local_admin"
# -- Privacy policy link
privacy_link: "https://customer_domain.com/privacy-policy"
# -- Display name of the project
project_name: "istari"
# -- Terms of service link
tos_link: "https://customer_domain.com/terms-of-service"

Before installing, it is recommended that you have the Zitadel Configurator set to plan by changing the following value found in your zitadel-custom-values.yaml chart:

configurator:
  # -- Set to true to enable debug mode for the Terraform plan; pod logs will display the planning output. Set to false to apply the Terraform changes instead.
  plan_only: true

Install Zitadel Configurator

If everything looks correct and the plan does not encounter any errors, run the following command:

helm upgrade --install istari-zitadel-configurator main-helm-local/istari-zitadel-configurator --version 1.3.6 --values zitadel-custom-values.yaml

Once the installation is complete the zitadel configurator will create a few secrets as part of the setup. Two secrets to note are zitadel-registry-service-env and zitadel-frontend-env as these will be used later as part of the installation

Configure Istari Platform Secrets

Before installing we need to create the istari-frontend and istari-fileservice secret

Frontend Service Secret

The Istari Platform requires a secret for the frontend service. This secret is used to store sensitive information related to file storage and access. The secret should be created in the Kubernetes cluster where the Istari Platform is deployed.

istari-frontend-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-frontend
stringData:
  ISTARI_REGISTRY_URL: "https://registry.<customer_istari_fqdn>"
  VITE_DOCUMENTATION_URL: "https://docs.istaridigital.com"
  VITE_DOMAIN: "<customer_istari_fqdn>"
  VITE_FILE_AUTH_ENDPOINT: "https://registry.<customer_istari_fqdn>"
  VITE_FS_URL: "https://registry.<customer_istari_fqdn>"
  VITE_LOGOUT_REDIRECT_URI: "https://<customer_istari_fqdn>"
  VITE_REDIRECT_URI: "https://<customer_istari_fqdn>"
  VITE_UI_URL: "https://<customer_istari_fqdn>"
  # Set VITE_ITAR to "true" if your platform will be hosting ITAR/CUI data 
  VITE_ITAR: "false"
  # Following values are required as is
  BASE_URL: ""
  VITE_SENTRY_ENABLED: "false"
  VITE_SENTRY_AUTH_TOKEN: ""
  VITE_SENTRY_DSN: ""

info

Make sure to replace <customer_istari_fqdn> with the actual domain used for the Istari Digital platform, e.g. istari.customer_domain.com.

Registry Service Secret

warning

What is currently referred to as "fileservice" will be renamed to "registry-service" as part of a future release. In preparation for this we have chosen to use the subdomain registry below.

The Istari Platform requires a secret for fileservice. This secret is used to store sensitive information related to file storage and access. The secret should be created in the Kubernetes cluster where the Istari Platform is deployed.

info

Istari Digital needs to grant access to license holder and license key to the customer. Please reach out to your Istari Digital Customer Success representative if you do not already have these.

istari-fileservice-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-fileservice
stringData:
  FILE_SERVICE_AUTHZED_HOST: "spicedb" # Change to host if setting FILE_SERVICE_AUTHZED_NO_TLS to "false"
  FILE_SERVICE_AUTHZED_NO_TLS: "true" # Set this to "false" if you want to require TLS with SpiceDB
  FILE_SERVICE_AUTHZED_PORT: "50051" # Change to 443 if setting FILE_SERVICE_AUTHZED_NO_TLS to "false"
  FILE_SERVICE_AUTHZED_TOKEN: "<spicedb_preshared_key>"
  FILE_SERVICE_CORS_ALLOW_ORIGINS: '["https://<customer_istari_fqdn>", "https://v2.<customer_istari_fqdn>"]'
  FILE_SERVICE_DATABASE_URL: "postgresql://registry:<password>@<rds_host>:5432/registry"
  FILE_SERVICE_LICENSE_HOLDER: "<license_holder>"
  FILE_SERVICE_LICENSE_KEY: "<license_key>"
  FILE_SERVICE_OBJECT_STORE_SCHEME_NAME: "s3"  # Set to `wasbs` if using Windows Azure Blob Storage instead of AWS S3
  FILE_SERVICE_OBJECT_STORE_ACCESS_KEY: "<AWS_S3_access_key OR Azure_storage_account_name>"
  FILE_SERVICE_OBJECT_STORE_SECRET_KEY: "<AWS_S3_secret_key OR Azure_storage_container_access_key>"
  FILE_SERVICE_OBJECT_STORE_NAME: "<AWS_S3_bucket OR Azure_storage_container>"
  FILE_SERVICE_OBJECT_STORE_ENDPOINT_URL: "https://<AWS_S3_endpoint_url OR Azure_endpoint_url>" # See https://docs.aws.amazon.com/general/latest/gr/s3.html and https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview#standard-endpoints
  FILE_SERVICE_OBJECT_STORE_REGION: "<AWS_S3_region>" # Not used with Azure Blob Storage
  # Following values are required as is
  FILE_SERVICE_HOST: "0.0.0.0"
  FILE_SERVICE_PORT: "8000"
  FILE_SERVICE_SENTRY_ENABLED: "false"
  FILE_SERVICE_USE_SINGLETON_AUTHZED_PERMISSION_MANAGER: "false"

warning

FILE_SERVICE_CORS_ALLOW_ORIGINS is written as a JSON array. Make sure to use double quotes for the JSON array.

Note the following:

customer_istari_fqdn is the domain used for the Istari Digital platform, e.g. istari.customer_domain.com.
AWS_S3_access_key or Azure_storage_account_name are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_bucket or Azure_storage_container are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_endpoint_url or Azure_endpoint_url are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_region is obtained from the Object Store Configuration step
spicedb_preshared_key is obtained from the SpiceDB Install step
password is obtained from the AWS or Azure PostgreSQL Install step and is associated with the DB user registry_service

Install Istari Platform

Once the Zitadel Configurator has successfully installed and the istari-frontend and the istari-fileservice secrets have been created, you can proceed to install the Istari Platform:

helm pull oci://istaridigital.jfrog.io/customer-charts/istari-platform --version 3.3.5

You'll notice in the below command that --set fileService.extraEnvSecrets={zitadel-registry-service-env} is set to point to a registry-service-env secret. This is in preperation for "fileservice" to be renamed to "registry-service" as part of a future release.

helm upgrade --install istari istari-platform-3.3.5.tgz --set fileservice.extraEnvSecrets={zitadel-registry-service-env} --set frontend.extraEnvSecrets={zitadel-frontend-service-env}

Prerequisites​

Helm repo setup​

Define Zitadel Configurator Values

Configure Customer Domains

Zitadel Configuration

Frontend

Zitadel Org and Admin UserLogin

Install Zitadel Configurator

Configure Istari Platform Secrets

Frontend Service Secret​

Registry Service Secret​

Install Istari Platform

Prerequisites

Helm repo setup

Frontend Service Secret

Registry Service Secret