API reference

Documentation home · Administrator guide

The UI and JSON API share the same host and port (8080 by default). There is no application-level authentication; use the access controls described in the administrator guide. API calls use the backend's Kubernetes identity.

`GET /`

Serves the browser application from app/static/index.html. This path does not query Kubernetes and can succeed even when the JSON endpoints fail.

`GET /namespaces.json`

Lists namespace names using the Core API. There are no query parameters and the response does not guarantee a sort order.

{"namespaces": ["default", "kube-system"]}

`GET /graph.json`

Builds a new graph from Kubernetes list calls.

Parameter	Type	Behavior
`ns`	Optional string	A non-empty value selects that namespace. Omitted or empty selects all namespaces.

Example request:

curl --fail --get --data-urlencode ns=default http://localhost:8080/graph.json

Example response with a selector-based link:

{
  "nodes": [
    {
      "id": "ser:default:web",
      "kind": "Service",
      "ns": "default",
      "name": "web",
      "type": "ClusterIP",
      "selector": {"app": "web"},
      "svcKind": "standard",
      "displayKind": "Service"
    },
    {
      "id": "pod:default:web-example",
      "kind": "Pod",
      "ns": "default",
      "name": "web-example",
      "ready": true,
      "phase": "Running",
      "crash": false
    }
  ],
  "edges": [
    {
      "source": "ser:default:web",
      "target": "pod:default:web-example",
      "reason": "selector",
      "etype": "data"
    }
  ]
}

An empty graph is {"nodes": [], "edges": []}. Array order is not a stable API contract; do not use it as an identifier.

Node fields

Every node has id, kind, ns (namespace), and name. IDs are formed as <first-three-letters-of-kind-in-lowercase>:<namespace>:<name>, for example dep:default:web or orb:kube-system:platform. They identify graph elements, not Kubernetes UIDs, and can be reused when a resource is recreated.

Kind	Additional fields
Deployment, StatefulSet, DaemonSet	`image`: comma-separated distinct container images from the Pod template, or an empty string. Image order is unspecified; init containers are not included.
Pod	`ready`: any regular container status is ready; `phase`: phase or empty string; `crash`: any regular container is waiting with reason `CrashLoopBackOff`.
Service	`type`: Kubernetes Service type; `selector`: object; `svcKind`: `standard`, `headless`, or `external`; `displayKind`: corresponding display label. `orphan: true` is present only for a non-empty selector matching no Pods.
Ingress	`hosts`: rule host strings (empty for a rule without a host); `ingressClassName`: configured class, usually a string or null; `displayKind`: `Ingress`.
OrbitDeployment	`displayKind`: `OrbitDeployment`.

Service classification checks clusterIP == "None" first, then non-empty externalIPs. A LoadBalancer or ExternalName Service is not automatically classified as external. orphan being absent does not prove endpoint health.

Edge fields

Edges have source and target node IDs, etype, and reason. They have no backend-generated edge ID.

`etype`	Source → target	`reason`
`data`	Service → Pod with matching labels in the same namespace	`selector`
`data`	Ingress → existing Service in the same namespace	`backend` for the default backend, or `path:<path>` for HTTP paths (empty paths become `/`)
`create`	Deployment, StatefulSet, or DaemonSet → Pod	`ownerRef`
`manage`	OrbitDeployment → target present in the graph	`managedObject`

An Ingress can produce multiple edges to the same Service for different paths. The UI constructs edge IDs from only source and target, so it may not represent each repeated path separately. Consume the JSON directly if path reasons matter.

Orbit lookup and namespace scope

The custom resource endpoint is group k8s.tlspu.com, version v1, plural orbit-deployments. Management targets are parsed from keys in status.managedObjects with format apiVersion|kind|namespace|name. The API version component is not used to resolve a target; the generated node ID is.

For an all-namespace graph, OrbitDeployments are listed across namespaces. With ns set, they are listed in that namespace and, unless it is kube-system, in kube-system. Only managers whose status mentions the selected namespace are included from kube-system. Management targets must also exist in the graph.

Errors and consistency

The endpoints do not define a custom error response schema. Kubernetes authentication, authorization, connectivity, and API failures generally become HTTP 500 responses; inspect backend logs for the underlying error. A missing namespace can also produce an API error rather than an empty graph. Only HTTP 404 from the Orbit custom-resource lookup is suppressed.

Graph data is assembled from sequential list calls without a shared snapshot or response timestamp. Concurrent cluster changes can affect relationships. There is no response cache, watch stream, or pagination interface exposed by this service. Read the user guide for interpretation limits.

api-reference