readiness.sh

Overview

`readiness.sh` is a lightweight shell script designed to serve as a **Kubernetes readiness probe** for a Blockbook-based blockchain indexer. Its primary function is to determine whether the Blockbook indexer instance is fully synchronized with the blockchain and thus ready to serve accurate and up-to-date data.

This script performs the following key tasks:

Checks for the presence of a sentinel file to optionally disable readiness checking.
Queries the local Blockbook API endpoint to retrieve the current sync status.
Parses the JSON response to extract the synchronization flag.
Exits with a status code that Kubernetes uses to mark the pod as ready or not ready.

This readiness check ensures that traffic is only routed to indexers that have fully processed blockchain data, improving the reliability and consistency of API responses.

Detailed Explanation

The script is short, but each part is critical for its functionality.

Variables

DISABLE_READINESS_PROBE=/data/disable_readiness
Path to a "disable" sentinel file. If this file exists, readiness probing is skipped and the script exits successfully.

Script Logic and Flow

#!/bin/bash

DISABLE_READINESS_PROBE=/data/disable_readiness

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

STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')

if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1

Step-by-Step Breakdown

Disable Check
```
if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
  echo "readiness probe disabled"
  exit 0
fi
```
If the file /data/disable_readiness exists, the readiness check is bypassed, and the script exits 0 (success). This allows manual override to mark the pod as ready regardless of sync status.
Query Blockbook API Endpoint
```
STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1
```
Sends a silent (-s) and fail-fast (-f) HTTP GET request to the local Blockbook API endpoint. If the request fails (e.g., service down), the script exits 1 (failure).
Parse JSON Response
```
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')
```
Uses jq to extract the value of .blockbook.inSync from the JSON output. This flag is a boolean indicating whether Blockbook has fully synchronized with the blockchain.
Evaluate Sync Status
```
if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1
```
If inSync is true, the script returns success (0), signaling readiness. Otherwise, it returns failure (1), indicating the indexer is still syncing.

Usage Example

This script is intended to be configured as the `readinessProbe` command in Kubernetes pod specifications. Example snippet from a Kubernetes Deployment YAML:

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

Kubernetes will execute the script periodically to decide if the pod is ready to receive traffic.

Important Implementation Details

Sentinel File: The presence of /data/disable_readiness allows operators to quickly disable readiness checks without modifying deployment configs or restarting pods.
Robust Curl Usage: The -sf flags ensure the script fails on HTTP errors or connection issues, preventing false readiness signals.
JSON Parsing: The script depends on jq to parse the API response; this utility must be available in the container.
Exit Codes: Exit code 0 signals Kubernetes that the service is ready; exit code 1 indicates not ready.

Interaction with Other System Components

Blockbook Indexer API: The script queries the local Blockbook API running on localhost:8001 to get the current synchronization status.
Kubernetes: Acts as a readiness probe command; Kubernetes uses its exit code to mark the pod's readiness state.
Filesystem: Checks for a sentinel file to optionally disable readiness probe behavior.
Container Environment: Assumes presence of curl and jq utilities for HTTP requests and JSON parsing.

Together, these interactions enable Kubernetes to route traffic only to indexers that are fully synchronized, ensuring data consistency and reliability in the blockchain data serving layer.

Mermaid Diagram: Flowchart of readiness.sh Script Logic

flowchart TD
    Start[Start readiness.sh script]
    CheckDisable[Check if /data/disable_readiness file exists]
    Disabled[Readiness probe disabled\nExit 0]
    QueryAPI[Query Blockbook API\nGET http://localhost:8001/api/v2]
    CurlFail{Did curl succeed?}
    ParseSync[Parse .blockbook.inSync flag using jq]
    InSyncTrue{Is inSync == "true"?}
    Ready[Indexer ready\nExit 0]
    NotReady[Indexer syncing\nExit 1]

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

Summary

`readiness.sh` is a concise, reliable readiness probe script that leverages the Blockbook API’s internal sync status to inform Kubernetes about the indexer’s readiness state. It incorporates a manual override mechanism and uses robust HTTP querying and JSON parsing techniques to ensure accurate readiness signaling. This script plays a crucial role in maintaining high availability and data correctness for blockchain indexer services in Kubernetes environments.