How to Update Teranode with Kubernetes Helm
Last modified: 19-October-2026
Introduction
This guide provides instructions for updating Teranode in a Kubernetes environment using Helm.
Prerequisites
Ensure you have:
- Access to the ECR registry
- AWS CLI configured
- Helm installed
- Existing Teranode deployment
Update Process
1. Set Version Variables
# Set new versions
export OPERATOR_VERSION=<new-version>
export TERANODE_VERSION=<new-version>
export GHCR_REGISTRY=ghcr.io/bsv-blockchain2. Update Images
# Pull new images
docker pull $GHCR_REGISTRY/teranode-operator:$OPERATOR_VERSION
docker pull $GHCR_REGISTRY/teranode:$TERANODE_VERSION
# Load into Minikube
minikube image load $GHCR_REGISTRY/teranode-operator:$OPERATOR_VERSION
minikube image load $GHCR_REGISTRY/teranode:$TERANODE_VERSION3. Update Operator
# Update operator
helm upgrade teranode-operator oci://ghcr.io/bsv-blockchain/helm/teranode-operator \
-n teranode-operator \
-f kubernetes/teranode/teranode-operator.yaml4. Verify Update
# Check all pods are running
kubectl get pods -n teranode-operator | grep -E 'aerospike|postgres|kafka|teranode-operator'
# Check Teranode services are ready
kubectl wait --for=condition=ready pod -l app=blockchain -n teranode-operator --timeout=300s
# View Teranode logs
kubectl logs -n teranode-operator -l app=blockchain -fProduction Considerations
For production deployments:
- Create backups before updating
- Review release notes for breaking changes
- Test updates in a staging environment first
- Monitor system during and after update
- Have a rollback plan prepared (see Roll Back)
- Changes to the PostgreSQL
init.sqlConfigMap do not apply to an existing persistent volume. If you provisioned the cluster before Teranode dropped superuser from theteranodePostgreSQL role, apply the one-offALTER ROLEin PostgreSQL Role Privileges
Roll Back
Before you roll back, read the release notes of every version between the target version and the current version. Look for data-format, schema or migration warnings.
Teranode applies blockchain store schema changes on startup, and it only applies them forward. If a release in that range changes data formats, do not only change the image version. Restore the backup that you took before the upgrade, as described in How to Back Up and Restore Teranode Data.
1. Roll Back the Teranode Image
The Teranode image comes from spec.image in the Cluster CR. Set it to the
previous release tag:
spec:
image: ghcr.io/bsv-blockchain/teranode:<previous-version>Load the image if your cluster cannot pull it, then apply the CR:
minikube image load ghcr.io/bsv-blockchain/teranode:<previous-version>
kubectl apply -f kubernetes/teranode/teranode-cr.yaml -n teranode-operator2. Roll Back the Operator (if you upgraded it)
# Find the revision before the upgrade
helm history teranode-operator -n teranode-operator
# Roll back to that revision
helm rollback teranode-operator <revision> -n teranode-operatorhelm rollback does not roll back the CRDs, because the install applies them
with kubectl apply. If the new operator version changed the CRDs, apply the
CRDs of the previous operator version:
kubectl apply --server-side -f https://raw.githubusercontent.com/bsv-blockchain/teranode-operator/<previous-operator-version>/deploy/crds.yaml3. Verify the Rollback
# Check that the pods run the previous image
kubectl get pods -n teranode-operator -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
# Check Teranode services are ready
kubectl wait --for=condition=ready pod -l app=blockchain -n teranode-operator --timeout=300s
# Check the FSM state
kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli getfsmstateThen watch the logs, and check that the node follows the network tip and accepts new blocks. If block validation rejects blocks that the network accepts, restore the pre-upgrade backup.
Other Resources
- How to Back Up and Restore Teranode Data
- How to Install Teranode
- Third Party Reference Documentation
- Teranode Sync Guide