EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/docs/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
mode: local Reference
Full chart values, script mechanics, and permissions for mode: local
This page is the complete reference for mode: local. For the shortest path to a first bundle, go to Local Mode in the Getting Started guide instead.
The router-diagnostics collect script
Collection for mode: local runs through a standalone script, available for macOS, Linux, and Windows.
Run the following command on macOS / Linux (requires kubectl):
1curl -sSLo collect.sh https://router.apollo.dev/router-diagnostics-collect/latest
2chmod +x collect.shWindows (run in PowerShell, requires kubectl):
1Invoke-WebRequest -Uri https://router.apollo.dev/router-diagnostics-collect-ps1/latest -OutFile collect.ps1This command provides a ./collect.sh (or .\collect.ps1 on Windows) script, which caches a pinned support-bundle binary locally — in ~/.router-diagnostics/bin on Unix, %USERPROFILE%\.router-diagnostics\bin on Windows, or the path in ROUTER_DIAGNOSTICS_CACHE_DIR — keyed by version so a version update downloads a fresh binary instead of using an outdated one. Apollo sets this version, the same way job mode's image tag does.
--namespace (Unix) / -Namespace (Windows) is a plain, required flag. It must match wherever you actually installed the chart: both the helm install --namespace value and the chart's own --set namespace=<router_namespace> value (typically the same namespace in practice). The script uses it directly for its kubectl calls and for support-bundle --load-cluster-specs --namespace, which is what discovers the rendered spec ConfigMap.
Chart values
Every one of these values applies regardless of which mode you run.
| Value | Required | Default | Applies to | Purpose |
|---|---|---|---|---|
namespace | Yes | — | Official chart, raw manifest / custom | Your router's namespace. Rendered into every collector that accepts it, including clusterResources.namespaces as a single-element list. Never rely on the kubectl context's default namespace; it isn't used. |
mode | Yes | — | Official chart, raw manifest / custom | Selects how collection runs: local runs on your own machine using your own kubectl credentials and job runs in-cluster as a Kubernetes Job using a ServiceAccount the chart creates. |
selector | Raw-manifest tier only | The official chart's app.kubernetes.io/name=router label | Raw manifests / custom | Pod label selector, for example, app=my-router. Also selects which pods the metrics collector scrapes, found each time collection runs. Set it on the official chart too if your router's app.kubernetes.io/name label isn't router, for example with router.nameOverride. For more information, see Collecting Metrics → Which pods get scraped. |
configMapName | Raw-manifest tier only | Label-based targeting, no name needed | Raw manifests / custom | Name of the ConfigMap holding your router's rendered config |
metricsPort | No | 9090 | Official chart, raw manifest / custom | Port your router's metrics endpoint is reachable on, if not 9090. For more information, go to Collecting Metrics. |
logs.maxAge | No | Unset—no age cap | Official chart, raw manifest / custom | Maps to the logs collector's limits.maxAge. How far back to reach, for example, 2h |
logs.maxLines | No | 10000 (troubleshoot.sh default) | Official chart, raw manifest / custom | Maps to limits.maxLines. Lines kept, newest per container |
Go to Local Mode / Job Mode to determine what each mode needs beyond this shared set.
Kubernetes RBAC
Installing the chart requires permission to create a ConfigMap in the target namespace, which is the same level of access needed to install the router itself.
Run ./collect.sh (or .\collect.ps1) to use your own existing kubectl credentials. This step creates no additional ServiceAccount. To reach the metrics collector, you also need create on the pods/portforward subresource in the router's namespace. For more information, see Collecting Metrics. Declining this doesn't fail collection: no metrics are collected, and each pod's line in the bundle includes the port-forward error from kubectl.
Container memory and CPU usage come from the kubelet through the API server's proxy, using your own credentials, because your machine can't reach node addresses directly. Ensure your user has these grants:
nodes(list)nodes/proxy(get)
nodes/proxy is a broad grant: Kubernetes' own RBAC good-practices documentation states it "provides access to privileged kubelet APIs that can retrieve container logs or execute and attach to pod processes... bypasses audit logging and admission control," and is explicitly "not a read-only permission." What this tool does with it is read-only, but the grant itself authorizes more than that one use, and it can't be scoped to only the router's nodes. node-metrics/<node-name>.json lists every pod on every node in the cluster, not only the router's.
If you don't have these grants, collection still completes, but there is no node-metrics/ directory. What the bundle records depends on which grant is missing:
A request to a node fails, for example because
nodes/proxyis missing:execution-data/summary.txtmarksnode-metricsas failed, andcollector-errors/node-metrics-error.jsonnames the endpoint that failed.nodes(list) is missing: the collector reports success with no output, and the bundle has no record of it.
Check your grants with kubectl auth can-i get nodes/proxy and kubectl auth can-i list nodes.
pods/exec isn't required: nothing this tool does runs inside your router container.
clusterResources also attempts several cluster-scoped resource types beyond what's listed above (nodes, storage classes, CustomResourceDefinitions, webhook configurations, and more). A <resource>-errors.json file lands alongside its corresponding <resource>.json containing the Kubernetes API error.
cluster-resources/auth-cani-list/ is troubleshoot.sh's own self-reported record of every verb/resource/apiGroup combination the collecting identity had at collection time.
Cluster footprint
Installation leaves behind the spec ConfigMap and Helm release metadata. To collect again, run ./collect.sh --namespace <namespace> (or .\collect.ps1 -Namespace <namespace> on Windows). You don't need to reinstall. If you'd rather leave nothing behind, uninstall the release:
1helm uninstall router-diagnostics --namespace <namespace>Bundle output shape
Extracting support-bundle-<timestamp>.tar.gz yields one top-level directory. version.yaml, analysis.json, cluster-info/, and execution-data/summary.txt always land in it, written unconditionally by the engine itself regardless of what the spec declares; meta.json is ours. execution-data/summary.txt is worth a look if something seems off — it's a human-readable per-collector success/failure/timing report.
Worked example, for a mode: local collection against production:
1support-bundle-2026-08-11T14_23_00/
2├── version.yaml
3├── analysis.json
4├── meta.json
5├── cluster-info/
6│ └── cluster_version.json
7├── execution-data/
8│ └── summary.txt
9├── host-collectors/
10│ └── run-host/
11│ ├── router-metrics-info.json # fully masked — see Collecting Metrics
12│ ├── router-metrics.txt # the collector's own output, including why any metrics are missing
13│ ├── router-metrics-stderr.txt # the script's stderr, only present if the script writes to stderr
14│ └── router-metrics/
15│ └── pods/
16│ ├── <pod-name>.txt
17│ └── <pod-2-name>.txt
18├── router-logs/
19│ └── <router-pod-name>/
20│ └── router.log -> ../../cluster-resources/pods/logs/production/<router-pod-name>/router.log
21├── cluster-resources/
22│ ├── pods/
23│ │ ├── production.json
24│ │ └── logs/production/<router-pod-name>/router.log # the real file behind the symlink above
25│ ├── configmaps/production.json
26│ ├── events/production.json
27│ ├── nodes.json
28│ └── ...
29├── node-metrics/
30│ └── <node-name>.json
31└── configmaps/
32 └── production/
33 └── <configmap-name>.jsonhost-collectors/run-host/router-metrics/pods/— one<pod-name>.txtper router pod matchingselectorthat responded, written by therouter-metricshost collector's script. This nested path (not a top-levelrouter-metrics/) is how troubleshoot.sh lays out ahostCollectors.runcollector's output, andmode: jobbundles use the same path. See Collecting Metrics for the mechanics.host-collectors/run-host/router-metrics-stderr.txt— the metrics collector's stderr, such as the errorkubectlreturned when it couldn't list pods. It is only present if the script writes to stderr. See Collecting Metrics → If metrics are missing.host-collectors/run-host/router-metrics-info.json— a diagnostic sidecar troubleshoot.sh writes for everyhostCollectors.runcollector. Its contents are fully masked. For more details, see Collecting Metrics.host-collectors/run-host/router-metrics.txt— the collector's own output, separate from the per-pod files underpods/. It has one line for each pod that couldn't be scraped, or for why no pod could be. See Collecting Metrics → If metrics are missing for what each line means.If more than one ConfigMap in your namespace matches,
configmaps/production/becomes multiple files, one per ConfigMap, named after that ConfigMap's own Kubernetes name:Text1configmaps/ 2└── production/ 3 ├── <configmap-1-name>.json 4 └── <configmap-2-name>.jsonnode-metrics/<node-name>.json— one file for every node in the cluster, not only the nodes that run router pods.nodeMetricsignores yourselectorandnamespaceso each file lists every pod on that node. The files contain pod names, namespaces, and container CPU and memory usage, but no logs, configuration, or secrets.cluster-resources/configmaps/production.jsonisclusterResources's full, unfiltered sweep of every ConfigMap in the namespace.configmaps/production/<configmap-name>.jsonis the dedicatedconfigMapcollector's own output.
keyExists: false in configmaps/<namespace>/<configmap-name>.json doesn't mean the config is missing. This is a troubleshoot.sh quirk: the configMap collector's keyExists field is only ever set true when the collector is configured with a specific key to look for. Our spec uses includeAllData: true with no key set, so keyExists is always false in this output, regardless of whether the config was actually captured. Check for the config data in that same file, rather than reading keyExists as a success/failure signal.