Objects

Overview

For each type of Kubernetes object, RealTheory provides two complementary objects: a Summary object and a Kubernetes object.

Together, these two objects offer different levels of detail about the same underlying Kubernetes object. The Summary object provides a high-level, aggregated view that is optimized for visualization and quick insights, while the Kubernetes object provides the concrete, detailed state of the object, including the raw resource returned by the Kubernetes API.

Summary Objects

Summary objects provide a high-level summary of a Kubernetes object and form the basis for the visualizations and quick views within the RealTheory console.

Summary objects are available through the K8sSummary API endpoint, where each object type has its own resource path:

<endpoint>/theory/api/v1/k8ssummary/clustersummaries
<endpoint>/theory/api/v1/k8ssummary/namespacesummaries
...
<endpoint>/theory/api/v1/k8ssummary/podsummaries

A Summary object aggregates key information about an object into a single, easy-to-consume record, typically including:

• metadata: Common metadata used to identify the object and its relationships to other objects, such as its cluster, namespace, and owners.
• manifest: Counts of the objects contained within or associated with the object, such as the number of pods, containers, or deployments.
• metrics: Current resource usage, requests, and limits, such as CPU, memory, and network metrics.
• cost: Cost information associated with the object over various time windows.
• synopsis: Health, performance, governance, and cost scores, along with aggregated alert and recommendation counts.

Because Summary objects are pre-aggregated, they are well suited to powering dashboards, lists, and other views where a concise overview is more useful than the full underlying detail.

Kubernetes Objects

Kubernetes objects provide the concrete details that show the current state of an object. Each Kubernetes object references the actual object returned by the Kubernetes API through its object property, providing the raw data that forms the basis of much of the Summary data.

Kubernetes objects are available through the K8s API endpoint, where each object type has its own resource path:

<endpoint>/theory/api/v1/k8s/clusters
<endpoint>/theory/api/v1/k8s/namespaces
...
<endpoint>/theory/api/v1/k8s/pods

A Kubernetes object typically includes:

• metadata: The same common metadata used to identify the object and its relationships to other objects.
• object: The raw Kubernetes resource, exactly as returned by the Kubernetes API.
• extensions: Additional RealTheory-specific data derived from the object that is not part of the raw Kubernetes resource.

Kubernetes objects are best suited to scenarios that require the full, authoritative detail of an object, such as inspecting an individual object's configuration or state.

Object Pairs

Every Summary object has a corresponding Kubernetes object. The table below lists the available object pairs:

Querying Related Objects

Both the K8sSummary and K8s APIs support metadata queries, making it easy to discover and query related objects.

Because objects share a common set of metadata, you can query one object type by the identifiers of a related object. For example, to get all the namespace summaries associated with a given cluster, call the NamespaceSummary endpoint with a query using the cluster's ID:

metadata.clusterId = <cluster-id>

for example:

metadata.clusterId = f99e055f-b35d-208b-63b1-f4222b80151a

Queries can also combine multiple conditions to narrow the results further. As a second example, to find all the pod summaries within a given cluster and namespace, call the PodSummary endpoint with a query combining the cluster and namespace IDs:

metadata.clusterId = <cluster-id> AND  metadata.namespaceId = <namespace-id>

for example:

metadata.clusterId = f99e055f-b35d-208b-63b1-f4222b80151a AND metadata.namespaceId = 568490d7-9f0e-41ad-b416-8392056cb455

The same queries also work against the K8s APIs, allowing you to discover and navigate related objects consistently across both Summary and Kubernetes objects.

Note: While these queries can be written against either the name or ID metadata fields, it is always better to use IDs, as they are guaranteed to be unique across the data plane and are indexed for fast lookups.

Note: When looking up IDs from names — for example, resolving the ID for a cluster or namespace — it is recommended to use the K8sSummary APIs rather than the K8s APIs. Summary objects are an order of magnitude smaller in size, which means less network transfer and lower latency.