Upgrade

Upgrade a kagent 1.x installation and Agent Substrate to a later release.

An installation of kagent consists of five Helm releases. Upgrade the releases in the order that you installed them, starting with the CRDs, then Agent Substrate, and then the kagent control plane.

Upgrade through each release in order, and do not skip a release. For example, to move from 1.0.0 to 1.0.2, upgrade to 1.0.1 first, and then to 1.0.2. To move to a new minor version, upgrade from the last patch release of the previous minor version, such as from 1.0.2 to 1.1.0. To move a 0.10.x installation to 1.x, see Upgrade from 0.x instead.

Prepare to upgrade

Complete every step in this section before you change any release. The steps make sure that Helm manages the installation, back up the database, save the configuration of each release, and set the target versions that the upgrade commands use.

If you installed with the kagent CLI, export the installation to Helm first. The kagent install command is for getting started, and the upgrade commands in this guide use Helm. For the steps, see Export a CLI installation to Helm. An installation that you installed with Helm needs no export.
Read the kagent release notes for every release between your current version and the target version. A release can rename or remove a Helm value, and the chart fails to render when a removed value is still set.
Confirm the installed version of each release.
```
helm list -A --filter 'kagent|substrate'
```
The output lists five releases. The CHART column shows the version of each release.
- The kagent and kagent-crds releases are in the kagent namespace.
- The substrate and substrate-crds releases are in the ate-system namespace.
- The substrate-podcert release is in the podcertificate-controller-system namespace.
Back up the PostgreSQL database that kagent and Agent Substrate share. The upgrade keeps your data. However, the kagent controller and the Agent Substrate API server change the database schema when they start on the new version. To return to the previous version, you must restore the backup.
```
pg_dump "postgresql://<user>:<password>@<host>:5432/kagent" \
  --format=custom \
  --file=kagent-backup.dump
```
Save the values of each release to a file. The upgrade commands reapply these files, so each release keeps its database settings and model provider settings. The --reuse-values flag also reapplies the defaults of the previous chart version, and the new chart can reject a default that it removed. Do not use that flag.
```
helm get values substrate-podcert -n podcertificate-controller-system -o yaml > substrate-podcert-values.yaml
helm get values substrate -n ate-system -o yaml > substrate-values.yaml
helm get values kagent -n kagent -o yaml > kagent-values.yaml
```
For an installation that you exported from the kagent CLI, the kagent-values.yaml file contains your model provider API key in plain text. Store the files securely.
Save the target versions in environment variables. The following values are the versions that this documentation describes. To upgrade incrementally through an earlier release first, set the versions of that release.
```
export KAGENT_VERSION=1.0.0-rc1
export SUBSTRATE_VERSION=1.0.0-rc1
```

Upgrade the CRDs

Upgrade the kagent and Agent Substrate custom resource definitions (CRDs) before the controllers that read them. Both charts ship the CRDs as templates, so helm upgrade updates the CRDs in place.

Upgrade the kagent CRDs.

helm upgrade kagent-crds \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --version ${KAGENT_VERSION} \
  --namespace kagent --wait

Upgrade the Agent Substrate CRDs.

helm upgrade substrate-crds \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate-crds \
  --version ${SUBSTRATE_VERSION} \
  --namespace ate-system --wait

Upgrade Agent Substrate

Upgrade the Agent Substrate PodCertificate controller, followed by the Agent Substrate control plane and data plane. The kagent controller connects to the Agent Substrate API server, so Agent Substrate moves to the new version first.

Upgrade the PodCertificate controller.

helm upgrade substrate-podcert \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate-podcert \
  --version ${SUBSTRATE_VERSION} \
  --namespace podcertificate-controller-system \
  --wait --timeout 5m \
  -f substrate-podcert-values.yaml

Upgrade Agent Substrate.

helm upgrade substrate \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate \
  --version ${SUBSTRATE_VERSION} \
  --namespace ate-system \
  --wait --timeout 10m \
  -f substrate-values.yaml

Confirm that the Agent Substrate pods are running.
```
kubectl get pods -n ate-system
```
In the output, verify that every pod reports Running and that every container is ready. A pod that belongs to a Job, such as the snapshot bucket setup Job, reports Completed.

Upgrade kagent

Upgrade the kagent control plane. The upgrade has no separate migration step.

Upgrade kagent. The saved values pin the Worker image to the previous Agent Substrate version, so the command sets the image again after the values file. A later -f file overrides an earlier one.

helm upgrade kagent \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --version ${KAGENT_VERSION} \
  --namespace kagent --timeout 12m \
  -f kagent-values.yaml \
  -f - <<EOF
substrateWorkerPool:
  workerImage: "ghcr.io/kagent-dev/substrate/ateworker-gvisor:v${SUBSTRATE_VERSION}"
EOF

Wait for the controller to roll out.

kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s

deployment "kagent-controller" successfully rolled out

Verify the upgrade

Confirm that every release runs the new version and that the agents are ready.

Confirm that each release reports the target version.
```
helm list -A --filter 'kagent|substrate'
```
For the kagent and kagent-crds releases, the CHART column shows the target kagent version. For the substrate, substrate-crds, and substrate-podcert releases, the CHART column shows the target Agent Substrate version.

Confirm that the kagent pods are running.

kubectl get pods -n kagent

In the output, verify that every pod reports Running. An installation that uses the development database also lists a kagent-postgresql pod.

NAME                                              READY   STATUS    RESTARTS   AGE
kagent-controller-56c67b6cd7-hqj5z                1/1     Running   0          2m
kagent-default-774d4496bd-sfx4b                   1/1     Running   0          2m
kagent-postgresql-856b475f59-n258n                2/2     Running   0          2m
kagent-tools-54959b659c-lfkrz                     1/1     Running   0          2m
kagent-ui-5fdb6fd85c-vzb2z                        1/1     Running   0          2m

If the controller restarts in a loop, see The controller restarts after an upgrade.

Confirm that the WorkerPool reports a ready replica.

kubectl get workerpools -n kagent

In the output, verify that the READY column matches the DESIRED column, and that the RESOLVED column reports True.

NAME             DESIRED   REPLICAS   READY   SANDBOXCONFIG    RESOLVED   AGE
kagent-default   1         1          1       gvisor-default   True       2m

Confirm that your agents are ready.
```
kubectl get agents -A
```
In the output, verify that every Agent reports True in the READY column.
```
NAMESPACE   NAME       READY   AGE
kagent      my-agent   True    3d
```

Next steps

Operational considerationsReview the production values for replicas, resources, and storage. DebugDiagnose a controller or Agent that does not become ready.

Debug Upgrade from 0.x