Skip to content

USAGE.md

Latest commit

 

History

History
375 lines (277 loc) · 8.86 KB

USAGE.md

File metadata and controls

375 lines (277 loc) · 8.86 KB
Raw

Usage Guide — abc-node-probe

This guide shows common workflows and real-world examples for running abc-node-probe.

Quick Start

1. Run locally with default settings

./abc-node-probe --jurisdiction=ZA

Output includes a colored table of all checks and a JSON report.

2. Run with JSON-only output (for parsing)

./abc-node-probe --jurisdiction=ZA --json | jq '.summary'

Output: only JSON (no table), suitable for piping to tools like jq.

3. Run quietly, exit on first failure

./abc-node-probe --jurisdiction=ZA --fail-fast --json

Stops immediately on first FAIL or WARN severity check.

Installation

From Latest Release

The abc-cluster-cli will automatically download the latest abc-node-probe release:

# When running via the CLI
abc compute probe node-01

# The CLI fetches latest release from GitHub and caches it locally at:
# ~/.cache/abc-cli/releases/<version>/abc-node-probe-<os>-<arch>

Manual Installation

Download the latest release binary for your platform from GitHub Releases:

# Example: macOS arm64
wget https://github.com/abc-cluster/abc-node-probe/releases/download/v0.1.0/abc-node-probe-darwin-arm64
chmod +x abc-node-probe-darwin-arm64
./abc-node-probe-darwin-arm64 --version
# → abc-node-probe v0.1.0 (built 2026-04-14T06:58:34Z, commit 508b608)

Verify Static Binary

# Confirm the binary is fully static (no dynamic dependencies)
file abc-node-probe-linux-amd64
# → ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, ...

ldd abc-node-probe-linux-amd64
# → not a dynamic executable

Common Workflows

Scenario 1: Pre-flight check before adding a node to the cluster

# Basic check with jurisdiction
./abc-node-probe --jurisdiction=ZA

# If output shows "NODE ELIGIBLE TO JOIN: YES", proceed with cluster join
# Otherwise, check the FAIL and WARN severities in the report

Scenario 2: Batch test multiple nodes using Nomad

The abc compute probe CLI command automates this:

# Test a single node
abc compute probe worker-01 --jurisdiction=ZA

# Shows:
#   ✓ Probe dispatched
#   Node           worker-01 (abc1234...)
#   Nomad job ID   abc-node-probe-system/abc-node-1234-5678
#   Evaluation ID  eval-9876-5432-1234
#   Probe version  v1.0.0
#   
#   Streaming probe output...
#   [... JSON output ...]

Scenario 3: Test without compliance checks (faster)

Useful when compliance jurisdictional data is not relevant:

./abc-node-probe --jurisdiction=US --skip-categories=compliance,smart

# Skips:
# - compliance checks (jurisdiction, LUKS, cross-border mounts)
# - smart checks (S.M.A.R.T. disk health — Linux only, requires root)
#
# Runs only: hardware, storage, network, os, security checks (~10s instead of ~60s)

Scenario 4: Test network performance (speedtest)

Network checks include a speedtest that measures actual throughput:

./abc-node-probe --jurisdiction=ZA --skip-categories=smart,compliance

# Output includes:
# network  network.speedtest.throughput  INFO   325.4 Mbps  Download: 325.4 Mbps, Upload: 87.3 Mbps, ...
#
# Full metadata in JSON:
# {
#   "id": "network.speedtest.throughput",
#   "value": "325.4 Mbps",
#   "metadata": {
#     "download_mbps": "325.4",
#     "upload_mbps": "87.3",
#     "latency_ms": "12.5",
#     "server": "ZA-JNB-1",
#     ...
#   }
# }

Scenario 5: Write report to file for archival

./abc-node-probe --jurisdiction=ZA --mode=file --output-file=/var/log/probe-report.json

# Creates /var/log/probe-report.json with the full JSON report
# Useful for auditing, compliance records, or post-analysis

Scenario 6: Send results to control plane API

Requires API token and control plane endpoint:

./abc-node-probe \
  --jurisdiction=ZA \
  --mode=send \
  --api-endpoint=https://control-plane.example.com \
  --api-token=bearer_token_here

# On success (HTTP 200/201), stdout shows:
# SUMMARY: ... NODE ELIGIBLE TO JOIN: YES
# ✓ Results sent to API

# On failure, error message indicates the issue

Or use environment variables:

export ABC_PROBE_API="https://control-plane.example.com"
export ABC_PROBE_TOKEN="bearer_token_here"
export ABC_PROBE_JURISDICTION="ZA"

./abc-node-probe --mode=send

Scenario 7: Nomad integration (system batch job)

