Why Is Cluster Metadata Missing From the Console?

Background

RealTheory provides real-time visibility into metrics, costs, performance, and health data for Kubernetes environments. Nearly all of this metadata comes from a lightweight but essential component called the RealTheory Collector.

The Collector deployment manifest, which can be easily generated with the correct configuration settings through the RealTheory console:

• References the official RealTheory container registry, which implicitly uses the latest tag.
• Sets the imagePullPolicy configuration to Always, instructing Kubernetes to always check for and pull the latest image version on pod restart.

The Collector itself:

• Is configured to pull metadata directly from your cluster and securely stream it back to RealTheory.
• Automatically restarts weekly, triggering Kubernetes to pull the latest Collector image from the registry and start the pod with the updated image if it is newer than the current one.

This design ensures that the Collector is always in sync with the RealTheory services API and that your cluster metadata is continuously collected and displayed in the console without manual intervention.

Problem

If the Collector cannot auto-upgrade or connect properly to RealTheory services, the platform will be unable to ingest new metrics from the affected cluster. This results in:

• Missing cluster metadata in the console.
• The Collector not appearing in the Settings > Agent > Management view.

Cause

In many cases, this problem can be traced to changes made to the Collector deployment before it’s applied to the cluster, such as:

• Modifying the image path to point to a local or private container registry instead of the official RealTheory registry.
• Pinning the collector to a specific image version instead of using the latest tag.
• Changing the imagePullPolicy from Always to another value, or omitting it entirely, prevents Kubernetes from checking for a newer image on pod restart.

These changes break the intended auto-upgrade process. If the alternate registry is not regularly updated to match the official RealTheory registry, or if the Collector is pinned to an outdated version, it will eventually fall out of compatibility with the RealTheory service layer—potentially breaking functionality or preventing access to new features.

Solution

To maintain accurate, real-time cluster data in the console:

1. Recommended: Deploy the YAML file generated by the RealTheory console without modifying the following:
   • The Collector’s image path—including adding a custom registry, changing the repository or image name, or adding an explicit tag.
   • The imagePullPolicy, which must remain set to Always.
2. If you must use a custom image repository, ensure the following:
   • Ensure the custom repository is regularly synchronized with the official RealTheory repository.
   • The imagePullPolicy must remain set to Always so the agent checks your custom registry for the latest mirrored image during its weekly restart.
3. Allow the collector to run with its default weekly restart schedule so it can automatically fetch updates from the official RealTheory container registry.