How To: List the Pod Summaries for a Kubernetes Cluster and Namespace

After deploying the RealTheory collector to a Kubernetes cluster (See Installing RealTheory in a Cluster), the cluster and its associated objects become available in the RealTheory API within minutes.

Overview

Listing the pod summaries for a given cluster and namespace is a three-step process, where each step resolves the identifiers needed by the next. All three calls are made against the K8sSummary endpoint.

1. Look up the cluster summary by name using the ClusterSummaries endpoint with the query metadata.name=<cluster-name>. This gives the <cluster-id>.

   Example query: metadata.name=realtheory-cluster-01

2. Get all namespace summaries associated with the cluster using the NamespaceSummaries endpoint with the query metadata.clusterId=<cluster-id>. This gives all <namespace-name> and <namespace-id> values.

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

3. Look up the pod summaries associated with the cluster and namespace using the PodSummaries endpoint with the query metadata.clusterId=<cluster-id> AND metadata.namespaceId=<namespace-id>.

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

Note:

• All calls to RealTheory APIs must be authenticated and authorized. See Authentication for more details.
• Each call accepts the common index, count, order, and direction paging parameters. See Paging for more details on how to page through all results.
• Queries should be URL encoded; otherwise the request might be rejected.

Step 1: Look up the cluster summary by name

Call the method below to find the cluster summary whose name matches the given cluster name.

GET <endpoint>/theory/api/v1/k8ssummary/clustersummaries/search/query/{query}?index={index}&count={count}&order={order}&direction={direction}

where

• {endpoint} - is the URL of the RealTheory SaaS portal for your account.
• {query} - is a query used to match the cluster by name.
• {index} - is the starting index of the cluster summaries to include in the list. This parameter is optional and defaults to 0 if not specified.
• {count} - is the maximum number of cluster summaries to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified.
• {order} - is a string containing the name of the attribute to sort on. This parameter is optional.
• {direction} - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified.

Note: While it is expected that the query will only return one result, the query may return more than one result if the cluster name is not unique. Page through the results as needed by incrementing the {index} by the {count} on each subsequent call. See Paging for more details.

Example

GET theory/api/v1/k8ssummary/clustersummaries/search/query/metadata.name=realtheory-cluster-01?index=0&count=100&order=metadata.name&direction=0

which returns the ClusterSummary objects whose name is realtheory-cluster-01. The metadata.id field of the returned object is the <cluster-id> used in the following steps.

[
  {
    "metadata": {
      "id": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "name": "realtheory-cluster-01",
      "timestamp": "2024-07-17T20:15:15.333644Z"
    },
    ...
  }
]

Step 2: Get the namespace summaries for the cluster

Using the <cluster-id> from Step 1, call the method below to get all namespace summaries associated with the cluster.

GET <endpoint>/theory/api/v1/k8ssummary/namespacesummaries/search/query/{query}?index={index}&count={count}&order={order}&direction={direction}

where

• {query} - is a query used to limit the results to namespaces within the given cluster.
• {index} - is the starting index of the namespace summaries to include in the list. This parameter is optional and defaults to 0 if not specified.
• {count} - is the maximum number of namespace summaries to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified.
• {order} - is a string containing the name of the attribute to sort on. This parameter is optional.
• {direction} - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified.

Note: To retrieve all namespace summaries, increment the {index} by the {count} on each subsequent call until a response returns fewer namespace summaries than the {count} requested. See Paging for more details on how to page through all results.

Example

GET theory/api/v1/k8ssummary/namespacesummaries/search/query/metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a?index=0&count=100&order=metadata.name&direction=0

which returns a list of the first 100 NamespaceSummary objects for the cluster, sorted by name in ascending order. Each object's metadata.id is the <namespace-id> and its metadata.name is the <namespace-name> used in the next step.

[
  {
    "metadata": {
      "id": "568490d7-9f0e-41ad-b416-8392056cb455",
      "name": "web-app",
      "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "clusterName": "realtheory-cluster-01",
      "timestamp": "2024-07-17T20:15:15.333644Z"
    },
    ...
  }
]

Step 3: Get the pod summaries

Using the <cluster-id> from Step 1 and a <namespace-id> from Step 2, call the method below to get the pod summaries for that cluster and namespace.

GET <endpoint>/theory/api/v1/k8ssummary/podsummaries/search/query/{query}?index={index}&count={count}&order={order}&direction={direction}

where

• {query} - is a query used to limit the results to pods within a given namespace and cluster.
• {index} - is the starting index of the pod summaries to include in the list. This parameter is optional and defaults to 0 if not specified.
• {count} - is the maximum number of pod summaries to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified.
• {order} - is a string containing the name of the attribute to sort on. This parameter is optional.
• {direction} - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified.

Note: To retrieve all pod summaries, increment the {index} by the {count} on each subsequent call until a response returns fewer pod summaries than the {count} requested. See Paging for more details on how to page through all results.

Example

GET theory/api/v1/k8ssummary/podsummaries/search/query/metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a AND metadata.namespaceId=568490d7-9f0e-41ad-b416-8392056cb455?index=0&count=100&order=metadata.name&direction=0

which returns a list of the first 100 pod summaries associated with the given namespace and cluster, sorted by name in ascending order.

Notes:

• A pod summary is an object that summarizes key information related to a Kubernetes Pod.
• As cluster and namespace names are not guaranteed to be unique across all environments, it is strongly recommended to use the metadata.clusterId and metadata.namespaceId fields, as shown above. See Objects for more details on querying related objects.

Output

Returns an array of PodSummary objects:

[
  {
    "metadata": {
      "id": "a6095791-7552-474a-8865-85bfa2efd4b9",
      "name": "activity-6c467dfcd-jn2qg",
      "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "clusterName": "realtheory-cluster-01",
      "nodeId": "1206f66c-65a1-4ae6-a7cc-e5ced6cc2ae4",
      "nodeName": "aks-userpool-15373879-vmss000029",
      "namespaceId": "568490d7-9f0e-41ad-b416-8392056cb455",
      "namespaceName": "web-app",
      "deploymentId": "1284d4ef-558a-4d57-8a2e-21e218f9a9f3",
      "deploymentName": "activity",
      "timestamp": "2024-07-17T20:15:15.333644Z"
    },
    "ready": "1/1",
    "status": "Running",
    ...
  },
  {
    "metadata": {
      "id": "e3b2c9f4-1a77-42d1-9f0e-7c1d2a9b04e5",
      "name": "queue-767b8d9c88-rwvjx",
      "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "clusterName": "realtheory-cluster-01",
      "nodeId": "1206f66c-65a1-4ae6-a7cc-e5ced6cc2ae4",
      "nodeName": "aks-userpool-15373879-vmss000029",
      "namespaceId": "568490d7-9f0e-41ad-b416-8392056cb455",
      "namespaceName": "web-app",
      "deploymentId": "a6ffe9d7-8bda-43a9-bc65-4f7dfdbc7ebf",
      "deploymentName": "queue",
      "timestamp": "2024-07-17T20:15:15.333644Z"
    },
    "ready": "1/1",
    "status": "Running",
    ...
  },
  ...
]

Note: Content has been omitted from the JSON response above for brevity.