readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to serve as a Kubernetes readiness probe or any similar health check mechanism. Its primary function is to determine if a backend service, specifically a **Blockbook API** running locally on port 8001, has fully synchronized and is ready to handle requests.

The script performs the following checks in order:

1. Disabling readiness probe: It 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.

2. Service availability: It then attempts to query the local Blockbook API endpoint /api/v2 using curl. If the service is unreachable or returns an error, the script exits with failure.

3. Sync status: It parses the JSON response to check if the Blockbook instance is "in sync." If synced, it exits successfully; otherwise, it exits with failure.

This script is typically used by container orchestrators to decide whether the container is ready to accept traffic.

Detailed Explanation

Script Workflow

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

Functional Breakdown

1. Disable Readiness Probe Check

• Purpose: Allow external control to disable the readiness probe.

• Mechanism: Checks if the file /data/disable_readiness exists.

• Outcome:

  • If file exists: Outputs "readiness probe disabled" and exits with 0 (success).

  • If file does not exist: Continues to subsequent checks.

2. Retrieve Blockbook API Status

• Command: curl -sf http://localhost:8001/api/v2

  • -s for silent mode (no progress meter).

  • -f to fail silently on server errors (non-2xx responses).

• Outcome:

  • On failure to reach the service or non-2xx HTTP response, the script exits with 1 (failure).

  • On success, stores JSON response in variable STATUS.

3. Parse Sync State

• Tool: jq — a command-line JSON processor.

• Parsing: Extracts .blockbook.inSync boolean from the JSON response.

• Outcome:

  • If "true", outputs "blockbook is synced" and exits 0.

  • If not "true", outputs "blockbook is still syncing" and exits 1.

Parameters

This script does not take command-line parameters. It relies on:

• The presence or absence of the file /data/disable_readiness.

• The availability of the local Blockbook API at http://localhost:8001/api/v2.

• The jq utility to parse JSON.

Return Values

• Exit code 0: The system is ready (either disabled probe or Blockbook is synced).

• Exit code 1: The system is not ready (Blockbook is syncing or unreachable).

Usage Example

This script is intended to be used as a Kubernetes readiness probe command:

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

The orchestrator runs the script periodically; if it exits with `0`, the pod is marked ready; otherwise, it is not.

Implementation Details

• Robustness: Uses curl -sf to handle HTTP errors gracefully.

• Dependency: Requires jq to parse JSON output; if jq is missing or the expected JSON structure changes, the script will fail.

• File-based toggle: The /data/disable_readiness file is a simple mechanism to disable readiness checks without changing the script or deployment configuration.

Interaction with Other System Components

• Blockbook API: The script depends on the Blockbook service exposing a REST API on localhost:8001. The API must provide a /api/v2 endpoint that returns a JSON object with a .blockbook.inSync boolean property indicating synchronization status.

• Orchestration Layer: Typically integrated with Kubernetes or other container orchestration platforms as a readiness probe to control routing of traffic.

• Filesystem: Relies on a shared volume or filesystem where the /data/disable_readiness file may be placed to disable readiness checks dynamically.

Mermaid Flowchart Diagram

flowchart TD
    A[Start] --> B{Check /data/disable_readiness file}
    B -- Exists --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- Not Exists --> E[Run curl to http://localhost:8001/api/v2]
    E -- Fail --> F[Exit 1]
    E -- Success --> G[Parse .blockbook.inSync field using jq]
    G --> H{Is inSync == "true"?}
    H -- Yes --> I[Print "blockbook is synced"]
    I --> D
    H -- No --> J[Print "blockbook is still syncing"]
    J --> F

Summary

`readiness.sh` is a simple yet effective shell script designed to monitor the readiness of a Blockbook backend service by checking its synchronization status through an HTTP API. It also includes a mechanism to disable the readiness check via a sentinel file. This script integrates well with container orchestration tools to provide dynamic service readiness feedback, improving deployment stability and traffic routing decisions.