readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to act as a readiness probe for a service, most likely in a containerized environment such as Kubernetes. Its primary function is to verify whether a backend service (referred to as "blockbook") is fully synchronized and ready to serve requests. The script performs this check by querying a local HTTP API endpoint and interpreting the JSON response to determine the synchronization status.

If a specific flag file exists, the readiness check can be forcibly disabled, allowing flexibility in operational scenarios such as maintenance or debugging.

Detailed Explanation

Script Workflow

1. Disable Flag Check:
   The script first checks for the presence of a file /data/disable_readiness. If this file exists, the readiness probe is disabled, the script outputs a message, and exits with success (exit 0).

2. Status Retrieval:
   If readiness is not disabled, the script sends an HTTP GET request to http://localhost:8001/api/v2 using curl with silent (-s) and fail-fast (-f) options. If this request fails (e.g., service down or network error), the script exits with failure (exit 1).

3. JSON Parsing and Sync Check:
   The script parses the JSON response using jq to extract the boolean inSync field from the .blockbook object.

4. Decision and Output:

   • If inSync is "true", the script outputs "blockbook is synced" and exits successfully (exit 0).

   • If not synced, it outputs "blockbook is still syncing" and exits with failure (exit 1).

Key Variables

Important Commands Used

• curl -sf
  Fetches the URL silently and fails if the HTTP status is not 2xx or 3xx. This ensures the script only proceeds if the endpoint is reachable and responsive.

• jq -r
  Parses JSON input and extracts raw strings without quotes, used here to get the value of .blockbook.inSync.

Usage

This script is intended to be executed periodically by orchestration or monitoring systems as a readiness probe.

./readiness.sh

• Exit codes:

  • 0 indicates the service is ready (blockbook is synced or readiness check disabled).

  • 1 indicates the service is not ready (blockbook syncing or unable to fetch status).

Implementation Details and Considerations

• Disable Readiness Probe:
  The presence of the /data/disable_readiness file provides an operational override to skip readiness checks, allowing manual control or integration with other system maintenance workflows.

• Dependency on curl and jq:
  The script depends on these two utilities being installed and accessible in the runtime environment.

• Local API Endpoint:
  The script only checks the local service on port 8001, which implies it is expected to run on the same host or container as the blockbook service.

• Exit Codes for Orchestrators:
  The exit codes are suitable for Kubernetes readiness probes, where 0 means ready and non-zero means not ready.

Interaction with Other System Components

• Blockbook Service:
  The script interacts directly with the blockbook API at http://localhost:8001/api/v2 to determine readiness.

• Orchestration Systems (e.g., Kubernetes):
  This script is typically invoked by container orchestration systems as a readiness probe command to decide whether the pod/container can receive traffic.

• Filesystem:
  Monitors the existence of /data/disable_readiness to control readiness behavior.

Example Scenario

A Kubernetes pod running blockbook might be configured with a readiness probe like:

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

The orchestrator will call this script repeatedly, routing traffic to the pod only when it exits with status `0`.

Mermaid Diagram: Flowchart of readiness.sh Workflow

flowchart TD
    Start(Start)
    CheckDisableFile{Does /data/disable_readiness exist?}
    OutputDisabled["Print: 'readiness probe disabled'"]
    ExitSuccess0[Exit 0]

    CurlRequest["curl -sf http://localhost:8001/api/v2"]
    CurlFail[Exit 1]

    ParseJSON["Parse JSON response with jq"]
    CheckInSync{Is .blockbook.inSync == 'true'?}

    OutputSynced["Print: 'blockbook is synced'"]
    ExitSuccess1[Exit 0]

    OutputSyncing["Print: 'blockbook is still syncing'"]
    ExitFail[Exit 1]

    Start --> CheckDisableFile
    CheckDisableFile -- Yes --> OutputDisabled --> ExitSuccess0
    CheckDisableFile -- No --> CurlRequest
    CurlRequest -- Fail --> CurlFail
    CurlRequest -- Success --> ParseJSON --> CheckInSync
    CheckInSync -- Yes --> OutputSynced --> ExitSuccess1
    CheckInSync -- No --> OutputSyncing --> ExitFail

Summary

The `readiness.sh` script is a simple yet crucial utility for ensuring that the blockbook service is fully synchronized before it is marked ready to handle requests. Its design leverages standard Linux command-line tools to provide a clear, reliable readiness check that integrates seamlessly with container orchestration platforms. The ability to disable the probe via a flag file adds operational flexibility, making it suitable for various deployment and maintenance scenarios.