readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to serve as a readiness probe in a containerized or microservices environment. Its primary purpose is to check whether a backend service, specifically the **Blockbook API**, is fully synchronized and ready to serve requests. This script is typically used by container orchestrators (e.g., Kubernetes) to determine if the application instance should receive traffic.

The script checks for a "disable readiness probe" flag file and, if absent, queries the Blockbook API’s status endpoint. Based on the synchronization status returned, it exits with a success or failure code, signaling readiness or non-readiness.

Detailed Explanation

Script Workflow & Logic

1. Disable Readiness Probe Check

   • The script first checks if a special file /data/disable_readiness exists.

   • If this file exists, the readiness probe is considered disabled.

   • The script immediately outputs "readiness probe disabled" and exits with status code 0 (success).

2. Query Blockbook API Status

   • If the disable file is not present, the script sends a GET request to http://localhost:8001/api/v2 using curl.

   • The -s flag silences progress, and -f causes curl to fail if the HTTP response code is 400 or greater.

   • If curl fails (e.g., service is down or endpoint unreachable), the script exits with status 1 (failure).

3. Parse Synchronization Status

   • The JSON response is parsed using jq to extract the value of .blockbook.inSync.

   • If the value is "true", the script prints "blockbook is synced" and exits with status 0.

   • Otherwise, it prints "blockbook is still syncing" and exits with status 1.

Script Breakdown

#!/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

Parameters and Return Values

• Parameters:
  None. The script uses fixed endpoints and file paths.

• Exit Codes:

  • 0: Readiness check passed (either disabled or Blockbook synced)

  • 1: Readiness check failed (Blockbook not synced or API unreachable)

Usage Example

This script is not intended to be run manually but invoked by container orchestration platforms as a readiness probe command.

Example command to run manually:

./readiness.sh

Possible outputs:

• If disabled:

  readiness probe disabled
  

  Exit code: 0

• If synced:

  blockbook is synced
  

  Exit code: 0

• If syncing:

  blockbook is still syncing
  

  Exit code: 1

• If API unreachable:
  (no output, exits immediately)
  Exit code: 1

Implementation Details

• Disable Probe Mechanism: The presence of the /data/disable_readiness file acts as a manual override to skip readiness checks. This can be useful during maintenance or debugging.

• Health Check Endpoint: The script relies on a local HTTP API endpoint http://localhost:8001/api/v2 assumed to be exposed by the Blockbook service.

• JSON Parsing: Uses jq to extract the inSync boolean value from the JSON response, a robust and efficient way to handle JSON in shell scripts.

• Exit Codes: Exit status aligns with conventional readiness probe expectations where 0 means ready and non-zero means not ready.

Interaction with Other System Components

• Blockbook Service:
  The script depends directly on the Blockbook API’s /api/v2 endpoint to determine synchronization status. It assumes that Blockbook runs locally on port 8001.

• Container Orchestrator (e.g., Kubernetes):
  Typically configured as a readiness probe command. The orchestrator will execute this script regularly to decide if the pod/container should receive traffic.

• File System:
  The presence of /data/disable_readiness file controls whether this probe is active, allowing external control over readiness checks.

Mermaid Flowchart Diagram

flowchart TD
    Start([Start])
    CheckDisableFile{Does /data/disable_readiness file exist?}
    DisableTrue["Print 'readiness probe disabled' \nExit 0"]
    CurlAPI["Execute curl GET http://localhost:8001/api/v2"]
    CurlFail{Did curl succeed?}
    ExitFail["Exit 1"]
    ParseJSON["Parse JSON with jq: .blockbook.inSync"]
    InSyncTrue{Is inSync == 'true'?}
    Synced["Print 'blockbook is synced' \nExit 0"]
    Syncing["Print 'blockbook is still syncing' \nExit 1"]

    Start --> CheckDisableFile
    CheckDisableFile -- Yes --> DisableTrue
    CheckDisableFile -- No --> CurlAPI
    CurlAPI --> CurlFail
    CurlFail -- No --> ExitFail
    CurlFail -- Yes --> ParseJSON
    ParseJSON --> InSyncTrue
    InSyncTrue -- Yes --> Synced
    InSyncTrue -- No --> Syncing

Summary

`readiness.sh` is a minimal, robust readiness probe script that helps orchestrators determine when the Blockbook backend is ready to serve traffic. It elegantly combines file-based toggling, HTTP status querying, and JSON parsing to provide clear readiness signals, making it a vital utility in cloud-native deployment pipelines.