Upgrades and Maintenance

Validator maintenance is a controlled change to a node that may be participating in consensus or serving application traffic. An Agave upgrade is therefore not a package update: the client version, network feature state, leader schedule, snapshot behavior, and rollback path all matter.

Before the change

1. Identify the target Agave release and confirm it is appropriate for the target cluster.
2. Record the current client version, genesis hash, current slot, vote account status, and health metrics.
3. Review the release notes and feature implications for the target network.
4. Confirm available disk, working snapshots, and the current recovery time.
5. Choose a window that avoids upcoming leader slots for voting validators.
6. Prepare a rollback binary/configuration and define the point at which rollback is safer than waiting.

agave-validator --version
solana genesis-hash --url <local-rpc-url>
solana validators --url <local-rpc-url>
solana slot --url <local-rpc-url>

Upgrade sequence

1. Drain application traffic from an RPC node, or schedule the validator change outside its assigned leader window.
2. Stop the service gracefully and wait for the process to exit.
3. Install or activate the target release without overwriting the previous known-good binary.
4. Start the service and follow logs through snapshot/replay and cluster join.
5. Verify version, genesis hash, slot progression, peer connectivity, and vote/leader status.
6. Restore traffic only after the node meets its normal readiness criteria.

Public-network templates are data, not constants

Known validators, entrypoints, expected genesis hashes, and recommended versions in a startup script are all time-sensitive. Do not copy an old template into a new deployment without verifying it against current official cluster information.

Maintenance windows

For a voting validator, the cost of downtime is higher while it is scheduled to produce. Maintenance automation should therefore combine version-compliance signals with leader-schedule awareness, identifying safe maintenance windows instead of only reporting that a version is outdated.

For hot-switch and failover approaches, see Solana Validator Switch. Treat any failover design as a consensus-sensitive change: validate identity and vote-account custody, network reachability, and recovery behavior in a non-production cluster before relying on it.

Evidence to keep

Store the change request, old/new versions, timestamps, configuration diff, health checks before/after, restore/replay duration, and any alert suppression used. That record turns the next upgrade into an improvement rather than another one-off operation.