How To: List the Namespace Summaries for a Kubernetes Cluster

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 namespace summaries for a given cluster is a two-step process, where the first step resolves the identifier needed by the second. Both 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>.

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

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 step.

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

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 for a 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 namespace summaries associated with the given cluster, sorted by name in ascending order.

Notes:

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

Output

Returns an array of NamespaceSummary objects:

[
  {
    "metadata": {
      "id": "3fa272eb-7faa-41f2-a416-2c59b950b277",
      "name": "cert-manager",
      "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "clusterName": "realtheory-cluster-01",
      "owners": null,
      "timestamp": "2024-03-06T20:17:25.0471704Z"
    },
    ...
  },
  {
    "metadata": {
      "id": "b1cb1122-68e6-41f8-bd62-8b6e2ba675cd",
      "name": "default",
      "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a",
      "clusterName": "realtheory-cluster-01",
      "owners": null,
      "timestamp": "2024-03-06T20:16:24.2065431Z"
    },
    ...
  },
  ...
]

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