readiness.sh

Overview

`readiness.sh` is a lightweight shell script designed as a Kubernetes readiness probe to determine whether a service (specifically, a Blockbook API) is ready to accept traffic. The script performs a health check by querying the local Blockbook API and evaluating its synchronization status. It also supports a manual override to disable the readiness check if required.

This script is typically invoked periodically by Kubernetes or other orchestration tools to decide if the associated pod/container should receive network traffic.

Detailed Explanation

Purpose

• To verify if the Blockbook service is fully synchronized (inSync).

• To allow a manual override that disables the readiness probe.

• To return appropriate exit codes that Kubernetes uses to determine pod readiness.

Script Flow and Logic

1. Manual Disable Check
   The script first checks for the presence of the file /data/disable_readiness. If this file exists, the readiness probe is considered disabled, and the script exits successfully (exit code 0).

2. Query Blockbook API
   The script performs an HTTP GET request (curl) to the local Blockbook API endpoint http://localhost:8001/api/v2. If this request fails (non-success HTTP status or no response), the script exits with failure (exit code 1).

3. Parse API Response
   It uses jq to extract the .blockbook.inSync field from the JSON response. This boolean indicates whether the blockchain data is fully synchronized.

4. Determine Readiness

   • If .blockbook.inSync is "true", the script prints "blockbook is synced" and exits with success (0).

   • Otherwise, it prints "blockbook is still syncing" and exits with failure (1).

Exit Codes

• 0: Service is ready (synced) or readiness probe is disabled.

• 1: Service is not ready or API is unreachable.

Key Variables and Commands

Usage Example

The script itself is designed to be called by the Kubernetes readiness probe configuration:

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

Manually, a user could run:

./readiness.sh

Possible outputs:

• readiness probe disabled (exit 0, if /data/disable_readiness exists)

• blockbook is synced (exit 0, when fully synced)

• blockbook is still syncing (exit 1, when syncing or API unreachable)

Important Implementation Details

• Manual override via file presence: By simply creating or deleting the file /data/disable_readiness, operators can enable or disable the readiness probe without changing the deployment or restarting the container.

• Silent and robust API check: curl -sf ensures no output on failure, allowing clean conditional logic.

• JSON parsing via jq: The script requires jq installed in the container to parse JSON responses reliably.

• Exit status drives Kubernetes readiness: The script's exit code is critical, as Kubernetes considers exit code 0 as ready and any non-zero as not ready.

Interaction with Other System Components

• Blockbook API: The script depends on the Blockbook API running locally on port 8001. Blockbook is a blockchain indexer providing data through REST endpoints.

• Kubernetes: This script is used as a readiness probe command, helping Kubernetes decide pod readiness based on Blockbook sync status.

• Container runtime: The script runs inside the container hosting the Blockbook service.

• File system: It reads the /data/disable_readiness file to disable readiness checks dynamically.

Mermaid Diagram

flowchart TD
    A[Start readiness.sh] --> B{Check /data/disable_readiness file}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Run curl to http://localhost:8001/api/v2]
    E -- Fail --> F[Exit 1]
    E -- Success --> G[Parse JSON field .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 concise, reliable readiness probe script for Kubernetes environments running Blockbook. It smartly combines a manual override mechanism with a live sync check against the Blockbook API. The script’s exit codes drive Kubernetes load balancing and pod lifecycle decisions, ensuring traffic is only routed to fully ready and synced instances.

Requirements

• curl command-line tool.

• jq JSON processor.

• Access to the Blockbook API on localhost port 8001.

• Write permissions to /data for manual readiness override file.

Potential Enhancements

• Add retries or backoff for transient API failures.

• Provide more detailed logging or metrics.

• Support configurable API endpoint via environment variables.

• Extend to check additional health indicators beyond just sync status.

This documentation provides a comprehensive understanding of the `readiness.sh` script, its role, and its practical usage within the system architecture.