User guide
Documentation home · Administrator guide
Open the map
Open the URL supplied by your administrator in a browser with JavaScript enabled. For a local installation, the default address is http://localhost:8080. Complete any sign-in required by your organization's access gateway.
The application loads the namespace list and then a graph for *All* namespaces. You do not need a local kubeconfig to use the browser UI: the backend connects to Kubernetes using the credentials configured by the administrator.
The browser also loads graph libraries from unpkg.com. If the page opens but
the graph and controls do not work, check whether your browser or network blocks
that host.
Use the controls
| Control | What it does |
|---|---|
| Namespace | Requests a fresh graph for the selected namespace. *All* requests resources across the cluster. |
| Resource names in the Legend | Click a resource kind to hide or show its nodes and their connected edges. A faded entry means that kind is hidden. All Service variants share the Service toggle. |
| Refresh | Fetches current graph data for the selected namespace. |
| Hover over a node | Shows available details and highlights its connected edges in red. The red highlight indicates focus, not a failure. |
| Mouse wheel or trackpad zoom; drag the graph background | Zooms or pans around the map. |
The node/edge count reflects the graph after the legend filters are applied. Legend changes redraw the graph from the last fetched data; they do not query Kubernetes. Hidden kinds remain hidden across refreshes and namespace changes until you show them again or reload the page. Redrawing fits the graph to the panel and resets its layout.
The footer shows the latest request status and the time of the last successful graph refresh, using your browser's local time. There is no automatic polling: click Refresh after a cluster change. Reload the page to refresh the namespace dropdown, which is populated only when the page opens.
If a graph request fails, an older graph can remain visible. Check the footer before treating the displayed map as current; after a failed namespace change, that graph can still belong to the previous namespace.
Read nodes and arrows
Each node is labeled with its resource kind, name, and namespace. Arrows point from the source resource to the related resource.
| Node | Meaning and available hover details |
|---|---|
| Ingress | HTTP entry point; the tooltip includes rule hosts when present. |
| Service | A Kubernetes Service; the tooltip includes its Service type and selector. |
| Headless Service | A Service whose clusterIP is the string None. |
| External Service | A Service with spec.externalIPs, unless classified as headless. This label does not represent every externally reachable Service. |
| Deployment, StatefulSet, DaemonSet | Workload controller; the tooltip includes container images from the Pod template. |
| Pod | Pod phase, a simplified readiness indicator, and CrashLoopBackOff when detected. |
| OrbitDeployment | An Orbit Deploy custom resource; arrows show supported objects listed in its management status. |
| Arrow | Color | Meaning |
|---|---|---|
| Data flow | Gray | Ingress backend to Service, or Service selector to matching Pod. |
| Owner/create | Blue | Deployment, StatefulSet, or DaemonSet to its Pod, using owner references. Deployment relationships follow the intermediate ReplicaSet. |
| Manages | Purple | OrbitDeployment to an object named in status.managedObjects that is present in the graph. |
For example, follow Ingress → Service → Pod to inspect a possible request path,
then look for the blue arrow pointing to the Pod to identify its workload.
Pod and Service indicators
- A Pod with any regular container reporting ready has a green border. This does not mean every container is ready or that the Pod's Kubernetes Ready condition is true.
- A Pod with a regular container waiting in
CrashLoopBackOffhas a pale red background and a tooltip warning. If another container is ready, the border can still be green. - A Service with a non-empty selector that matches no Pods is marked orphaned; the UI defines a dashed border for this flag. A Service with no selector is not flagged this way.
Use these indicators to decide what to inspect next. They do not replace Pod events, logs, readiness conditions, or endpoint checks.
Work through common questions
Which Pods are behind a Service?
- Select the Service's namespace and ensure Service and Pod are visible in the legend.
- Find the Service and hover over it to highlight its arrows.
- Follow gray arrows to Pods and compare the Service selector with the Pod labels using your normal Kubernetes tools if the result is unexpected.
Links are based on label matching within the same namespace. The graph does not read Endpoints or EndpointSlices, test connectivity, or exclude unready Pods.
Which workload created a Pod?
Show Deployment, StatefulSet, DaemonSet, and Pod in the legend, then follow the blue arrow into the Pod. ReplicaSets are used internally to resolve Deployment ownership but are not displayed as nodes. Jobs, CronJobs, and other controllers are not displayed, so some Pods have no visible owner arrow.
Which resources does an OrbitDeployment manage?
Show OrbitDeployment in the legend and follow its purple arrows. In a namespace
view, the map includes OrbitDeployments from that namespace and those in
kube-system whose managed-object status references the selected namespace.
It does not search all other namespaces for managers.
An OrbitDeployment can appear with no arrows if its status is empty or its managed resources are outside the selected graph or supported kinds. The application does not install Orbit Deploy itself.
Understand the limits
- The graph is assembled from separate API list calls on each refresh. It is not an atomic snapshot, traffic measurement, or connectivity test.
- Service edges do not establish endpoint health, port compatibility, DNS resolution, or NetworkPolicy behavior. Services without selectors have no selector-based Pod arrows.
- Ingress edges cover default and HTTP path backends that name Services in the same namespace. Resource backends and missing Services have no arrows.
- Only the resource kinds listed above are shown. ConfigMaps, Secrets, storage, nodes, and many other Kubernetes resources are outside the map.
- Selecting a namespace filters data; it does not change access permissions.
Troubleshooting
| Symptom | What to try |
|---|---|
| Empty graph | Select *All* or another namespace, restore faded legend entries, then refresh. The selected namespace may contain no supported resources. |
| A resource or arrow is missing | Check the namespace, legend filters, and supported relationships above. Refresh after changes. |
| Namespace list is stale | Reload the page. Refresh reloads only the graph. |
Failed to load graph or HTTP error |
Record the error and selected namespace, then contact your administrator. An existing graph may be stale. |
| Page loads but graph does not initialize | Check the browser console/network panel for failed scripts from unpkg.com, then report them to your administrator. |
| Pod looks ready but the application is unhealthy | Inspect actual readiness conditions, logs, and endpoints; the map's readiness flag is simplified. |
When reporting a problem, include the page URL, selected namespace, resource kind/name, footer error, last refresh time, and what you expected to see.