Self-Hosting

Identity Chart

Deploy Zitadel for OIDC authentication using the identity Helm chart.

The identity chart deploys Zitadel, the OIDC provider that handles all authentication for flex.plane. It includes Zitadel itself and optionally a PostgreSQL database.

Configure values

The identity chart wraps the upstream Zitadel Helm chart with flex.plane-specific defaults. Here are the key values to configure.

Database

Zitadel requires PostgreSQL. You can either use the bundled PostgreSQL subchart or point to an external database.

# charts/identity/values.yaml

# Use bundled PostgreSQL
postgresql:
  enabled: true
  fullnameOverride: "postgresql"
  auth:
    database: "zitadel"
    username: "zitadel"
    existingSecret: "postgresql"
    secretKeys:
      adminPasswordKey: "ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD"
      userPasswordKey: "ZITADEL_DATABASE_POSTGRES_USER_PASSWORD"

For production deployments, use an external managed PostgreSQL instance. The bundled subchart is suitable for development and testing but does not include high availability or automated backups.

Zitadel configuration

zitadel:
  enabled: true
  fullnameOverride: zitadel
  replicaCount: 1

  envVarsSecret: postgresql

  zitadel:
    masterkeySecretName: zitadel
    configmapConfig:
      TLS:
        Enabled: false
      Database:
        Postgres:
          Host: postgresql
          Port: 5432
          Database: zitadel
          User:
            Username: zitadel
            SSL:
              Mode: disable
          Admin:
            Username: postgres
            SSL:
              Mode: disable

Create secrets

Zitadel requires a master key and PostgreSQL credentials. Create these before deploying:

# Generate a 32-byte master key for Zitadel
kubectl create secret generic zitadel \
  --namespace flexplane-identity \
  --from-literal=masterkey="$(openssl rand -hex 16)"

# PostgreSQL credentials
kubectl create secret generic postgresql \
  --namespace flexplane-identity \
  --from-literal=ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD="$(openssl rand -base64 24)" \
  --from-literal=ZITADEL_DATABASE_POSTGRES_USER_PASSWORD="$(openssl rand -base64 24)"

Deploy the chart

kubectl create namespace flexplane-identity

helm install identity charts/identity \
  -n flexplane-identity \
  -f my-identity-values.yaml

Wait for Zitadel to become ready:

kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=zitadel \
  -n flexplane-identity --timeout=300s

Configure Zitadel

Once Zitadel is running, access its admin console to set up the flex.plane tenant.

Access the console

Set up a port-forward to the Zitadel service:

kubectl port-forward svc/zitadel -n flexplane-identity 8443:8080

Open http://localhost:8443/ui/console in your browser. Log in with the default admin credentials (check the Zitadel docs for initial setup).

Create the organization and project

Create an organization for your flex.plane tenant (e.g., "My Company").
Create a project within that organization (e.g., "flex.plane").
Note down the Organization ID and Project ID. You will need these for the platform deployment.

Create project roles

Add the following roles to your project. These map directly to flex.plane's RBAC model:

Role Key	Display Name	Description
`USER`	User	Tenant-wide user access
`ADMIN`	Admin	Tenant-wide admin access
`VDC_USER`	VDC User	User access scoped to a VDC
`VDC_ADMIN`	VDC Admin	Admin access scoped to a VDC

Create the portal OIDC application

In your project, click New Application.
Choose Web as the application type.
Set the authentication method to PKCE.
Configure redirect URIs:
- https://flexplane.example.com/portal/auth/callback
- http://localhost:3000/portal/auth/callback (for local development)
Set the post-logout redirect URI: https://flexplane.example.com/portal/
Note down the Client ID.

Create a machine user for the orchestrator

The orchestrator needs API access to Zitadel for managing VDC memberships and roles:

Go to Users and create a new Machine User (e.g., "flexplane-orchestrator").
Under the machine user's Keys, generate a new JWT key.
Download the JSON key file. You will mount this as a Kubernetes secret.

kubectl create secret generic zitadel-key \
  --namespace flexplane \
  --from-file=key.json=./downloaded-key.json

The Zitadel organization ID (ZITADEL_ORG_ID) is visible in the console URL when you are inside the organization. You will need this for the orchestrator configuration.

Verify authentication

Test that Zitadel is serving OIDC discovery correctly:

curl -s https://id.flexplane.example.com/.well-known/openid-configuration | jq .issuer

The output should match your configured issuer URL:

"https://id.flexplane.example.com"

If you are using port-forwarding for testing, replace the URL accordingly: http://localhost:8443/.well-known/openid-configuration.

Edit this pageorReport an issue

Helm Charts Overview

The charts that make up a flex.plane deployment and how they fit together.

Flextenant Chart

Deploy the orchestrator and portal, the core of flex.plane.