Why Are My Collector Agents Out of Date and Not Upgrading?

  • Updated on Aug 15, 2025
  • Published on Aug 15, 2025
  • 1 minute(s) read
Prev Next

Background

By default, the RealTheory Collector agent, which runs on each cluster that RealTheory monitors, automatically restarts weekly. This restart triggers Kubernetes to pull the latest Collector image from the official RealTheory container registry and start the pod with the updated image if it is newer than the current one.

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

Problem

When changes such as the following are made to the Collector deployment manifest before it’s applied to the cluster:

  • 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

the Collector auto-upgrade process can stop working because, 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 connectivity between the Collector agent and the RealTheory console:

  1. 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. Allow the collector to run with its default weekly restart schedule so it can automatically fetch updates from the official RealTheory container registry.

Important: Modifications to the Collector’s image path or imagePullPolicy are unsupported and will disrupt connectivity and data collection, even if intended to solve caching or registry access issues.