Upgrading the Agent

A cluster connected with tetrate onboard, with the Manual connection steps, or from a cloud account runs the agent as an ordinary Helm release. Nothing upgrades that release for you: Tetrate holds no credentials to your cluster, and without a managed data plane there is no repository for an upgrade to arrive through. This page upgrades the agent with Helm while keeping the configuration it runs with.

This page is only for non-managed agent installs

If the cluster runs a managed product, its agent is installed by ArgoCD from the agent directory of your repository, and agent upgrades arrive as upgrade pull requests like every other component. Do not run Helm against it: ArgoCD reverts the change on its next sync.

An agent that falls behind keeps working. New Tetrate releases are recognized from the release catalog the agent fetches, not from its own image, and analysis happens on the server, so an upgrade is about the agent's own fixes and features rather than about seeing newer Tetrate components.

The exception is images pulled from your own registry. Agents up to 0.4.3 recognize them once you name the mirror, but do not report which Tetrate image they copy, so they show No scan data and no Upgrade available marker. If your clusters pull Tetrate's images through a mirror, upgrade to get CVE findings and upgrade markers for them.

Knowing When an Upgrade Is Available

The agent's own image is in the release catalog, so the console treats it like any other Tetrate component:

• The Agent column in the Clusters view shows the version each cluster runs. Search for a version, such as 0.4.2, to list every cluster still on it.
• Expanding a cluster lists the agent's own container, patch-service-agent in the tetrate-dataplane-system namespace. When a newer agent is published, its Status carries the Upgrade available arrow with the version to move to, and the cluster name carries the orange arrow.

The latest release is also published in the catalog itself, which is the source to script against:

curl -s https://releases.tetrate.io/manifests/patch-service-agent.json \
  | jq -r '.latestVersion as $v | "image tag: \($v)\nchart version: \(.versions[$v].helm.version)"'

image tag: 0.4.3
chart version: v0.4.3

The chart and the image are released together under the same version. Note the one difference in spelling: the chart version starts with a v and the image tag does not.

Before You Begin

• kubectl and helm 3.8 or newer, which pulls charts from OCI registries. The tetrate CLI does not take part in an upgrade.
• A kubeconfig context pointing at the cluster, with cluster-admin access. An upgrade can change the agent's cluster-scoped read permissions along with its Deployment.
• The versions to move to, from the catalog or the console as described above.

Every command below targets the release the onboarding flows create. The names are fixed: an upgrade finds the previous install by them, so use them as they are.

What	Value
Helm release	patch-service-agent
Namespace	tetrate-dataplane-system
Chart	oci://fips-containers.teg.tetratelabs.com/patch-service-agent-helm

Confirm the release is there and see which version it runs:

helm list -n tetrate-dataplane-system

NAME                 NAMESPACE                 REVISION  STATUS    CHART                            APP VERSION
patch-service-agent  tetrate-dataplane-system  1         deployed  patch-service-agent-helm-v0.4.2  0.4.2

If the list holds no patch-service-agent release but the agent is running, ArgoCD manages it: the cluster is on the managed data plane, and its upgrades arrive as pull requests instead.

Step 1: Save the Current Values

The onboarding flows install the agent with values that connect it to your organization: your customer ID, the server it reports to, its client ID, the name of the Secret holding its credentials, and the namespaces it watches. An upgrade has to pass all of them again, and the release itself is the authoritative record of them. Save them to a file:

helm get values patch-service-agent -n tetrate-dataplane-system -o yaml > agent-values.yaml

The file looks like this, with your organization's values in place of the placeholders:

agent-values.yaml

clusterNameConfigMap:
  name: patch-service-agent-config
commonLabels:
  dataplane.tetrate.io: <customer-id>
customerId: <customer-id>
image:
  repository: fips-containers.teg.tetratelabs.com/patch-service-agent
  tag: 0.4.2
imagePullSecrets:
- name: tetrate-pull-credentials
podLabels:
  dataplane.tetrate.io: <customer-id>
podNamespaces:
- tetrate-dataplane-system
- envoy-gateway-system
- envoy-ai-gateway-system
server:
  clientId: <client-id>
  existingSecretName: patch-service-agent
  tokenUrl: https://auth.patch.tetrate.io/oauth2/token
  url: https://<your patch service API>

