Request icon
Return icon
Switch icon
Log icon
SlackIncomingWebhook icon
OutputValues icon
Schedule icon

ZITADEL Identity Provider Health and Readiness Sentinel

Audit ZITADEL IAM readiness, validate database connection pooling and OIDC discovery endpoints, classify cluster health, and alert Slack via Kestra.

Categories
BusinessInfrastructure

Continuously audits ZITADEL Identity and Access Management (IAM) clusters by probing database readiness endpoints, container health liveness routes, and OpenID Connect (OIDC) discovery metadata, classifying operational health, and dispatching real-time incident escalation alerts to Slack.

This blueprint was created by Mohit Jeswani.

How it works

  1. probe_ready_endpoint (io.kestra.plugin.core.http.Request) queries /debug/ready to verify that the ZITADEL instance has completed initialization and that its backend database connection pool (CockroachDB or PostgreSQL) is healthy and responsive.
  2. probe_health_endpoint (io.kestra.plugin.core.http.Request) queries /debug/healthz to confirm process liveness and web server responsiveness.
  3. probe_oidc_discovery (io.kestra.plugin.core.http.Request) queries /.well-known/openid-configuration to confirm that the public OpenID Connect discovery document is serving valid JSON with an intact issuer URL and cryptographic key endpoints.
  4. classify_zitadel_posture (io.kestra.plugin.core.debug.Return) evaluates endpoint response codes and metadata using a declarative Pebble expression:
    • Classifies as INSTANCE_UNREACHABLE if endpoints cannot be reached over the network.
    • Classifies as DATABASE_OR_BACKEND_UNREADY if /debug/ready returns non-200 (database stall or connection exhaustion).
    • Classifies as SERVICE_UNHEALTHY if /debug/healthz returns non-200.
    • Classifies as OIDC_DISCOVERY_CORRUPTED if the discovery document is unavailable or the issuer URL prefix does not match expectations.
    • Classifies as HEALTHY_COMPLIANT when all probes succeed.
  5. route_by_posture (io.kestra.plugin.core.flow.Switch) routes execution based on the classification:
    • HEALTHY_COMPLIANT: Logs successful audit confirmation with issuer URL and HTTP status codes.
    • DATABASE_OR_BACKEND_UNREADY: Posts a critical Slack alert flagging database connection exhaustion.
    • SERVICE_UNHEALTHY: Alerts Slack that the core process is degraded.
    • OIDC_DISCOVERY_CORRUPTED: Dispatches an urgent Slack alert warning that downstream SSO authentication will fail.
    • INSTANCE_UNREACHABLE: Notifies on-call teams of total service unavailability.
  6. audit_summary (io.kestra.plugin.core.output.OutputValues) exports structured metrics capturing endpoint HTTP status codes and cluster posture for compliance logging.
  7. errors sends a priority failure notification to Slack if unhandled workflow execution errors occur.

What you get

  • Automated, continuous validation of critical IAM control planes without relying on manual user login tests.
  • Early warning of database connection exhaustion and migration stalls before end users experience authentication timeouts.
  • Active verification of OIDC discovery documents so single sign-on (SSO) clients and API gateways never receive corrupted metadata.
  • Contextual Slack alerts detailing exact endpoint failure codes and instance hostnames.
  • Auditable execution history satisfying SOC2 and ISO27001 identity infrastructure monitoring controls.

Who it's for

  • Platform Engineers and SREs responsible for uptime and reliability of identity infrastructure.
  • Security Operations (SecOps) teams maintaining high-availability authentication backbones.
  • Cloud Architects managing self-hosted or Kubernetes-deployed ZITADEL IAM clusters.

Why orchestrate this with Kestra

Identity provider outages are critical Sev-0 incidents that cascade into every downstream microservice and enterprise portal. Standard TCP port checks cannot verify whether ZITADEL's backend database connection pool is functional or whether OIDC discovery documents are returning corrupted issuer URLs. Kestra orchestrates multi-stage HTTP inspection, declarative Pebble classification, failure escalation to Slack, and centralized compliance audit trails in a single workflow.

Prerequisites

  • A running ZITADEL instance (Docker container or Kubernetes cluster).
  • An incoming Slack webhook URL for incident notifications.

Secrets

  • SLACK_WEBHOOK_URL: Incoming Slack webhook URL used by alert_ready_failure_slack, alert_unhealthy_slack, alert_discovery_corrupted_slack, alert_unreachable_slack, and alert_flow_failure.

Quick start

  1. Configure SLACK_WEBHOOK_URL in your Kestra namespace secrets.
  2. Start a local ZITADEL instance using Docker:
    docker run -d --name zitadel -p 8080:8080 ghcr.io/zitadel/zitadel:latest start-from-init --masterkey "MasterkeyNeedsToHave32Characters"
    
  3. Import this blueprint into Kestra and click Execute with default inputs (zitadel_host: "localhost").
  4. Confirm that classify_zitadel_posture classifies HEALTHY_COMPLIANT and inspect the structured telemetry in audit_summary.
  5. Enable the hourly_canary schedule to automate continuous IAM health monitoring.

How to extend

  • Add authenticated user verification by querying /v2/users using a Personal Access Token (PAT) stored in Kestra secrets.
  • Integrate PagerDuty or Opsgenie alerts for out-of-hours on-call paging during INSTANCE_UNREACHABLE or DATABASE_OR_BACKEND_UNREADY incidents.
  • Expand multi-region monitoring by looping over an array of ZITADEL edge cluster hostnames using io.kestra.plugin.core.flow.ForEach.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.