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

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
• Changing the imagePullPolicy from Always to another value, or omitting it entirely

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, follow the standard deployment or the custom registry guidelines below.

Standard Deployment (Recommended)

1. Deploy the YAML file generated by the RealTheory console without modifying:

   • The Collector’s image path (including the registry, repository name, or image tag).

   • The imagePullPolicy, which must remain set to Always.

2. Allow the Collector to run with its default weekly restart schedule to automatically fetch updates from the official RealTheory container registry.

Custom Deployment Using a Custom Registry

Organizations with strict security or network policies might need to point the Collector agent to an internal mirror. If you use a custom registry, you can modify the image path, repository, and tag provided in the YAML; however, you must adhere to the following requirements:

• Synchronization Schedule - You are responsible for keeping your custom registry synchronized with the official RealTheory registry. We recommend at least a weekly cadence for synchronization to ensure you receive critical security patches and feature updates.

• Avoid Version Gaps - RealTheory releases updates on a rolling basis. While a minor version gap might only result in missing features, a significant gap will eventually result in degraded data collection and missing functionality as the agent and backend evolve.

• Maintain Pull Policy - The imagePullPolicy must remain set to Always so the agent checks your custom registry for the latest mirrored image during its weekly restart.