Understanding Clusters and the Agent

Everything Tetrate Patch Service shows you starts with the agent: a small controller that runs in each of your clusters and reports which container images are actually running there. The console never guesses from deploy history or configuration; it shows what the agents observed. This page explains what the agent is, how it decides what to report, how its reports work, and the deliberately narrow set of things it can do.

What Is the Agent?

The agent is a lightweight Kubernetes controller that watches the cluster's Deployments and DaemonSets and reports the name and image of every container run by the ones running a Tetrate image. It is a sensor, not a decision-maker: it collects image references and sends them to the Patch Service, and everything else, matching images to components, versions, and vulnerabilities, happens on the server against the release catalog.

That split is deliberate. Because analysis lives server-side, new analysis never requires an agent upgrade in your cluster: when Tetrate improves categorization or publishes new releases, your existing agents' reports light up with the new information on their own.

On the managed data plane, the agent reports one more thing: which managed products it finds installed in the cluster. That is a separate question from what images are running, and the agent is the only reliable answer to it. An install record says what was asked for; the agent says what is there now, so a product whose install failed or that has since been removed is simply absent from the report. The Products column in the Clusters view is that report and nothing else.

What the Agent Reports

The image decides, not you. A container is reported when the image it runs is one Tetrate publishes, checked against the same public release catalog that drives categorization and upgrade markers. Nothing in your cluster has to be labeled or annotated, and a Tetrate product installed after the agent is picked up with no change on your side.

Two consequences are worth stating plainly:

• Your own applications are never reported. Whatever namespace they run in, an image Tetrate does not publish is not reported, so widening what the agent watches costs you nothing in privacy. There is no setting that puts your own images in front of Tetrate's scanners; the catalog decides, and nothing overrides it.
• The catalog includes upstream images Tetrate tracks but does not distribute. If you happen to run one of those for unrelated reasons, it is reported, and it gets CVE and upgrade answers along with everything else.

The agent fetches the catalog rather than relying on the copy built into its image, and refreshes it periodically, which is what lets an agent nobody has upgraded recognize a component Tetrate published after it shipped. A cluster that cannot reach the catalog falls back to the copy it shipped with, so it recognizes everything Tetrate had published when its image was built and nothing newer.

Narrowing What the Agent Watches

Two settings on the agent's Helm chart narrow discovery further, and both only ever narrow:

Setting	What it does
podNamespaces	Restricts the watch to a list of namespaces. Empty watches every namespace.
selector	Restricts the watch to Deployments and DaemonSets whose own labels match a selector. Empty considers every workload in the watched namespaces.

An install from the tetrate CLI, the console's manual steps, or the managed data plane seeds podNamespaces with the namespaces a Tetrate install uses, tetrate-dataplane-system, envoy-gateway-system, and envoy-ai-gateway-system. That is proportion rather than protection: add a namespace if you run a Tetrate product elsewhere, or set it to [] to watch the whole cluster.

Narrowing the watch is not narrowing the grant

podNamespaces changes what the agent looks at, not what it is permitted to read: its ClusterRole grants read-only access to Deployments and DaemonSets cluster-wide either way.

When a Cluster Reports Nothing

A cluster that connects and then shows no containers is running no images the agent recognizes. Three causes account for nearly all of it, in the order worth checking:

1. Its Tetrate images come from your own mirror. Matching is exact, so an image served from your registry is not recognized as Tetrate's until you say where it comes from. Name the mirror on the agent's values: releaseCatalog.registryAliases maps a registry the catalog names to your local prefix, which covers every component on that registry at once, and releaseCatalog.extraRepositories names individual repositories for a mirror that renamed or flattened the paths. A workload pinned by digest needs neither: a mirror preserves digests, so it is recognized wherever it is served from.
2. The workloads run outside the watched namespaces. Widen podNamespaces, or set it to [] for the whole cluster.
3. The cluster cannot reach the release catalog. The agent then knows only what it shipped with, so a recently published component goes unrecognized.

Telling the agent where a Tetrate image is served from is the only way to bring an unrecognized image into scope. That is deliberate: the fix is always about where a Tetrate image comes from, never about opting one of your own workloads into Tetrate's scanning.

Snapshots and Observations

Every report the agent sends is a full snapshot: the complete set of containers running in the cluster at that moment, together with the products installed there, which replaces the previous set entirely. The console shows what runs now, not a history: a container removed from the cluster disappears at the next report, and a missed report is corrected wholesale by the one that follows it.

When the agent sees a workload change, it merges the change into its picture of the whole cluster and sends that complete picture. A catalog refresh that brings a newly published component into scope is itself a reason to re-report, because no cluster event would have fired for it. The Last report and First seen columns in the Clusters view come straight from this reporting loop: First seen is when the cluster was registered, and Last report is when its latest snapshot arrived.

Registered is not connected

A cluster appears in the console as soon as onboarding registers it, but it only counts as connected once its agent reports. A cluster whose install never finished stays visible as never having reported, rather than disappearing.

Cluster Identity and Names

Every cluster carries an identity of its own, read from the cluster itself and fixed for its lifetime. That identity, not the cluster's name, is what the Patch Service files reports under.

The name is a label for people. It is derived from whatever connected the cluster, the kube context name reduced to a DNS-1123 label, and the service keeps names unique within your organization: if the derived name is already held, the cluster is registered under a name derived from it, such as prod-a3f1c2.

Separating the two settles three things at once:

• Two different clusters can never share a record. Two kube contexts can reduce to the same name; two identities cannot collide, so each cluster gets its own record even when their names would have clashed.
• Re-onboarding never renames anything. A cluster is found by its identity, so running an onboarding again finds the existing record whatever the context is called now.
• A cluster becomes correlatable later. A cluster connected from a laptop is recognized as the same cluster when its cloud account is connected, and its source in the console changes from kubeconfig to its account and region.

Because names can be adjusted, the console shows each cluster's source under its name; see Telling Clusters Apart by Source.

One Agent per Cluster

Full snapshots mean two agents in one cluster would each claim to describe the whole cluster, so the Patch Service converges on exactly one agent per cluster, whichever path you connect through:

• Connecting a cluster that the managed data plane already manages does nothing; the agent is already there.
• Installing a managed product on an already-connected cluster adopts the running agent instead of reinstalling it, so reporting never gaps.
• An agent that neither flow installed is refused rather than overwritten: the Patch Service does not replace software in your cluster that it cannot account for.

What the Agent Can and Cannot Do

The agent's permissions are deliberately minimal, so connecting a cluster is a small decision rather than a leap of trust:

• It has read-only access to Deployments and DaemonSets, no access to Pods, and it binds no ports. It also reads its own cluster's identity once at startup, and refuses to start if it cannot, naming the permission it needs rather than reporting anonymously.
• It reports only containers running an image Tetrate publishes. Watching a namespace is not the same as reporting what is in it: what leaves your cluster is decided by the release catalog, and the namespace and selector settings only ever narrow that further.
• It authenticates with a machine identity issued for your organization alone, whose tokens can only ever report for your customer. A leaked credential cannot read anything back or touch another organization.
• Its configuration arrives through a Kubernetes Secret applied during onboarding, so rotating or removing it is a normal Kubernetes operation.
• Deleting a cluster in the console removes its stored data but revokes nothing in the cluster: a still-running agent re-registers on its next report. To stop a cluster from reporting, uninstall the agent.

Next Steps

• Connect your first cluster to see the reporting loop in action within minutes.
• Read the Clusters view to see what the agent's snapshots look like in the console.
• See what upgrades are waiting to read the reported products alongside the requests open against them.
• Read CVE Scanning and Findings for what happens to every image the agent reports.