What Does the Out-of-Date Agent Indicator Mean?

Background

The Collector agent is a lightweight but essential component that gathers and streams cluster metadata to the RealTheory platform. Keeping the Collector up to date ensures you have access to the latest features, performance improvements, and bug fixes.
The Collector is designed to update itself automatically. It restarts periodically, and each restart prompts Kubernetes to pull the latest Collector image from the official RealTheory container registry — keeping it in sync with the RealTheory platform without any manual intervention.

What the Indicator Means

When you see the out-of-date agent indicator in the RealTheory console, it means the Collector agent running on that cluster is not the current version. As a result, some console features or cluster metadata might be missing, incomplete, or behaving unexpectedly.

Why Does This Happen?

In most cases, the Collector's auto-update mechanism works without issue. However, certain configuration changes made to the Collector deployment can prevent it from updating correctly:

• The image uses a fixed version tag
  Auto‑upgrade only works when the image uses the floating latest tag.

  Allows auto-update: image: realtheory/theory-k8s-collector
  Allows auto-update: image: realtheory/theory-k8s-collector:latest
  Blocks auto-update: image: realtheory/theory-k8s-collector:v1.3.11836 
    A pinned version means Kubernetes will never pull a newer build.

• The image is coming from a private registry that is not syncing with the latest images in the RealTheory registry
  You can use a private registry, but it must mirror the official RealTheory container registry

  Allows auto-update: realtheory/theory-k8s-collector
  Blocks auto-update (if not syncing): private-registry.example.com/realtheory/theory-k8s-collector 
    If the private repo isn’t syncing new images, the agent will not upgrade.

• imagePullPolicy is not set to Always
  An imagePullPolicy that is set to Always ensures Kubernetes pulls the latest image every time the pod starts or restarts.

  Allows auto-update: imagePullPolicy: Always 
  Blocks auto-update: imagePullPolicy: IfNotPresent or if the imagePullPolicy field is omitted entirely, Kubernetes will reuse the cached image rather than checking for a newer version.

Solution

If you see the out-of-date agent indicator, determine why the agent is not automatically upgrading:

• If the agent was deployed with the standard deployment manifest (highly recommended), do one of the following:
  • If you have access to Settings > Agent > Management, navigate to the view, locate the cluster, and initiate the update manually
  • If you do not have access to Settings > Agent > Management, the upgrade will self-resolve within seven days
• If the agent was not deployed with the standard deployment manifest, do one of the following:
  • If you are using your own repository rather than the RealTheory repository, ensure that your repository is regularly syncing with the RealTheory repository
  • If you have pinned to a specific agent version, remove the specific version and use either no tag or thelatest tag instead
  • If you have changed or removed the imagePullPolicy, ensure that imagePullPolicy is set to Always