Skip to main content
logoTetrate Patch ServiceVersion: alpha

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 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 carrying your custom label. 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.

Snapshots and Observations​

Every report the agent sends is a full snapshot: the complete set of containers running in the cluster at that moment, 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. 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 the Deployments and DaemonSets that carry your customer label, so what a cluster inventories is your decision, taken by labeling workloads.
  • 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​