Upgrade notes

This page lists each version's breaking changes and what to do before you upgrade. For the upgrade steps themselves, see Upgrade Zeabur.

If you're skipping versions, start at the version you run now and read every section up to the version you're moving to. The newest version is at the top.

v0.1 → v0.2

On a server installed with zeabur-installer, change the configuration file and remove the zot that v0.1 installed, then run plan and apply. If other nodes joined later, worker nodes or RKE2 servers, have each one join again after the server is upgraded.

If you installed with Helm, Argo CD or Flux, the chart values have no breaking changes. You only need to act if you added flags that v0.2 removed to the Deployment yourself. See below.

Installed with zeabur-installer

Run the kubectl commands below on the server. On K3s, use sudo k3s kubectl. On RKE2, use sudo /var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml.

1. Change the configuration file

Edit /etc/zeabur-installer/config.yaml on the server and replace the three old forms below.

v0.2 has no preset. By default it installs the components the catalog recommends, plus Zeabur Builder, Keel and CloudNativePG. Adjust it based on your old preset:

Before	After
standard, or not set	Delete the preset line
secure	Delete preset and add enable: [runtime-security, vulnerability-scanning, intrusion-prevention]
minimal	Delete preset, run plan to see which components it adds, and add the ones you don't want to disable

Zeabur Builder is a new default component that builds from Git. If you don't need it, add builds to disable.

Input names in inputs and secretFiles are now camelCase, and the new version doesn't read the old names. If a required input uses its old name, plan reports it as missing. An optional one is treated as unset and takes its default. If you use any of these components, rename the old inputs:

Component	Old name	New name
builds/zeabur-builder	cluster-ip	clusterIp
intrusion-prevention/crowdsec	bouncer-key, lapi-secret, registration-token	bouncerKey, lapiSecret, registrationToken
remote-access/tailscale-operator	oauth-client-id, oauth-client-secret	oauthClientId, oauthClientSecret
volume-backup/velero	s3-url, repository-password, backup-key, file-backup	s3Url, repositoryPassword, backupKey, fileBackup

If enable or disable lists container-registry/zot, delete it. zot is now part of Zeabur Builder.

2. Remove the zot that v0.1 installed

v0.1's default components included a standalone zot. v0.2 doesn't replace it with Zeabur Builder's zot, so remove it yourself first. Check whether this server has it:

kubectl -n kube-system get helmchart zot \
  -o jsonpath='{.metadata.annotations.installer\.zeabur\.com/component}'

Only remove it if this prints container-registry/zot. If it prints builds/zeabur-builder, or there's no zot, go to the next step.

kubectl -n kube-system delete helmchart zot
kubectl -n zot get pods      # wait until no pods are left
kubectl delete namespace zot

This also deletes the images zot stored. The next apply installs Zeabur Builder with its own zot, and builds push their images again.

3. Upgrade the server

If profile is multi-node, run these first. v0.1 gave VictoriaMetrics a 20 GiB volume on multi-node and v0.2 asks for 5 GiB, but a volume can't shrink, so the VictoriaMetrics operator would stop updating vmsingle. The first command tells the operator to keep the volume's size, and the second makes it try vmsingle again:

kubectl -n observability annotate pvc vmsingle-vm-victoria-metrics-k8s-stack operator.victoriametrics.com/pvc-allow-volume-expansion=false
kubectl -n observability rollout restart deployment victoria-metrics-operator

Download the v0.2 installer, run plan, review it, then run apply. See Upgrade Zeabur for the steps.

plan lists the components this upgrade adds. System Upgrade Controller is no longer a default component. apply doesn't remove it but stops updating it, and plan shows it as not removed, no longer updated. The installer already pins the K3s and RKE2 release, so you don't need it. To keep it, add node-updates/system-upgrade-controller to enable. Otherwise, delete it after apply:

kubectl delete namespace system-upgrade
kubectl delete crd plans.upgrade.cattle.io
kubectl delete clusterrolebinding system-upgrade system-upgrade-drainer
kubectl delete clusterrole system-upgrade-controller system-upgrade-controller-drainer

The zot you removed in step 2 also shows as not removed, no longer updated in plan. That's because the install record still lists it. It no longer shows after apply.

v0.2 reserves memory for the system so pods can't use it all and take the whole server down. So apply restarts K3s or RKE2. The Kubernetes API stops answering for about 10 seconds. Running apps keep serving. The reserved memory is taken from what pods can request, so on a server that was nearly full, pods may no longer fit and stay Pending. plan warns when the pods on a node already request more than is left. Before apply, delete a service on that node or lower its replicas, move a service to another node, or add a node.

4. Have the other nodes join again

Nodes that joined later have a join section in their configuration file: worker nodes, and on RKE2, servers added after the first. If no node has one, skip this step.

In their configuration files, v0.1's join.zot is join.registry in v0.2, and zot's address has changed, so join again with a new configuration:

1. On the upgraded server, run sudo zeabur-installer node add. For RKE2 servers that joined later, add --role server so they keep their server role.
2. On each of those nodes, put the v0.2 installer in place, back up /etc/zeabur-installer/config.yaml, then paste what node add printed as root. It writes the new configuration file, then runs plan and apply.
3. Once every node is Ready, if any worker nodes joined, run sudo zeabur-installer node sync on the server, then revoke the token as the last line of the node add output says. Until you run node sync, the network policies block the rejoined nodes.

For node add's options and how to revoke its token, see Manage nodes.

Installed with Helm, Argo CD or Flux

Zeabur and Zeabur Proxy dropped the flags that set session length and proxy limits. The values stay the same: people sign in again after 1 hour idle or 12 hours in total. The proxy times out after 30 seconds and caps requests at 16 MiB. The chart never set these flags. If you added them to the Deployment's args or env yourself, delete them before you upgrade:

• zeabur: --session-idle-minutes, --session-max-hours, or the ZEABUR_SESSION_IDLE_MINUTES and ZEABUR_SESSION_MAX_HOURS environment variables.
• zeabur-proxy: --timeout, --max-bytes, --review-cache, --max-inflight, --max-inflight-per-person, or the ZEABUR_PROXY_TIMEOUT, ZEABUR_PROXY_MAX_BYTES, ZEABUR_PROXY_REVIEW_CACHE, ZEABUR_PROXY_MAX_INFLIGHT and ZEABUR_PROXY_MAX_INFLIGHT_PER_PERSON environment variables. Other ZEABUR_PROXY_* variables, such as the TLS certificate and key, still work.