Troubleshooting updates

The new version does not appear in the GUI #

Closed loop:

• Verify that the target version is uploaded to the mirror (images and manifests are available in the private repository).
• Check whether the transition from the current version is supported. Not all paths are direct; you may need an intermediate version. See Version transitions and the Update version map.
• Restart ShturvalUpdateChannel (shturval-update) in the cluster;
• Wait 5–10 minutes; during reconciliation - up to 6 hours.

Open loop:

• Check the availability of Registry (r.shturval.tech) from cluster nodes;
• Check the status of the shturval-update module and its dependencies.

Update hangs or rolls back #

• Check the logs of the update module and system services;
• Make sure there are enough resources (CPU, RAM, disk) on the nodes;
• Check the network connection to the Registry;
• If necessary, roll back to the previous version and contact support.

The update has stopped (stuck in one status for more than 1 hour) #

If the update does not change the status for more than an hour:

1. Check shturval-node-config pod logs — this module applies the new Kubernetes version on nodes. Kubelet or node configuration errors often appear here. In the GUI: Services and repositories → Installed services → Node configuration management module (shturval-node-config) → pods → logs. Via kubectl: kubectl logs -n <namespace> -l app.kubernetes.io/name=shturval-node-config -c <container> --tail=200.
2. Check system service pods — ensure shturval-update, shturval-node-config, shturval-backend, and other critical pods are Running and Ready. If pods crash or restart, review events and logs.

Checking status via kubectl #

# List of update channels
kubectl get shturvalupdatechannel -A

# Channel details
kubectl describe shturvalupdatechannel <name> -n <namespace>

If the mirror update freezes, restarting ShturvalUpdateChannel can help pick up the new version:

kubectl -n <namespace> rollout restart deployment shturval-update-channel

Starting with 2.15, available versions are in ClusterInfo in the management cluster, field status.update.availableUpdates. The object name and namespace match the cluster name.

Errors after update #

• Check the release notes of the target version for known issues;
• Check that all system services are in Ready state;
• If you have problems with a specific service, reinstall or update it through the Services and repositories section.

Support #

If you run into problems during an update, contact Shturval support. In the GUI, open About system and submit a request through the service desk.

More information about platform update troubleshooting - Update troubleshooting in the platform administrator section.