Hasura GraphQL Metadata Desync Sentinel

id: hasura-graphql-metadata-desync-sentinel
namespace: company.infrastructure

inputs:
  - id: hasura_endpoint
    type: STRING
    displayName: Hasura GraphQL Engine Endpoint
    description: Base URL of the Hasura GraphQL Engine instance.
    defaults: "http://localhost:8080"

  - id: max_allowed_inconsistencies
    type: INT
    displayName: Maximum Allowed Inconsistencies
    description: Tolerance threshold of inconsistent objects before raising a
      critical incident alert.
    defaults: 0

  - id: send_slack_alert
    type: BOOL
    displayName: Dispatch Slack Incident Alert
    description: Whether to transmit real-time Slack notifications upon metadata
      desynchronization.
    defaults: true

triggers:
  - id: metadata_audit_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Recurring audit polling Hasura metadata consistency every 15 minutes.
    cron: "*/15 * * * *"
    disabled: true

tasks:
  - id: probe_hasura_metadata
    type: io.kestra.plugin.core.http.Request
    description: Query Hasura metadata API for inconsistent schema objects and
      desynchronized tables.
    uri: "{{ inputs.hasura_endpoint }}/v1/metadata"
    method: POST
    headers:
      x-hasura-admin-secret: "{{ secret('HASURA_ADMIN_SECRET') }}"
      Content-Type: "application/json"
    contentType: "application/json"
    body: '{"type": "get_inconsistent_metadata", "args": {}}'
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT5S
      maxAttempts: 3
    allowFailure: true

  - id: evaluate_metadata_consistency
    type: io.kestra.plugin.scripts.python.Script
    description: Interrogate Hasura metadata response, extract inconsistent
      entities, and classify health state.
    taskRunner:
      type: io.kestra.plugin.core.runner.Process
    inputFiles:
      response.json: "{{ outputs.probe_hasura_metadata.body }}"
    script: |
      import json
      import sys

      max_allowed = int({{ inputs.max_allowed_inconsistencies }})

      try:
          with open("response.json", "r") as f:
              raw = f.read().strip()
              data = json.loads(raw) if raw else {}
      except Exception as e:
          data = {"is_consistent": False, "inconsistent_objects": [{"name": "API_UNREACHABLE", "type": "network", "reason": str(e)}]}

      is_consistent = data.get("is_consistent", False)
      inconsistent_objects = data.get("inconsistent_objects", [])
      inconsistent_count = len(inconsistent_objects)

      broken_names = [f"{obj.get('type', 'object')}:{obj.get('name', 'unknown')}" for obj in inconsistent_objects[:5]]
      broken_summary = ", ".join(broken_names) if broken_names else "none"

      if is_consistent and inconsistent_count == 0:
          classification = "CONSISTENT_HEALTHY"
      elif inconsistent_count <= max_allowed:
          classification = "DESYNC_WARNING"
      else:
          classification = "CRITICAL_METADATA_DESYNC"

      output_payload = {
          "outputs": {
              "is_consistent": is_consistent,
              "inconsistent_count": inconsistent_count,
              "broken_summary": broken_summary,
              "classification": classification
          }
      }
      print(f"::{json.dumps(output_payload)}::")

  - id: classify_schema_status
    type: io.kestra.plugin.core.log.Log
    description: Log evaluated Hasura metadata consistency metrics and status
      classification.
    message: |
      Hasura Endpoint: {{ inputs.hasura_endpoint }}
      Is Consistent: {{ outputs.evaluate_metadata_consistency.vars.is_consistent }}
      Inconsistent Objects Count: {{ outputs.evaluate_metadata_consistency.vars.inconsistent_count }}
      Broken Entities: {{ outputs.evaluate_metadata_consistency.vars.broken_summary }}
      Classification: {{ outputs.evaluate_metadata_consistency.vars.classification }}

  - id: route_consistency_gate
    type: io.kestra.plugin.core.flow.Switch
    description: Route flow execution based on Hasura metadata consistency classification.
    value: "{{ outputs.evaluate_metadata_consistency.vars.classification }}"
    cases:
      CONSISTENT_HEALTHY:
        - id: log_healthy_state
          type: io.kestra.plugin.core.log.Log
          description: Log nominal verification confirming all GraphQL entities are
            synchronized.
          message: "HEALTHY: Hasura metadata is fully consistent with backing Postgres
            database schema."

      DESYNC_WARNING:
        - id: log_desync_advisory
          type: io.kestra.plugin.core.log.Log
          description: Log advisory warning for non-critical schema inconsistencies within
            tolerance limits.
          message: "WARNING: Hasura metadata detected {{
            outputs.evaluate_metadata_consistency.vars.inconsistent_count }}
            inconsistent object(s): {{
            outputs.evaluate_metadata_consistency.vars.broken_summary }}."

      CRITICAL_METADATA_DESYNC:
        - id: alert_slack_inconsistency
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Dispatch urgent incident alert to platform engineering channel.
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": ":rotating_light: *CRITICAL Hasura Metadata Desynchronization Sentinel Alert*\n*Endpoint:* `{{ inputs.hasura_endpoint }}`\n*Inconsistent Objects:* `{{ outputs.evaluate_metadata_consistency.vars.inconsistent_count }}`\n*Broken Entities:* `{{ outputs.evaluate_metadata_consistency.vars.broken_summary }}`\n*Execution:* <{{ flow.url }}|{{ execution.id }}>"
            }

        - id: quarantine_schema_gate
          type: io.kestra.plugin.core.execution.Fail
          description: Fail execution to halt downstream API consumers and trigger alert
            escalation.

  - id: final_audit_log
    type: io.kestra.plugin.core.log.Log
    description: Record immutable audit log entry documenting Hasura metadata health
      verification.
    message: |
      [AUDIT] Hasura GraphQL Metadata Desynchronization Sentinel completed.
      Endpoint: {{ inputs.hasura_endpoint }}
      Consistent: {{ outputs.evaluate_metadata_consistency.vars.is_consistent }}
      Inconsistencies: {{ outputs.evaluate_metadata_consistency.vars.inconsistent_count }}
      Verdict: {{ outputs.evaluate_metadata_consistency.vars.classification }}

