readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to serve as a **readiness probe** for a Blockbook-based blockchain indexer service running inside a containerized environment (e.g., Kubernetes). Its primary purpose is to determine if the indexer is fully synchronized with the blockchain and therefore ready to handle API requests reliably.

It performs this by:

Checking for an override file that disables readiness checks.
Querying the local Blockbook API to retrieve the current synchronization status.
Exiting with appropriate status codes (0 for ready, 1 for not ready) to signal Kubernetes or other orchestrators about the pod's readiness state.

This mechanism helps ensure that only fully synced indexer pods receive traffic, improving overall system reliability and data consistency.

Detailed Explanation

Script Workflow

Disable Probe Check:
The script first checks for the presence of a sentinel file:
```
/data/disable_readiness
```
If this file exists, the readiness probe is considered disabled, and the script exits successfully (exit 0) immediately.
Query Blockbook API:
The script sends an HTTP GET request to the local Blockbook API endpoint:
```
http://localhost:8001/api/v2
```
Using curl with silent and fail flags (-sf), it captures the API response or exits with failure (exit 1) if the request fails (e.g., API down or unreachable).
Parse Synchronization Status:
The JSON response is parsed using jq to extract the value of:
```
.blockbook.inSync
```
This boolean flag indicates if the indexer is fully synced (true) or still syncing (false).
Determine Readiness:
- If .blockbook.inSync is "true", the script prints blockbook is synced and exits with 0, signaling readiness.
- Otherwise, it prints blockbook is still syncing and exits with 1, indicating the pod is not ready yet.

Code Breakdown

#!/bin/bash

DISABLE_READINESS_PROBE=/data/disable_readiness

# Check if readiness probe is disabled
if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
  echo "readiness probe disabled"
  exit 0
fi

# Query Blockbook API for status
STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1

# Parse the inSync flag from JSON response
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')

# Check the sync status and exit accordingly
if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1

Parameters and Return Values

This script does not accept any command-line parameters. Its behavior is controlled by:

The presence of the file /data/disable_readiness.
The availability and response of the local Blockbook API (http://localhost:8001/api/v2).

**Exit Codes:**

0 — The indexer is ready (synced) or readiness probing is disabled.
1 — The indexer is not ready (still syncing) or the API endpoint is unreachable.

Usage Example

In a Kubernetes deployment, this script would typically be configured as a readiness probe in the pod spec:

readinessProbe:
  exec:
    command:
      - /bin/bash
      - /path/to/readiness.sh
  initialDelaySeconds: 10
  periodSeconds: 5

Kubernetes will run the script periodically. If the script exits with `0`, the pod is marked as ready and can receive traffic. If it exits with `1`, the pod is marked as not ready.

Implementation Details and Algorithms

Sentinel File Override: The presence of /data/disable_readiness allows manual or automated disabling of readiness probes without changing deployment configurations. This can be useful during maintenance or troubleshooting.
HTTP Status Check: The curl -sf command ensures silent mode and fails fast on HTTP errors or connection issues, allowing the script to immediately return a non-ready status.
JSON Parsing: The script relies on jq for robust extraction of the .blockbook.inSync boolean from the JSON response. This avoids brittle string matching and allows future expansion of the JSON structure without breaking the probe.
Exit Codes as Signals: The script's exit codes directly map to readiness states, enabling easy integration with container orchestrators that rely on exit codes to determine pod health.

Interaction with Other System Components

Blockbook API: The readiness script depends on the Blockbook indexer’s REST API running locally on port 8001. The API provides the .blockbook.inSync flag, reflecting the indexer's internal synchronization state.
Container Orchestrator (Kubernetes): The script is intended to be used as a readiness probe command, influencing pod lifecycle and traffic routing decisions. Kubernetes uses the script's exit status to mark pods as ready or not ready.
Filesystem (Sentinel File): The presence of /data/disable_readiness allows external control over the readiness probe, possibly by other system components or operators.
jq Utility: The script requires jq installed in the container environment to parse JSON responses.

Visual Diagram

flowchart TD
    Start[Start readiness.sh script]
    CheckDisable[Check if /data/disable_readiness file exists]
    Disabled[Readiness probe disabled\nExit 0]
    QueryAPI[Send HTTP GET to\nhttp://localhost:8001/api/v2]
    CurlFail[API request failed\nExit 1]
    ParseSync[Parse .blockbook.inSync from JSON]
    CheckInSync{Is inSync == "true"?}
    Ready[Print "blockbook is synced"\nExit 0]
    NotReady[Print "blockbook is still syncing"\nExit 1]

    Start --> CheckDisable
    CheckDisable -->|Exists| Disabled
    CheckDisable -->|Not exists| QueryAPI
    QueryAPI -->|Fail| CurlFail
    QueryAPI -->|Success| ParseSync
    ParseSync --> CheckInSync
    CheckInSync -->|Yes| Ready
    CheckInSync -->|No| NotReady

Summary

`readiness.sh` is a simple yet effective readiness probe script designed to:

Verify if a Blockbook indexer is fully synchronized.
Allow disabling readiness dynamically via a sentinel file.
Provide clear exit codes and messages for orchestrators.
Integrate seamlessly with Kubernetes readiness probe mechanisms.

Its minimal dependencies and straightforward logic make it a reliable component in blockchain data stack health monitoring.

End of Documentation for readiness.sh