readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to act as a readiness probe for a service that relies on a local Blockbook API. It determines whether the service is ready to handle traffic by checking if the Blockbook instance is synchronized. The script supports disabling the readiness check via a specific file flag and returns appropriate exit codes and messages based on the service's sync status.

This script is typically used in containerized environments (e.g., Kubernetes) as a readiness probe to control traffic routing based on the health and synchronization state of the backend Blockbook service.

Detailed Explanation

Script Purpose and Workflow

• Purpose:
  To verify if the Blockbook service is fully synchronized and ready.

• Key Checks:

  • If the readiness probe is disabled via a file flag.

  • If the local Blockbook API is reachable.

  • If the Blockbook service reports it is "in sync."

Step-by-Step Functionality

1. Check for Disable Flag
   The script checks if the file /data/disable_readiness exists. If yes, it prints "readiness probe disabled" and exits with a status code 0 (success), effectively bypassing the readiness check.

2. Fetch Blockbook Status
   Uses curl with -s (silent) and -f (fail on HTTP error) options to retrieve JSON status from http://localhost:8001/api/v2.

   • If the curl command fails (e.g., service not running or unreachable), the script exits with 1 (failure).

3. Parse Synchronization Status
   Parses the JSON response using jq to extract the .blockbook.inSync boolean value.

4. Decision Based on Sync Status

   • If .blockbook.inSync is "true", prints "blockbook is synced" and exits with 0.

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

Script Breakdown

#!/bin/bash

DISABLE_READINESS_PROBE=/data/disable_readiness

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

# Step 2: Get Blockbook status
STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1

# Step 3: Extract inSync field from JSON response
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')

# Step 4: Check if blockbook is synced
if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1

Parameters and Return Values

Usage Example

This script is intended to be invoked by external systems (e.g., Kubernetes readiness probes), but can be run manually for debugging:

$ ./readiness.sh
blockbook is synced
$ echo $?
0

Or, if the service is not synced:

$ ./readiness.sh
blockbook is still syncing
$ echo $?
1

If readiness probe is disabled by creating the file `/data/disable_readiness`:

$ touch /data/disable_readiness
$ ./readiness.sh
readiness probe disabled
$ echo $?
0

Important Implementation Details

• Disabling Mechanism:
  The presence of /data/disable_readiness acts as a simple toggle to bypass readiness checks without modifying the script or container configuration. This is useful for maintenance or troubleshooting.

• Reliance on External Tools:
  The script depends on:

  • curl for HTTP requests.

  • jq for JSON parsing.
    These must be installed in the environment where the script runs.

• Exit Codes:
  The script uses Unix exit codes to signal readiness status, which is the standard expected by container orchestration platforms.

• Error Handling:
  The script uses curl -f to fail silently on HTTP errors and immediately exits with code 1 on failure, ensuring that transient network/service issues cause the readiness probe to fail.

Interaction with Other System Components

• Blockbook API (localhost:8001):
  The script queries the Blockbook API endpoint /api/v2 running locally. This API must be accessible from the environment where the script runs.

• Container Orchestrators (e.g., Kubernetes):
  Typically configured as a readiness probe command/script in pod specs. The exit code and output control pod readiness for service routing.

• File System:
  The presence or absence of /data/disable_readiness on the filesystem controls whether the readiness check is active.

Visual Diagram: Workflow Flowchart

flowchart TD
    Start([Start])
    CheckDisable[Check if /data/disable_readiness exists]
    Disabled[Print "readiness probe disabled"\nExit 0]
    CurlStatus[Execute curl -sf http://localhost:8001/api/v2]
    CurlFail[Exit 1]
    ParseJSON[Parse JSON for .blockbook.inSync]
    InSyncTrue[Print "blockbook is synced"\nExit 0]
    InSyncFalse[Print "blockbook is still syncing"\nExit 1]

    Start --> CheckDisable
    CheckDisable -- Yes --> Disabled
    CheckDisable -- No --> CurlStatus
    CurlStatus -- Fail --> CurlFail
    CurlStatus -- Success --> ParseJSON
    ParseJSON -->|inSync == "true"| InSyncTrue
    ParseJSON -->|inSync != "true"| InSyncFalse

Summary

`readiness.sh` is a simple, robust readiness check script for verifying the synchronization status of a local Blockbook service. It efficiently integrates with container orchestration systems by using standard exit codes and leverages file-based toggling to allow dynamic disabling of the readiness check when needed. Its lightweight design and minimal dependencies make it ideal for containerized environments where quick health assessments are critical for service availability and traffic management.