readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to serve as a readiness probe for a service, specifically monitoring the synchronization status of a "blockbook" API. It is intended for use in containerized environments or orchestration platforms (e.g., Kubernetes) to determine if the service is ready to handle requests.

The script performs the following key functions:

• Checks for a file that explicitly disables the readiness probe.

• Queries a local HTTP API to retrieve the current synchronization status.

• Uses this status to decide whether the service is ready (exits with status 0) or not ready (exits with status 1).

This allows operational systems to automatically detect when the service is fully synchronized and ready to accept traffic.

Detailed Explanation

Script Logic and Workflow

Below is a step-by-step explanation of the script's workflow:

1. Disable file check:
   The script looks for the presence of the file /data/disable_readiness. If this file exists, the readiness probe is effectively disabled, and the script prints "readiness probe disabled" and exits with status code 0 (success).

2. API call to check status:
   If the disable file is not present, the script performs an HTTP GET request to http://localhost:8001/api/v2 using curl.

   • The -s option makes curl silent.

   • The -f option makes curl fail and return a non-zero exit code on HTTP errors.
     If the curl command fails (e.g., service not reachable), the script exits immediately with status code 1 (failure).

3. Parse JSON response:
   The output of the curl command is expected to be a JSON object. The script uses jq to extract the value of the field .blockbook.inSync from the JSON.

4. Decision based on synchronization status:

   • If .blockbook.inSync 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.

Key Components

Script Usage

./readiness.sh

• Exit Code 0: The service is ready (blockbook is in sync or readiness probe is disabled).

• Exit Code 1: The service is not ready (blockbook is not in sync or the API query failed).

Example Output

$ ./readiness.sh
blockbook is synced

or if syncing is ongoing:

$ ./readiness.sh
blockbook is still syncing

or if disabled:

$ ./readiness.sh
readiness probe disabled

Implementation Details and Considerations

• Disabling readiness: The presence of /data/disable_readiness overrides all other checks, allowing manual control to bypass readiness gating (useful for maintenance or troubleshooting).

• Robustness:

  • Using curl -sf helps fail silently on server or network errors preventing false positives.

  • The script exits immediately on curl failure to prevent returning readiness when the service is unreachable.

• JSON parsing: jq is required and must be installed in the container or environment where this script runs.

• Port and endpoint: The API endpoint is hardcoded to http://localhost:8001/api/v2, assuming the blockbook service listens locally on port 8001.

• Exit codes: The script uses standard Unix exit codes to signal readiness to orchestrators like Kubernetes, which expect 0 for ready and non-zero for not ready.

Integration with the System

• Role in the architecture:
  This script is typically invoked as a readiness probe command in container orchestration platforms such as Kubernetes. The platform periodically runs this script to check if the service is ready to serve traffic.

• Dependencies:

  • curl for HTTP requests

  • jq for JSON parsing

  • The blockbook API service accessible locally at port 8001

• Impact:

  • Helps orchestrators manage rolling updates and traffic routing by reporting readiness state.

  • Prevents sending traffic to the service until it has fully synchronized, improving reliability.

Mermaid Flowchart Diagram: Script Workflow

flowchart TD
    A[Start] --> B{Does /data/disable_readiness exist?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit with code 0]
    B -- No --> E[Run curl -sf http://localhost:8001/api/v2]
    E -- Fail --> F[Exit with code 1]
    E -- Success --> G[Parse JSON with jq: .blockbook.inSync]
    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 critical script that serves as a readiness probe by querying the blockbook API's synchronization status. It supports disabling via a file, gracefully handles failures, and integrates with orchestration systems to ensure traffic is only routed when the service is fully synchronized and ready. Its minimal dependencies and straightforward logic make it easy to maintain and extend if needed.