Run Pre-upgrade Health Checks and JSON Contract Reference

Overview

Before you start an F5OS upgrade, run the Platform Health Assessment Suite to detect platform issues that could cause the upgrade to fail or cause an extended outage. The suite checks for conditions such as degraded ETCD clusters, network connectivity problems, expired certificates, and memory leaks.

Before you begin

• You must be an authenticated administrator.
• You must run the checks from the active controller. Scripts do not run on the standby controller.
• The Health Engine must be available on the system.

Run all health checks

To run all registered health check scripts, use the following command:

h-engine run

The Engine dispatches all scripts in parallel, enforces timeouts, and aggregates results.

Run a specific health check

To run a single health check, specify the script ID:

h-engine run <ID>

You can also pass parameters to a script using the -p flag:

h-engine run <ID> -p key=value

For example, to run the ISO image status check with a specific component parameter:

h-engine run S00014 -p component=cc_iso

Understand the results

Each script produces structured JSON output.

Script JSON output contract

Every script returns structured JSON. The contract has two parts.

Part 1 — heuristic{} (descriptor)

{
  "heuristic": {
    "id": "C00101",
    "name": "ETCD Cluster Health",
    "description": "Checks ETCD member health and quorum",
    "path": "./controller/C00101_etcd_health.pyh",
    "tags": ["controller", "etcd", "health"]
  }
}

Part 2 — result{} (outcome and action recommendations)

{
  "result": {
    "runResult": "passed | failed | error | inconclusive",
    "startTime": "<ISO-8601>",
    "duration": 0.0,
    "iteration": 1,
    "results": [
      {
        "message": "<human-readable finding>",
        "severity": "info | notice | warning | error | critical",
        "value": "<raw value>",
        "data": { "<evidence-key>": "<evidence-value>" }
      }
    ],
    "actions": [
      {
        "action": "GENERATE_ALARM | CLEAR_ALARM | GENERATE_EVENT | RESTART_SERVICE",
        "severity": "critical",
        "data": { "alarm-id": "<id>", "service": "<name-if-restart>" }
      }
    ]
  }
}

Field descriptions

The key fields to review are:

runResult

Exactly one of the following values:

Treat error as unsafe until verified manually.

results[]

Individual findings produced by the script, each with a severity level ranging from info to critical. Each entry includes:

actions[]

Recommendations the Engine surfaces, such as raising or clearing alarms. The Engine does not perform these actions itself. Supported actions:

Review results in QKView

Script execution results are persisted in the Health Engine’s cache directory and included in QKView. You can use QKView to share results with F5 Support for further analysis.

Logging

Each script execution produces the following log entries in the Health Engine’s internal log:

• START: Records the script ID and execution context
• COMPLETE: Records the runResult, duration, and highest severity
• ERROR (if applicable): Records the error message when runResult is error

Log entries use structured JSON format. Scripts do not write directly to syslog.

Severity levels

Each check can produce results at the following severity levels: