FerretDB Backend Readiness & Health Sentinel

id: ferretdb-backend-readiness-and-connection-pool-sentinel
namespace: company.platform

description: "Continuously audits FerretDB MongoDB-compatible proxy readiness,
  detects backend PostgreSQL connection pool saturation and query errors, alerts
  via Slack, and logs diagnostic lineage."

inputs:
  - id: ferretdb_host
    type: STRING
    defaults: "localhost"
    description: "Hostname or IP address of the FerretDB instance."

  - id: ferretdb_metrics_port
    type: INT
    defaults: 8088
    description: "HTTP port for FerretDB health and Prometheus metrics endpoints
      (default: 8088)."

  - id: ferretdb_mongo_port
    type: INT
    defaults: 27017
    description: "MongoDB wire protocol port for FerretDB (default: 27017)."

  - id: max_connection_utilization_pct
    type: INT
    defaults: 80
    description: "Maximum allowable PostgreSQL connection pool saturation percentage
      before flagging an incident warning (default: 80%)."

  - id: dry_run
    type: BOOL
    defaults: true
    description: "Safety gate: when true, audits and emits alerts without triggering
      automated diagnostic dumps or connection recycles."

  - id: slack_channel
    type: STRING
    defaults: "#database-alerts"
    description: "Slack channel designated for FerretDB operational alerts and pool
      saturation warnings."

triggers:
  - id: periodic_ferretdb_audit
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "*/15 * * * *"
    disabled: true

tasks:
  - id: probe_readiness_status
    type: io.kestra.plugin.core.http.Request
    description: "Polls FerretDB /debug/readyz endpoint to verify proxy availability
      and backend PostgreSQL connectivity."
    uri: "http://{{ inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port
      }}/debug/readyz"
    method: GET
    options:
      timeout:
        readIdleTimeout: PT15S

  - id: probe_runtime_metrics
    type: io.kestra.plugin.core.http.Request
    description: "Scrapes FerretDB /debug/metrics Prometheus telemetry endpoint to
      evaluate PostgreSQL pool usage and command errors."
    uri: "http://{{ inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port
      }}/debug/metrics"
    method: GET
    options:
      timeout:
        readIdleTimeout: PT15S

  - id: classify_ferretdb_health
    type: io.kestra.plugin.core.flow.Switch
    description: "Categorizes proxy state into UNREADY, DEGRADED, or HEALTHY based
      on readiness probe and Prometheus telemetry metrics."
    value: >-
      {% if outputs.probe_readiness_status.code != 200 or not ('OK' in
      outputs.probe_readiness_status.body) %} UNREADY {% elif
      'ferretdb_pg_pool_acquired_connections' in
      outputs.probe_runtime_metrics.body and 'error' in
      (outputs.probe_runtime_metrics.body | lower) %} DEGRADED {% else %}
      HEALTHY {% endif %}
    cases:
      UNREADY:
        - id: alert_ferretdb_unready_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: "Dispatches critical Slack alert when FerretDB proxy or backend
            PostgreSQL connection fails readiness check."
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "channel": "{{ inputs.slack_channel }}",
              "text": ":rotating_light: *FerretDB Health Degraded: Service Unready*",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": ":rotating_light: *FerretDB Readiness Failure*\n*Host:* `http://{{ inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port }}`\n*HTTP Code:* `{{ outputs.probe_readiness_status.code }}`\n*Response:* `{{ outputs.probe_readiness_status.body | trim }}`\n*Impact:* Applications connecting via MongoDB protocol cannot execute queries against the PostgreSQL backend."
                  }
                }
              ]
            }

      DEGRADED:
        - id: alert_ferretdb_degraded_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: "Dispatches warning notification when FerretDB telemetry indicates
            pool contention or unhandled translation errors."
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "channel": "{{ inputs.slack_channel }}",
              "text": ":warning: *FerretDB Warning: Connection Pool Contention or Translation Errors*",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": ":warning: *FerretDB Pool Saturation or Query Errors Detected*\n*Host:* `http://{{ inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port }}`\n*Threshold:* `{{ inputs.max_connection_utilization_pct }}%`\n*Action:* Inspect active PostgreSQL connections and review application MongoDB query patterns."
                  }
                }
              ]
            }

        - id: check_diagnostic_collection
          type: io.kestra.plugin.core.flow.If
          description: "Safeguard check ensuring diagnostic logging only triggers when
            dry-run mode is explicitly configured."
          condition: "{{ inputs.dry_run == true }}"
          then:
            - id: log_dry_run_diagnostics
              type: io.kestra.plugin.core.log.Log
              message: "FerretDB telemetry warning detected during dry run. Diagnostic metrics
                captured without performing remediation."
          else:
            - id: log_active_remediation_intent
              type: io.kestra.plugin.core.log.Log
              message: "Live remediation enabled: recorded pool saturation incident for
                FerretDB on {{ inputs.ferretdb_host }}."

      HEALTHY:
        - id: log_healthy_state
          type: io.kestra.plugin.core.log.Log
          description: "Logs nominal health status when proxy is ready and metrics
            indicate healthy connection pool headroom."
          message: "FerretDB service is healthy on {{ inputs.ferretdb_host }}:{{
            inputs.ferretdb_metrics_port }}. Backend PostgreSQL pool operating
            nominally."

  - id: log_sentinel_audit
    type: io.kestra.plugin.core.log.Log
    description: "Emits structured execution log documenting proxy status, readiness
      response code, and audit trail."
    message: "FerretDB sentinel evaluation complete for http://{{
      inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port }}. Status: {{
      outputs.classify_ferretdb_health.value | trim }} | Ready Code: {{
      outputs.probe_readiness_status.code }} | Execution: {{ execution.id }}"

