Skip to main content

Reading tare doctor output

tare doctor inspects a self-hosted data plane and prints a single health verdict, a per-category checklist, and the findings behind them. This page explains what each section means and which findings are actionable. For the flag list, see the generated command reference.

Running it​

tare doctor /path/to/data-plane-credentials.json --verbose

The identity file is optional. Supplying it lets the command upload a diagnostic bundle to the management plane, which is what a support engagement needs; omitting it runs the same checks locally and prints the report only.

Two other invocations matter when reading output:

  • -o json emits the same report as a machine-readable envelope, which is what the Admin Console and the tare-doctor CronJob consume.
  • --only <check> runs one named check instead of the full pipeline. The checklist is suppressed in this mode, deliberately: categories that never ran would otherwise be printed as OK.

The shape of a report​

Sections appear in a fixed order. Sections with nothing to report are omitted.

CLUSTER HEALTH: DEGRADED
SUMMARY: 3 issues (0 errors, 1 warnings, 2 advisories)

CHECKLIST:
- Doctor access: OK
- Namespaces: OK
- CRDs: OK
...
- Routing: WARNING
- Pod health: OK

RESOURCES:
...

FEATURE CONFIGURATION:
...

WARNINGS:
- AIGatewayRoute tars-dataplane/route-openai: ...

ADVISORIES (informational; do not affect status):
- ...
SectionWhat it holds
CLUSTER HEALTHThe single roll-up verdict, described below
SUMMARYIssue counts by severity. The advisories count is present only when advisories were raised
CHECKLISTOne row per category, each carrying the worst severity found in it. Replaced by a single CHECK: line on an --only run
RESOURCESA kubectl-style inventory of what was found, with the status column each resource reports
FEATURE CONFIGURATIONWhich optional capabilities are configured, read from live cluster objects. It carries no verdict
CHECKS PERFORMEDThe full list of checks in the pipeline. Printed only with --verbose
ERRORS, WARNINGS, ADVISORIESThe findings themselves, grouped by severity

Status and severity​

The status line is derived from the finding counts, not judged separately:

StatusConditionMeaning
HEALTHYNo errors and no warningsNothing needs attention. Advisories may still be listed
DEGRADEDAt least one warning, no errorsThe data plane is serving, but something is inconsistent or incomplete
BROKENAt least one errorSomething the data plane needs is missing or rejected

Advisories are the third severity and behave differently from the other two. They are counted in SUMMARY, printed in their own section, and deliberately excluded from the roll-up, so a report can read HEALTHY while listing several. They flag things worth knowing rather than things to fix, and a dev cluster routinely raises them.

Exit codes​

Exit codeWhen
0HEALTHY, including a run that raised advisories only
1DEGRADED or BROKEN, that is, any error or any warning

Warnings exiting non-zero is intentional, and it is the behavior to design around when the report is consumed by automation. The tare-doctor CronJob and any CI gate wrapping the command will register a failure for a warning-level finding on an otherwise serving data plane. Advisories alone never do.

Checklist categories​

Each row rolls up every finding whose resource falls into that category. A row reads OK when nothing was found, which for a category whose resources are absent entirely means absence was not itself a problem.

CategoryCovers
Doctor accessWhether the doctor's own service account could read what it needed
Namespacestars-system and tars-dataplane presence and state
CRDsCustom resource definitions, their versions, and drift from the expected contract
ControllersThe controller Deployments
Helm releasesThe installed release and its revision
Management planeReachability of the management plane. Present only when the probe ran and found something
GatewayGatewayClass, Gateway, EnvoyProxy, and EnvoyPatchPolicy objects
Identity configThe Secrets and ConfigMaps carrying data plane identity and configuration
AI backendsAIServiceBackend objects, one per provider-model backend
BackendsThe underlying Backend objects those resolve to
Backend traffic policiesBackendTrafficPolicy objects
Backend security policiesBackendSecurityPolicy objects, which carry provider credential references
Backend TLS policiesBackendTLSPolicy objects
Client traffic policiesClientTrafficPolicy objects, including the connection buffer limit
HTTPRoute filtersHTTPRouteFilter objects
Reference grantsCross-namespace ReferenceGrant objects
RoutingAIGatewayRoute, HTTPRoute, and RouteDeployment objects, and whether they are accepted
Route consistencyWhether the route set agrees with what the management plane expects
MCP routesMCPRoute objects and their churn rate
Proxy healthThe tars-dataplane proxy workload
Pod healthPod-level state across both namespaces
Semantic routerThe optional SemanticRouter guardrail provider. Present only when it is deployed

Two further rows appear with --verbose only: EnvoyPatchPolicy existence and Envoy Tars image. Both can read UNAVAILABLE, which means the check could not determine an answer rather than that it failed.

Common findings​

Routing or AI backends empty on a fresh install​

A report showing no AIGatewayRoute objects, or routes naming a backend that does not exist, is most often a provider credential problem rather than a routing problem. A provider with no working credential produces no backend, and the routes that reference it cannot be accepted.

Check, in order:

  1. That the provider has a credential set and shows as active in the Admin Dashboard. Until it does, no model behind it is callable. See Add providers and models to projects.
  2. That the change has had time to land. Routes and the backends they point at are written as separate steps, so a snapshot taken between them looks like a permanent failure. See Configuration propagation.
  3. That the models are assigned to the project, not merely enabled in the organization catalog. Enabling alone does not make a model reachable.

Rotating the provider credential is a reliable way to force the backend and its route to be written, because it re-runs the step that creates both.

Identity config errors​

Findings against Secrets or ConfigMaps in tars-system usually point at the data plane credential rather than at a provider. The distinguishing symptom on the traffic side is a 503 with service_unavailable on every request, including requests with a valid client key. See Data plane credentials.

ArgoCD-managed clusters​

The doctor reads applications.argoproj.io to record deployment history for GitOps-driven rollouts, because ArgoCD applies charts without leaving the Helm release secrets the normal path reads.

That read is skipped silently on clusters where the ArgoCD CRD is not registered, so a plain Helm install needs no configuration. On a cluster that does run ArgoCD, the chart must be told about it:

argocd:
  enabled: true
  namespace: argocd

argocd.enabled governs only whether the Role and RoleBinding granting that read are rendered. It defaults to false because rendering them into a namespace that does not exist would fail the install. Left at false on a cluster that does run ArgoCD, the read is refused rather than skipped, and the deployment history in the Admin Console stays empty for ArgoCD-driven syncs.

Timeouts on a large data plane​

The check pipeline makes dozens of throttled list calls across two namespaces, and on a data plane of realistic size it runs well past the 30-second mark. The command's own default allows for this. A run cancelled by an externally imposed deadline reports no health at all rather than partial health, so a wrapper enforcing its own timeout should allow several minutes.