Skip to content

Diagnostics & Support

PteroCloud ships a read-only diagnostics and support system. It lets an operator gather evidence and act on it without exposing a secret or mutating infrastructure by accident.

Diagnostics Center

Support Center

Diagnostics

Diagnostics are organised as independent checks grouped by scope. A check is read-only, has a stable id, declares its scope and may declare dependencies.

Scopes

CONTROL_PLANE, PROVIDER, HYPERVISOR, INSTANCE, NETWORK, IPAM, STORAGE, IMAGE, CONSOLE, BACKUP, MIGRATION, HA, SCHEDULER, TASK, SECURITY, COMPATIBILITY, LICENSE and FULL. FULL expands to every scope.

Statuses

Status Meaning
PASS Healthy.
WARN Degraded or risky, but not blocking.
FAIL Broken; dependents are skipped.
SKIPPED Not evaluated because a dependency failed, or the run was cancelled.
UNKNOWN The check could not be evaluated (timeout or internal error).

Dependency semantics

If a check a check depends on FAILs, the dependent is SKIPPED and carries the root error code. This prevents a single root cause from producing a cascade of failures. Example: a broken queue makes the scheduler check SKIPPED with QUEUE_FAILED.

Timeouts, cancellation and caching

  • Each check has a per-check wall-clock timeout. A timed-out check becomes UNKNOWN with DIAGNOSTIC_CHECK_TIMEOUT.
  • A run can be cancelled between checks; remaining checks are SKIPPED with DIAGNOSTIC_CANCELLED.
  • Provider-touching work is cached with a short TTL; Run Again forces a refresh.

What diagnostics never do

  • No remote shell, no run_command, no arbitrary file read.
  • No port scanner and no SSRF: only configured provider endpoints are contacted, and only when a single provider is explicitly targeted.
  • No VM start/stop and no provider mutation.

Running

php artisan pterocloud:diagnostics --scope=control_plane
php artisan pterocloud:diagnostics --scope=provider --provider=<uuid>
php artisan pterocloud:diagnostics --scope=instance --instance=<uuid> --json

Support bundles

A support bundle is a redacted, self-contained archive of the evidence an engineer needs.

  • Always redacted. There is no unredacted mode.
  • A final secret scan of the written archive is fail-closed: if any secret survives, generation fails and the bundle is deleted.
  • Nothing is ever uploaded to Krapple automatically.
php artisan pterocloud:support:bundle
php artisan pterocloud:support:bundle:list
php artisan pterocloud:support:verify-bundle <path>

The compatibility section is included in the bundle. The license key is never in a bundle.

Repairs

Repairs are predefined, audited semantic actions. There is no shell, no arbitrary command, no arbitrary file read and no port scanner. Repairs default to a dry run; dangerous repairs require permission and a strong confirmation, and every executed repair is audited. See Repair.

Error lookup

Every customer-facing error carries an opaque support id (PC-YYYYMMDD-XXXXXX) that maps to a redacted event.

php artisan pterocloud:error PC-PVE-003
php artisan pterocloud:error:id PC-20260101-ABCDEF
php artisan pterocloud:errors:list

Compatibility page

Compatibility