When running via the CLI's abc compute probe command, the job is automatically configured:

# This HCL is generated by the CLI internally:
job "abc-node-probe-system" {
  type        = "sysbatch"
  datacenters = ["dc1"]

  parameterized {
    payload       = "forbidden"
    meta_optional = ["jurisdiction", "skip_categories", "json_only"]
  }

  group "probe" {
    constraint {
      attribute = "${node.unique.id}"
      operator  = "="
      value     = "abc1234..."  # Target node ID
    }

    restart {
      attempts = 0
      mode     = "fail"
    }

    task "probe" {
      driver = "raw_exec"

      config {
        command = "${path to downloaded abc-node-probe}"
        args = [
          "--nomad-mode",
          "--mode=stdout",
          "--jurisdiction=ZA"
        ]
      }

      resources {
        cpu    = 500
        memory = 512
      }
    }
  }
}

Key behavior:

  • Runs in --nomad-mode → always exits 0 (clean job completion)
  • Results in JSON output → view with nomad alloc logs <alloc-id> probe
  • summary.eligible_to_join field indicates actual node readiness

Scenario 8: One-liner for CI/CD pipelines

Check node readiness in a bash script:

#!/bin/bash
set -euo pipefail

JURISDICTION="${1:-ZA}"
ELIGIBLE=$(./abc-node-probe --jurisdiction="$JURISDICTION" --json | \
  jq -r '.summary.eligible_to_join')

if [[ "$ELIGIBLE" == "true" ]]; then
  echo "✓ Node is eligible to join"
  exit 0
else
  echo "✗ Node is not eligible to join"
  # Print failures for debugging
  ./abc-node-probe --jurisdiction="$JURISDICTION" --json | \
    jq '.results[] | select(.severity == "FAIL")'
  exit 1
fi

Usage:

./check-node-eligibility.sh ZA
# → ✓ Node is eligible to join

Scenario 9: Verbose output for debugging

# Show all checks including SKIP and INFO severities
./abc-node-probe --jurisdiction=ZA --json | jq '.results[]'

# Filter to warnings only
./abc-node-probe --jurisdiction=ZA --json | jq '.results[] | select(.severity == "WARN")'

# Count checks by severity
./abc-node-probe --jurisdiction=ZA --json | \
  jq '.results | group_by(.severity) | map({severity: .[0].severity, count: length})'

Output example:

[
  { "severity": "PASS", "count": 22 },
  { "severity": "WARN", "count": 3 },
  { "severity": "SKIP", "count": 2 }
]

Environment Variables

Variable Example Notes
ABC_PROBE_TOKEN abc_token_xyz Bearer token for API requests
ABC_PROBE_API https://api.example.com Control plane API endpoint
ABC_PROBE_JURISDICTION ZA ISO 3166-1 alpha-2 country code
ABC_MINIO_ENDPOINT minio.local:9000 MinIO endpoint; skipped if unset

Example:

export ABC_PROBE_JURISDICTION="ZA"
export ABC_PROBE_API="https://control-plane.example.com"
export ABC_PROBE_TOKEN="$(cat /var/secrets/probe-token)"

./abc-node-probe --mode=send

Exit Codes

Code Meaning
0 All checks PASS or SKIP; OR --nomad-mode is enabled
1 At least one WARN, zero FAIL (when not in --nomad-mode)
2 At least one FAIL (when not in --nomad-mode)
3 Tool execution error (bad flags, invalid jurisdiction, API unreachable)

Example: Use exit code for conditional logic:

./abc-node-probe --jurisdiction=ZA --fail-fast
case $? in
  0) echo "Ready to join cluster" ;;
  1) echo "Warnings detected, review before joining" ;;
  2) echo "Failures detected, node not ready" ;;
  3) echo "Tool error, check configuration" ;;
esac

Reporting Issues

When opening a bug report, include:

  1. Probe version:

    ./abc-node-probe --version
# → abc-node-probe v1.0.0 (built 2026-04-14T06:58:34Z, commit 508b608)

  2. Full JSON report:

    ./abc-node-probe --jurisdiction=ZA --json > report.json
# Include report.json in the issue

  3. Node information:

    uname -a
cat /etc/*-release | head -5

Performance Notes

  • Duration: Typically 10–60 seconds depending on checks and network

    • smart checks: +10–30s (S.M.A.R.T. I/O)
    • network.speedtest: +30–60s (actual speed test to speedtest.net)
    • Others: <1s each

  • Memory usage: <10 MB

  • Disk I/O: Minimal (reads only, no writes unless --mode=file)

  • Network:

    • API query with --mode=send: ~100 KB
    • Speedtest traffic: varies, typically 10–100 MB depending on speed

See Also