Validating Deployments

Fuzzball ships tiered readiness checks that validate a deployed, running cluster and print a sectioned report. Checks are grouped into the deployment checklist’s sections (Deployment, Operator Lifecycle, Node Provisioning, Workflows, and so on). In the terminal report each line is marked ✓ (pass), ! (warning), ✗ (failure), or - (skipped); the machine-readable report (-o json/-o yaml) carries the same outcomes as the literal status values PASS, FAIL, WARN, and SKIP.

Two commands run the checks:

• fuzzball context validate validates the cluster the active context points at — anywhere a context works, this works.
• fuzzball cluster <aws|gcp|azure|oci> validate runs the same checks plus the operator-level Kubernetes checks against a cloud deployment, deriving cluster credentials from your cloud session — no kubeconfig needed.

Both authenticate the Fuzzball API checks through the active fuzzball context, so log in to the target cluster first with fuzzball context login.

Checks are organized in three tiers of increasing depth; each tier includes everything in the tiers below it.

The read-only health tier is the default, but most installation problems only surface when a real workload runs — a cluster can pass every health check and still be unable to execute a single job. Run the functional tier before trusting a deployment:

$ fuzzball context validate --tier functional

The per-provider subcommands discover the deployment (or prompt to select one), connect to its Kubernetes cluster with credentials derived from your cloud session, and include the operator-level checks (operator deployment, FuzzballOrchestrate custom resource, service pods):

$ fuzzball cluster aws validate --stack-name my-fuzzball
$ fuzzball cluster gcp validate --deployment-name my-fuzzball
$ fuzzball cluster azure validate --resource-group my-fuzzball
$ fuzzball cluster oci validate --deployment-name my-fuzzball

Provider notes:

• OCI: OKE tokens are minted via oci ce cluster generate-token, so the OCI CLI must be on PATH.
• Azure: on AAD-only AKS clusters the returned credentials use kubelogin, which must then be on PATH.

Each run also verifies the active context actually points at the deployment being validated (the context-deployment-match check warns on a mismatch — validating cluster A’s API while inspecting cluster B’s operator is a confusing way to spend an afternoon).

For deployments not managed by the cloud subcommands (on-prem, kind, docker-compose), fuzzball context validate accepts an explicit kubeconfig to enable the Kubernetes-level checks:

$ fuzzball context validate --kubeconfig ./target-cluster.kubeconfig

The standard loading rules (KUBECONFIG, ~/.kube/config) are deliberately not consulted: they select whatever cluster your current kubectl context happens to point at, which is usually not the deployment under validation. Without --kubeconfig the Kubernetes checks are skipped — not failed.

Use the global --insecure flag against deployments with staging-issuer TLS certificates so the API-reachability and gRPC checks can connect. The TLS certificate check then reports a warning rather than a pass — with verification disabled it can still inspect expiry dates, but it cannot vouch for the issuer.

The overall run is bounded by --timeout (default 10 minutes). A run cut short by the timeout or an interrupt reports the remaining checks as skipped, marks the report interrupted, and exits with code 2 — a partial run is never presented as a completed assessment. Secrets and volumes created by the functional and full tiers are deleted, and their workflows stopped, on every exit path including interrupts; anything that could not be cleaned up is listed on standard error.

Run a single section or an individual check. Section names are exact and are listed in fuzzball context validate --help:

$ fuzzball context validate --section "Deployment with fuzzball cluster"

$ fuzzball context validate --check live/api/endpoint

A filter that matches no checks is an error (exit code 2), so a mistyped or renamed check ID cannot silently pass in CI.

-o json (or -o yaml) writes the full report document to standard output with nothing else — progress rendering is suppressed and errors go to standard error — so it can be piped directly to tools like jq:

$ fuzzball context validate -o json | jq .summary

The report schema is versioned via its schemaVersion field. Each check carries the tier it belongs to.

Optional checks report WARN instead of FAIL and never affect the exit code.