Automated GraphQL reliability sentinel that interrogates the Hasura GraphQL Engine metadata API on a recurring schedule to audit schema consistency against underlying Postgres tables, classify desynchronization severity, and dispatch Slack incident alerts when broken entity dependencies or missing database columns are detected.

How it works

A schedule trigger activates every fifteen minutes to probe the Hasura GraphQL Engine instance.
An HTTP request task queries Hasura's /v1/metadata endpoint utilizing the get_inconsistent_metadata administrative command.
An embedded Python script processes the returned JSON payload, interrogating the is_consistent boolean flag and extracting the count and names of any broken entity relationships.
An informational log task records the evaluated consistency metrics and current schema classification.
A Switch flow control task branches execution according to the evaluated status:
- CONSISTENT_HEALTHY: Confirms schema alignment and logs nominal operational telemetry.
- DESYNC_WARNING: Emits a non-blocking advisory notification when minor discrepancies fall within allowable limits.
- CRITICAL_METADATA_DESYNC: Dispatches a detailed Slack incident webhook with broken entity names, execution deep links, and triggers a downstream execution failure gate to quarantine corrupted deployments.
An immutable final audit log records the comprehensive health verdict and inconsistency metrics in Kestra execution history.

What you get

Proactive schema drift and desynchronization detection before frontend web or mobile GraphQL queries fail.
Automated catalog health audits catching broken remote schemas, dropped Postgres columns, and orphaned foreign keys.
Rich Slack notifications alerting platform engineering teams with specific broken entity names.
Automated execution failure gates that halt dependent deployment pipelines when database migrations break Hasura metadata.
Complete, immutable audit records tracking GraphQL catalog stability across continuous delivery cycles.

Who it's for

Platform Engineers and SREs maintaining production Hasura GraphQL Engine deployments.
Backend Developers and Database Administrators executing continuous schema migrations against PostgreSQL databases.
Frontend and Fullstack Engineers reliant on stable, unbroken GraphQL API contracts.

Why orchestrate this with Kestra

Declarative YAML orchestrates API health polling, payload parsing, and incident dispatching without dedicated monitoring agents.
Native secret masking ensures administrative API tokens and Slack webhook URLs remain confidential during automated runs.
Built-in conditional branching enables granular escalation policies tailored to schema severity tiers.
Centralized execution timelines provide instant diagnostic visibility into historical metadata failure patterns.

Prerequisites

Reachable Hasura GraphQL Engine instance (local Docker container or hosted deployment).
Network connectivity between Kestra and the Hasura administrative endpoint.

Secrets

HASURA_ADMIN_SECRET: Administrative secret token granting access to Hasura's /v1/metadata API.
SLACK_WEBHOOK_URL: Slack Incoming Webhook URL used to transmit critical schema inconsistency incident alerts.

Quick start

Configure the HASURA_ADMIN_SECRET and SLACK_WEBHOOK_URL secrets in your Kestra namespace or environment variables.
Import this blueprint into your Kestra instance under company.infrastructure.
Run a manual test execution pointing to your Hasura endpoint to verify connectivity and clean schema parsing.
Enable the metadata_audit_schedule trigger to maintain continuous 15-minute schema monitoring.

How to extend

Add an automated Hasura metadata reload task (reload_metadata) in the remediation branch to automatically attempt self-healing before alerting engineers.
Chain this flow as a post-migration verification gate following Flyway or Liquibase database deployments.
Route separate alerts to PagerDuty or Opsgenie when critical core business models desynchronize.

Hasura GraphQL Metadata Desync and Schema Inconsistency Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Hasura GraphQL Metadata Desync and Schema Inconsistency Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Recover a Helm release stuck pending after an interrupted upgrade

HealthLake FHIR Import Job Health Gate

Helm Release Health Sentinel

HashiCorp Vault Seal Status and HA Cluster Sentinel

Headscale Tailnet Node Health and Expiry Sentinel

Hazelcast Cluster State & Partition Safety Sentinel

New to Kestra?