readiness.sh

Overview

`readiness.sh` is a lightweight Bash script intended to serve as a readiness probe for a service, particularly one that relies on the "blockbook" API. The script checks whether the service is ready to receive traffic by verifying the synchronization status of blockbook. It exits with status `0` (success) if the service is ready, or `1` (failure) otherwise.

This script is typically used in containerized environments (e.g., Kubernetes) to inform the orchestrator whether the application is ready to handle requests, thus controlling load balancing and deployment rollouts.

Detailed Explanation

Purpose

• Detect if the readiness probe should be disabled.

• Query a local blockbook API endpoint to check if the service is synchronized (inSync).

• Return appropriate exit codes for readiness status:

  • 0 for ready (service synced or probe disabled).

  • 1 for not ready (service still syncing or unable to reach API).

Script Breakdown

#!/bin/bash

• Declares the script interpreter as Bash.

DISABLE_READINESS_PROBE=/data/disable_readiness

• Defines a file path that, if present, disables the readiness check.

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

• If the file /data/disable_readiness exists, the script immediately exits with status 0, signaling readiness without further checks.

STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1

• Attempts a silent (-s) and fail-fast (-f) HTTP GET request to http://localhost:8001/api/v2.

• If the request fails (e.g., service unavailable), the script exits with 1.

IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')

• Parses the JSON response using jq to extract the .blockbook.inSync boolean value, which indicates synchronization status.

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

• If the service is in sync, prints a message and exits with 0.

echo "blockbook is still syncing"
exit 1

• Otherwise, prints a message indicating ongoing syncing and exits with 1.

Usage

Run the script directly in an environment where the blockbook API is accessible locally on port `8001`.

./readiness.sh

• Exit code 0 means the service is ready.

• Exit code 1 means the service is not ready.

Example Integration in Kubernetes

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

Important Implementation Details

• Disabling readiness check: The presence of /data/disable_readiness file overrides all checks and forces readiness. This is useful for maintenance or deployment phases.

• Dependency on curl and jq: The script requires these utilities for HTTP requests and JSON parsing.

• Local API endpoint: The script assumes the blockbook API is accessible locally via http://localhost:8001/api/v2.

• Exit codes: The script uses Unix exit codes to signal readiness status to external orchestrators.

Interaction with Other System Components

• Blockbook API: The script depends on the blockbook service exposing its status JSON at /api/v2.

• Container Orchestrator / Load Balancer: The readiness probe script is called by external systems like Kubernetes to determine if the service instance should receive traffic.

• Filesystem: The script checks for a specific file /data/disable_readiness to optionally disable the readiness check.

Mermaid Flowchart Diagram

flowchart TD
    Start([Start])
    CheckDisableFile{File /data/disable_readiness?}
    ExitReady("Exit 0: readiness probe disabled")
    CurlRequest["curl -sf http://localhost:8001/api/v2"]
    CurlFail["curl failed: Exit 1"]
    ParseSync["Parse .blockbook.inSync from JSON"]
    SyncCheck{inSync == "true"?}
    ExitSynced("Exit 0: blockbook is synced")
    ExitSyncing("Exit 1: blockbook is still syncing")

    Start --> CheckDisableFile
    CheckDisableFile -- Yes --> ExitReady
    CheckDisableFile -- No --> CurlRequest
    CurlRequest -- Fail --> CurlFail
    CurlRequest -- Success --> ParseSync
    ParseSync --> SyncCheck
    SyncCheck -- Yes --> ExitSynced
    SyncCheck -- No --> ExitSyncing

Summary

The `readiness.sh` script is a simple yet critical utility script designed to integrate with container orchestration systems by performing a readiness check on the blockbook service. It uses a combination of filesystem flags and API status checks to determine readiness, returning appropriate exit codes for orchestration logic. It requires `curl` and `jq` and assumes the blockbook API is locally reachable. The script helps ensure that traffic is only routed to fully synced and ready service instances.