The file holds no secrets: the agent's client secret lives in the patch-service-agent Secret and the cluster's name in the patch-service-agent-config ConfigMap, both applied during onboarding and both left untouched by an upgrade. Keep the file under version control if you like; it is also the place to make any change you want to ship with the upgrade, such as naming an image mirror.

Mirror settings to review

If agent-values.yaml has a releaseCatalog.extraRepositories list, check that every entry names the Tetrate repository it copies, as <your repository>=<Tetrate repository>. An entry with only your repository is still reported after the upgrade, but its images are never scanned. releaseCatalog.registryAliases entries need no change. See Extra Repositories.

Upgrading from an agent older than 0.4.0

Agents before 0.4.0 found workloads by label, and their values carry a selector line such as selector: dataplane.tetrate.io=<customer-id>. Delete that line from agent-values.yaml before upgrading. Left in place, it keeps the new agent narrowed to labeled workloads, so it reports only the Tetrate workloads you happened to label instead of finding them all on its own.

Step 2: Authenticate to the Tetrate Registry

The agent chart is served from a private registry, fips-containers.teg.tetratelabs.com, and pulling it takes your organization's Tetrate Hub credentials. Onboarding already stored them in the cluster, in the tetrate-pull-credentials Secret the agent pulls its image with, and that Secret is in the format Helm reads registry credentials from. Write it to a file for Helm to use:

kubectl get secret tetrate-pull-credentials -n tetrate-dataplane-system \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > tetrate-registry.json

The file contains a password, so treat it as one: it is used by the next step and deleted right after.

If you already ran helm registry login fips-containers.teg.tetratelabs.com on this machine, for example from the Manual connection steps in the console, you can skip this step and leave --registry-config out of the next one.

Step 3: Run the Upgrade

Upgrade the release to the new chart version, with the saved values and the new image tag. The image tag has to be set explicitly: agent-values.yaml pins the version you are upgrading from, and without the override the new chart would keep running the old image.

helm upgrade patch-service-agent \
  oci://fips-containers.teg.tetratelabs.com/patch-service-agent-helm \
  --version v0.4.3 \
  --namespace tetrate-dataplane-system \
  --registry-config tetrate-registry.json \
  --values agent-values.yaml \
  --set image.tag=0.4.3 \
  --wait

rm tetrate-registry.json

Replace v0.4.3 and 0.4.3 with the chart version and image tag you are moving to. --wait returns once the new agent is running, so a failure, such as an image that cannot be pulled, surfaces here rather than later in the console.

Release "patch-service-agent" has been upgraded. Happy Helming!
NAME: patch-service-agent
NAMESPACE: tetrate-dataplane-system
STATUS: deployed
REVISION: 2

Always pass the saved values

Do not run the upgrade with --set flags alone. A helm upgrade given no values file resets every value it is not given to the chart's defaults, and the defaults carry no customer ID, no server, and no credentials, so the upgraded agent would stop reporting.

Step 4: Verify the Upgrade

Check that the new agent rolled out and runs the version you asked for:

helm list -n tetrate-dataplane-system
kubectl get deployment patch-service-agent -n tetrate-dataplane-system \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

A restarted agent reports straight away, so within a minute the console agrees: the cluster's Agent column shows the new version, and the agent's own container in the expanded row no longer carries an Upgrade available arrow. The agent's log confirms the same from inside the cluster:

kubectl logs deployment/patch-service-agent -n tetrate-dataplane-system | grep "reported cluster snapshot"

{"level":"INFO","msg":"reported cluster snapshot","containers":3,"products":0,"forced":true}

If you set releaseCatalog values, also check that the agent found something to match for each of them. It logs a warning at startup for any registry alias or extra repository that matches nothing in the catalog, and nothing when they all match:

kubectl logs deployment/patch-service-agent -n tetrate-dataplane-system | grep "matches nothing"

Rolling Back

Helm keeps the previous revision, so returning to it is one command, and the values it ran with come back with it:

helm rollback patch-service-agent -n tetrate-dataplane-system

Pulling a chart is not part of a rollback, so it needs no registry credentials.

Next Steps

• Look up any value in agent-values.yaml in Agent Helm Values, including which ones onboarding set and should be kept.
• If your Tetrate images come from your own registry, name the mirror in the same agent-values.yaml so the upgraded agent recognizes them.
• View your clusters to confirm every cluster's Agent column shows the new version.
• Read Clusters and the Agent for what the agent watches and why falling behind does not stop it recognizing new releases.