probe.sh

Overview

`probe.sh` is a minimalistic shell script designed primarily for use as a Kubernetes probe script within containerized blockchain node deployments. Its core purpose is to keep a container alive indefinitely without performing any active health checks or complex logic. This script acts as a placeholder or baseline liveness/readiness probe, ensuring Kubernetes perceives the pod as healthy and running.

The script achieves this by tailing `/dev/null` indefinitely, effectively blocking the container’s main process from exiting until it receives termination signals. It also handles common termination signals gracefully, allowing Kubernetes to stop the container cleanly during pod shutdown or redeployment.

Script Breakdown and Functionality

Script Content

#!/bin/sh

set -e

trap 'exit' SIGTERM SIGINT

tail -f /dev/null &

wait $!

Explanation of Each Part

Line	Code	Description
1	`#!/bin/sh`	Shebang specifying the script should be executed with `sh` shell interpreter.
3	`set -e`	Enables immediate exit if any command returns a non-zero status, ensuring failure is not ignored.
5	`trap 'exit' SIGTERM SIGINT`	Sets up signal handlers to catch `SIGTERM` and `SIGINT` signals and exit the script cleanly.
7	`tail -f /dev/null &`	Launches a background process that tails an empty stream indefinitely, keeping the script alive.
9	`wait $!`	Waits for the background tail process to finish, which only happens on termination signals.

Detailed Explanation

Signal Handling:
The script traps SIGTERM and SIGINT signals, which are standard termination signals sent by Kubernetes during pod shutdown or when a user interrupts the process. Upon receiving these signals, the script exits gracefully, allowing Kubernetes to safely stop the container.
Indefinite Wait:
tail -f /dev/null is a common Unix idiom for an infinite blocking command that does not consume CPU cycles. The script backgrounds this process and then waits on it. This approach prevents the container from exiting and keeps the main process alive, fulfilling Kubernetes’ requirement for a running process.
Fail-Fast Behavior:
set -e ensures the script exits immediately if any command fails unexpectedly, preventing silent failures.

Usage Example

This script is typically deployed as the container's entrypoint or as a probe command in Kubernetes Pod specifications.

Example Kubernetes Pod Spec Snippet

containers:
  - name: blockchain-node
    image: blockchain/node:latest
    readinessProbe:
      exec:
        command: ["/bin/sh", "/path/to/probe.sh"]
      initialDelaySeconds: 5
      periodSeconds: 10
    livenessProbe:
      exec:
        command: ["/bin/sh", "/path/to/probe.sh"]
      initialDelaySeconds: 15
      periodSeconds: 20

In this configuration:

The probe script runs periodically.
Since probe.sh never exits unless terminated, Kubernetes sees the container as alive.
The script’s signal handling allows Kubernetes to stop the container cleanly.

Important Implementation Details

Minimal Dependencies: Uses only POSIX-compliant shell commands (sh, tail), ensuring compatibility across most Linux base images.
Signal Awareness: Proper shutdown handling prevents Kubernetes from forcefully killing the container, aiding graceful pod termination.
No Active Health Checks: This script does not verify any application-specific status (e.g., blockchain node health). It is a placeholder or baseline probe.
Use Case Context: Typically used when no meaningful liveness/readiness checks are possible or desired, or when other specialized probe scripts are not yet implemented.

Interaction with Other System Components

Kubernetes:
This script is intended to be invoked by Kubernetes as a liveness or readiness probe. It ensures the container stays running by blocking indefinitely. Kubernetes uses the exit status of the script to determine pod health. Since the script only exits on termination signals, Kubernetes sees the pod as healthy as long as the container is running.
Container Lifecycle:
By handling termination signals (SIGTERM, SIGINT), the script cooperates with Kubernetes pod lifecycle events (e.g., pod deletion, scaling down) for clean shutdowns.
Other Infrastructure Scripts:
Compared to more complex probe scripts in this project (which might check blockchain node sync status, API responsiveness, or indexer health), probe.sh serves as a minimal fallback or default probe. It is often bundled alongside other scripts but performs no active checks itself.

Mermaid Flowchart: Workflow of `probe.sh`

flowchart TD
    Start[Container Starts] --> SetSignalTrap[Set trap for SIGTERM and SIGINT]
    SetSignalTrap --> StartTail[Tail /dev/null indefinitely in background]
    StartTail --> Wait[Wait for tail process to terminate]
    Wait -->|Receive SIGTERM or SIGINT| Exit[Exit Script]

Summary

`probe.sh` is a simple, robust shell script used as a Kubernetes probe to keep a container alive by tailing an empty file indefinitely. It handles termination signals gracefully, allowing Kubernetes to manage pod lifecycle events cleanly. While it does not perform any active health checking, it provides a reliable baseline probe useful in scenarios where more complex checks are unnecessary or unavailable.

Appendix: Related Scripts and Context

More advanced probe scripts in this project implement specific blockchain node health checks.
The probe.sh script complements these by serving as a simple "keep-alive" mechanism.
Used extensively in Kubernetes StatefulSets and DaemonSets managing blockchain nodes.
Part of a set of infrastructure scripts facilitating container lifecycle and health management.