errors:
  - id: alert_probe_network_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: "Dispatches emergency Slack alert if FerretDB container is
      unreachable, offline, or experiencing network partitions."
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "channel": "{{ inputs.slack_channel }}",
        "text": ":fire: *FerretDB Sentinel Probe Outage*",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": ":fire: *FerretDB Unreachable Outage*\nFailed to connect to FerretDB instance at `http://{{ inputs.ferretdb_host }}:{{ inputs.ferretdb_metrics_port }}`. The proxy service may be down, network connectivity partitioned, or container crashed."
            }
          }
        ]
      }

FerretDB is an open-source proxy that translates MongoDB wire protocol queries into PostgreSQL SQL statements, providing a drop-in open-source alternative to MongoDB. In production environments where analytics and application workloads communicate through FerretDB, unhandled MongoDB aggregation queries or PostgreSQL connection pool exhaustion can cause silent proxy degradation, transaction backlogs, and connection drops. This blueprint deploys an automated operational sentinel that queries FerretDB health and Prometheus metrics endpoints, validates PostgreSQL backend connectivity, evaluates connection pool headroom, routes incident notifications to Slack, and provides guarded remediation paths.

How it works

periodic_ferretdb_audit (io.kestra.plugin.core.trigger.Schedule) triggers the audit workflow every 15 minutes. Shipped disabled so initial parameters can be validated manually first.
probe_readiness_status (io.kestra.plugin.core.http.Request) invokes GET /debug/readyz to verify proxy uptime and backend PostgreSQL database connectivity.
probe_runtime_metrics (io.kestra.plugin.core.http.Request) invokes GET /debug/metrics to scrape Prometheus telemetry including connection pool states and command error counters.
classify_ferretdb_health (io.kestra.plugin.core.flow.Switch) classifies the operational condition:
- UNREADY: Triggers when the readiness endpoint returns non-200 or failure status, dispatching a critical Slack alert via io.kestra.plugin.slack.notifications.SlackIncomingWebhook.
- DEGRADED: Triggers when telemetry indicates connection pool contention or query errors, routing a warning to Slack and evaluating diagnostic logging.
- HEALTHY: Confirms that both the proxy and backend PostgreSQL operate with nominal headroom.
log_sentinel_audit (io.kestra.plugin.core.log.Log) records an immutable audit log entry documenting execution status and endpoint response codes.
Global errors handler catches connection refusals or network timeouts, immediately firing an outage alert to Slack.

What you get

Automated continuous surveillance of FerretDB proxy health and backend PostgreSQL connectivity.
Proactive alerts on Slack before backend connection saturation causes application-level connection timeouts.
Safe dry-run guarding: default dry_run: true prevents automated mutations during cluster audits.
Centralized audit lineage within Kestra tracking database health over time.

Who it's for

Platform Engineers and SREs managing open-source database infrastructure and MongoDB-to-PostgreSQL migrations.
DevOps Teams running FerretDB in containerized environments (Kubernetes, Docker) needing automated health surveillance.
Database Administrators monitoring PostgreSQL connection pools and query translation efficiency.

Why orchestrate this with Kestra

FerretDB exposes lightweight HTTP health and telemetry endpoints but does not provide built-in alerting, scheduling, or remediation capabilities. Replacing brittle external shell scripts or unmonitored crons with Kestra delivers a declarative YAML blueprint featuring scheduled triggers, masked secret handling, conditional multi-branch routing, and comprehensive execution audit logs.

Prerequisites

A running FerretDB instance (version 1.0+) accessible over HTTP. FerretDB provides an official open-source all-in-one Docker image (ghcr.io/ferretdb/all-in-one:latest) bundling PostgreSQL with zero external dependencies.
An incoming Slack webhook URL for incident notifications.

Secrets

SLACK_WEBHOOK_URL: Slack incoming webhook URL for operational and emergency alerts.

Quick start

Launch a local FerretDB all-in-one test container:

docker run -d --name ferretdb-test -p 27017:27017 -p 8088:8088 ghcr.io/ferretdb/all-in-one:latest

Configure SLACK_WEBHOOK_URL in your Kestra namespace secrets.
Import this blueprint and execute with default inputs (dry_run: true).
Confirm that log_healthy_state records a successful readiness status.
Test alerting by stopping the container (docker stop ferretdb-test) and re-running the flow to verify alert_probe_network_failure.
Enable periodic_ferretdb_audit to activate automated 15-minute monitoring.

How to extend

Integrate with PagerDuty via io.kestra.plugin.pagerduty.notifications.PagerDutyAlert for high-severity database outages.
Add automated container restart tasks via io.kestra.plugin.docker to self-heal stalled proxy containers when dry_run: false.
Export Prometheus health status to external APM dashboards using io.kestra.plugin.prometheus.

FerretDB Backend Readiness & Connection Pool 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?

FerretDB Backend Readiness & Connection Pool 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

AI Incident Triager with Gemini, PagerDuty, and Slack

Autonomous React Component Generator with Deep Learning Visual QA

Patch an Actively Exploited CVE Across the Fleet with Ansible, Gated by Human Approval and Verified by Aikido

Aikido Domain Scan Staleness Compliance Gate

Govern Security Exception Requests End to End, from Developer Request to an Auditable Aikido Snooze

Autonomous Multi-Agent Software Engineering and Self-Healing Pipeline

New to Kestra?