Upgrade a worker
Update the agent image, apply a generated one-Pod Recreate Deployment, verify the new agent, roll back safely, or uninstall the worker.
Loading documentation…
Powered by heyo
The worker list shows Update available when the running agent reports a different image digest from the available image, or reports no digest. The worker detail page shows an Agent update card with the command for your installation. Update required means the worker lacks the current execution capability and receives no checks until its agent is updated. An unknown digest can also mean the agent cannot read its own Pod; check its RBAC before treating the hint as proof of an older image. RestoreTrust never changes the agent Deployment itself; you run the update in your cluster.
Use the Agent deployment patch on the worker detail page when capacity or other Deployment settings change. It contains the current immutable agent image digest and preserves the one-Pod Recreate strategy.
Keep replicas: 1 and strategy.type: Recreate. A rolling update can run two
Pods with the same worker identity, causing the replacement to be rejected.
Record the running configuration for comparison:
Note the exact:
When practical, wait for active checks to finish. Running Jobs are designed to continue through an agent restart and be reconciled by the replacement, but a quiet window makes verification and rollback simpler.
The agent now reads its own Pod to report the image digest. Before upgrading an existing installation, grant its ServiceAccount get on pods as well as pods/log in the agent namespace. The current generated Role and RoleBinding are named restoretrust-k8s-agent-self; the older restoretrust-k8s-agent-self-log pair grants only log access. Save this manifest with your agent namespace substituted, then apply it:
Apply the saved file with kubectl apply -f agent-self-rbac.yaml. The namespace is specified in the manifest.
Verify both permissions before the image update:
Both commands should return yes. After the replacement agent reports its digest and live logs work, you can remove the obsolete restoretrust-k8s-agent-self-log Role and RoleBinding. The worker identity Secret does not change.
The Agent update card shows the short digest of the image that runs and of the one that is available. The command uses the namespace from the Agent namespace field of the deployment patch; correct it there if you installed the agent elsewhere.
Copy the command from the card. It has this form:
It changes only the image. Capacity, scratch settings, customer-added environment values and the identity Secret stay as they are.
After the agent reconnects, the worker detail page shows the new digest and Up to date. If the agent image stays unknown, the agent may not read its own Pod: apply the current generated RBAC, which grants get on pods and pods/log in the agent namespace.
If the change includes Max parallel jobs, edit and save that value on the worker detail page first. Ensure storage quota, volume attachment limits, and node capacity support it.
In Agent deployment patch, check the namespaces and scratch StorageClass against the running installation; they are pre-filled with what the agent last reported. Copy the generated YAML to worker-deployment.yaml.
The identity Secret is deliberately not included or rotated.
Confirm that the image uses @sha256:..., replicas remain one, the strategy remains Recreate, and cluster-specific settings are preserved.
Reapply approved RT_JOB_EGRESS_*_CIDRS values or other customer-owned Pod settings before continuing.
Recreate stops the old Pod before starting the new one.
Confirm there is exactly one agent Pod. In RestoreTrust, check Online, Accepting jobs: Yes, and the expected capacity.
Run a representative manual check and verify its scratch PVC and execution NetworkPolicy.
The detail-page patch updates the Deployment only. If RestoreTrust release guidance requires RBAC, namespace, or egress admission changes, follow those release-specific instructions; do not broaden permissions by inference.
If the new Pod does not become healthy:
Do not restore or rotate the identity Secret during an image rollback.
Uninstalling removes the worker record from RestoreTrust and requires separate cleanup in your cluster.
Edit every schedule that selects this worker. Assign a healthy replacement worker or pause the schedule.
Wait until no check is running on the worker. RestoreTrust refuses to remove a worker with running checks.
Scale the Deployment to zero so it cannot reconnect while you remove the worker.
On the worker detail page, choose Uninstall and confirm the exact worker name. The identity becomes unusable.
If both namespaces are dedicated to this worker, delete them after confirming no required Secret or retained data remains:
If you applied the optional cluster-scoped admission objects, inspect them and delete them only when they target this removed job namespace and protect no other installation.
Deleting the job namespace permanently removes local source and decryption Secrets, Jobs, Pods, PVCs, and any retained restore data. Back up anything your policy requires before deletion.