What Fabric upgrades involve and when teams call for help
A Fabric upgrade is not a single change on a single server. Each member organization runs its own orderers and peers and must replace the binaries on every node it operates. The upgrade guide describes four steps: back up the ledger and MSPs, upgrade orderer binaries in a rolling fashion, upgrade peer binaries in a rolling fashion, then update the application channel capability levels. The final step changes channel-wide behavior, so its timing is a consortium decision as much as a technical one.
Upgrades usually start from one of four triggers. The first is a move onto a supported line, such as adopting v2.5 LTS or a 3.x release. The second is a security patch. The 3.x and 2.5 LTS lines receive patch releases in parallel, as the v3.1.5 and v2.5.16 releases published on June 18, 2026 show, so patches can arrive on either line. The third is a planned capability change, which should be confirmed in writing by every member before it is made. The fourth is an end of support decision, for which you should confirm the published support dates for your line with the Fabric maintainers before you set a plan.
Many teams with a single in-house Fabric operator keep routine patch work internal. Patch releases on a line the team already runs, rehearsed on a test network first, fit that pattern well. Two areas are often outsourced. The first multi-organization upgrade needs coordinated windows across organizations, agreed capability levels and a rehearsed rollback for each node. The post go-live support window matters too, because faults tend to surface once real transactions flow. Outsource the steps your team has not yet rehearsed in your own environment.
Client applications can be upgraded separately from the network, because the Fabric Gateway client API is compatible with both v2.5 and v3.0. Confirm that your SDK versions, chaincode builds and custom images match the release you plan to run. Prerequisites such as Kafka ordering migration, the legacy chaincode lifecycle and the 2.5 to 3.x path are covered on the migration page, so check that page before scheduling any upgrade work.
What the upgrade and support work includes
The work runs from line selection through production cutover and handover. Each package has a defined output that your team can review before the next one starts.
Version and line selection
Decide whether each network stays on the 2.5 LTS line or moves to 3.x, and record the reasons in writing. The Fabric documentation names 2.5 as the long-term support release for production, while 3.x adds BFT ordering and Ed25519 MSP signing and removes Solo, Kafka and the v1.x lifecycle. Confirm the current patch level on both lines before the decision is signed.
Chaincode compatibility review
Inventory every chaincode package, its language runtime and the lifecycle version it was approved under. Confirm that all channels already use the v2.x lifecycle, because v3.0 removes the v1.x legacy lifecycle and networks must migrate first. Test each package against the target line in the rehearsal and record any package that needs a rebuild.
Client application upgrades
The Fabric Gateway client API works with both v2.5 and v3.0, so applications can move on their own schedule. Confirm each application's SDK version and its connection settings, then decide whether clients move before, during or after the network change. Track client cutover in its own change record so a client fault is not confused with a network fault.
CA, operations and HSM dependencies
Fabric CA, the operations service and any HSM are verified alongside the peers and orderers. Check the CA database backend and the mutual TLS client certificates that protect operations endpoints. If MSP keys sit in an HSM, confirm a PKCS#11 build, because prebuilt Docker images do not include PKCS#11 and custom images need retesting for each target release.
Rehearsal, sequence and rollback
Run the full procedure on a non-production copy of the network first. Production then follows four steps: back up the ledger and MSPs, roll orderer binaries, roll peer binaries, and update channel capability levels. Agree rollback criteria before the window opens, covering health check failures, endorsement or ordering errors, and which steps can be reversed without a restore.
Runbook, evidence and handover
Deliverables include an upgrade runbook, backup and restore evidence showing a tested restore, and a change record for each node. After go-live, support covers monitoring through the operations service, patch tracking on the chosen line, and handover of runbooks to your operators. Confirm the support period and response expectations in the written scope.
What drives upgrade cost and duration
This table lists the factors that change how much work and coordination a Fabric upgrade needs, with practical ways to keep each one under control.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Organizations and nodes in change windows | Every member organization must approve, and every orderer and peer must be upgraded in a rolling sequence, so effort grows with membership and node count. | Agree a standard change window and runbook once, and keep the number of nodes per organization to what resilience requires. |
| Channels and capability levels | Each application channel has its own capability level that must be raised after binaries are upgraded, and each channel needs its own verification. | Keep channel count small, group workloads by channel where the business allows, and plan capability updates as one reviewed step. |
| Chaincode count and custom builders or images | Chaincode packages and external builders may need retesting against the new peer, and custom images must be rebuilt for every release. | Track chaincode versions in a shared inventory, pin external builder versions, and limit custom image changes to what the HSM setup truly needs. |
| HSM-backed MSP keys | Prebuilt Docker images are not built with PKCS#11, so HSM-backed peers and orderers need custom images that must be rebuilt, retested and signed off for each upgrade. | Build and test the custom image pipeline before the upgrade window, and confirm HSM vendor client compatibility with the target release. |
| Client applications and release cadence | The Gateway client API works with both v2.5 and v3.0, so clients can move separately, but every application team adds coordination and testing. | Upgrade clients on their own schedule after the network is stable, and agree a compatibility test suite that all application teams run. |
| Environments to rehearse | Each environment such as development, test, staging and production needs its own rehearsal of backup, binary upgrade and capability update. | Keep environments built from the same deployment code, and reuse the same runbook and scripts in every rehearsal. |
| Governance steps before approval | Members usually need documented change requests, impact reviews and sign-off through consortium governance before any node changes, which can take longer than the technical work. | Pre-approve a change template with the consortium, define who votes on what, and set a fixed schedule for governance decisions. |
Upgrade and support phases and their outputs
The sequence moves a Fabric network to its chosen release line with a recorded decision, a tested runbook, consortium approval and a verified result at each stage.
Assess the current version and target line
Inventory every orderer, peer, Fabric CA and client application with its binary version, channel capability levels and chaincode lifecycle. Confirm that Kafka ordering has already moved to Raft and that all channels use the v2.x lifecycle, since v3.0 removed both. The output is a version and gap assessment that the consortium signs off before planning begins.
Record the 2.5 LTS or 3.x decision
Compare the 2.5 LTS line, which the Fabric documentation describes as the long-term support release for production users, with the 3.x line. Consider whether you need the BFT ordering service or Ed25519 MSP signing added in v3.0. Check the Fabric releases page on the decision date, because both lines receive patch releases. The output is a decision record naming the target version, the reasons and a review date.
Rehearse the upgrade on production-like data
Restore a recent backup of the ledger and MSPs into an isolated environment that matches the production topology. Run the full rolling sequence, then the chaincode and client application tests. Record errors, timings and any manual steps. The output is a rehearsal report listing each deviation from the runbook and how it was resolved. Ask your consortium how it will schedule rehearsals in its own environment.
Obtain consortium change approval
Each member organization reviews the rehearsal report, the rollback plan and the proposed upgrade window, then approves the change in writing. Confirm that every organization operating an orderer or peer has named an owner for its node. The output is a signed change plan that fixes the node order, the backup points and the go or no-go criteria.
Upgrade orderers and peers in rolling order
Back up the ledger and MSPs before each node changes. Upgrade orderer binaries one node at a time so the Raft majority stays available, then upgrade peers organization by organization. Follow the rehearsed runbook and check each node's /healthz and /version output before moving on. The output is a runbook execution log with a health check result for every node.
Update capability levels and verify channels
After every binary runs the new version, raise the application channel capability levels as the upgrade guide describes, one channel at a time. Confirm that endorsement, ledger queries and chaincode invocations succeed from each organization's client application. The output is post-change verification results for each channel, with the capability level recorded.
Run hypercare and hand over support
Keep heightened monitoring and on-call cover for a period the consortium agrees in advance, watching operations service metrics, logs and certificate expiry dates. Close open issues, then transfer the runbook, alert thresholds and contacts to steady-state support, which covers patching, backups and certificate renewal. The output is a support handover document signed by each member's operations owner.
What teams keep in-house and what they outsource
This table shows which parts of a Fabric upgrade and support program each party usually owns, and the skills each part requires, so you can decide where to staff internally and where to bring in a partner.
| Work area | Usual owner | Skills required |
|---|---|---|
| Consortium governance and change approval | In-house, each member organization | Governance of channel policies and endorsement rules, change records, decision authority per member, familiarity with Fabric lifecycle and capability levels |
| Node operation and access | In-house, each member organization | Fabric operations on peers and orderers, Linux administration, Kubernetes or VM operations, access control for MSP and TLS keys |
| Upgrade planning and rehearsal | Often outsourced for a first upgrade, then handed over | Fabric release management, reading upgrade notes for 2.5 LTS and 3.x, building a test network that mirrors production, Go or Node.js familiarity for client changes |
| Production change execution across organizations | Shared, with a partner coordinating | Rolling orderer and peer upgrades in agreed order, Linux and container operations, coordinated maintenance windows, rollback procedures across members |
| Backup design and restore testing | Often outsourced, then handed over | Ledger and MSP backup design, PostgreSQL or file-level backup tooling for CA databases, restore drills, PKI and certificate handling |
| Support retainers after go-live | Partner or internal, decided by staffing depth | Fabric operations service monitoring, PKI and certificate renewal, chaincode and client application troubleshooting, on-call coverage across time zones |
| Chaincode and client application changes | In-house, with partner review where needed | Chaincode in Go or Node.js, Fabric Gateway client API, testing against both 2.5 and 3.x during transition |
What usually goes wrong during Fabric upgrades
Most Fabric upgrade incidents trace back to a few predictable gaps: unverified backups, out-of-order steps, version drift and assumptions built for the old release. Each card names the check that prevents it.
Upgrading without a verified backup
Teams often take a ledger and MSP backup but never restore it. Before each orderer or peer change, restore the backup into an isolated test environment and confirm the node starts, joins its channels and reports the expected block height. Set a written go or no-go criterion so a failed restore stops the change window.
Channel capability update out of sequence
Channel capability levels should change only after every orderer and peer on the channel runs the new binaries. Applying the update early can block nodes that still run the old release. Record which organizations have upgraded, and make the capability update a separate, approved step with its own sign-off.
Mixed binary versions beyond the release notes
A rolling upgrade passes through a period where orderers and peers run different versions. Only the version combinations listed in the release notes are supported during that window. Inventory every node's version before each step, and do not extend the mixed period past what the upgrade guide allows.
Chaincode and client incompatibilities found late
Chaincode built against the old shim, and client applications built on older SDKs, can fail only after the network moves. Test endorsement and invocation of every production chaincode on a staging network at the target version. Client applications can be upgraded separately, but the Gateway client compatibility must be confirmed for each release pair.
Custom images and monitoring left on the old release
Custom peer or orderer images, such as those built for PKCS#11 HSM access, must be rebuilt on the new base image, or they will not start. Operations service endpoints, health checks and Prometheus scrape rules can also break without an error. Rebuild the images and run a monitoring check on every node after each change.
Ordering quorum lost during a rolling step
A Raft cluster keeps working only while a majority of its nodes are available. If an orderer is already down before the rolling restart begins, the next restart can remove quorum. Confirm every orderer is healthy and reachable before each step, and pause the change if any node is missing.
How the upgrade differs by starting point
A network that stays on the 2.5 LTS line receives patch releases only, such as v2.5.16, which was published on June 18, 2026 alongside v3.1.5. The sequence is the same four steps used for any upgrade, but the goal is to stay compatible with the current line.
- Check the target patch on the Fabric releases page before you schedule the window.
- Back up the ledger and MSPs on every node, then roll orderers before peers, one node at a time.
- Confirm that channel capability levels stay where they are, since a patch should not require a capability change.
- Confirm that Fabric Gateway client applications on your side remain compatible with 2.5.
- Agree in writing who watches the patch feed, who approves each window and how long a patch can wait.
Moving to 3.x changes the binaries and the capability levels, so the sequence needs more checkpoints. Prerequisites such as Kafka ordering and the legacy lifecycle are covered on the migration page. This tab covers the upgrade itself.
- Back up the ledger and MSPs, then upgrade orderer binaries in a rolling order, then upgrade peer binaries in a rolling order.
- Update application channel capability levels only after every node runs 3.x, and decide the timing for each channel.
- Review the Ed25519 option added alongside ECDSA for MSP signing, and confirm your CAs and clients support it before you change anything.
- Run the full sequence on a non-production copy of the network first.
- Confirm the BFT ordering service is a separate design decision, so it does not get folded into the upgrade.
On Kubernetes, an operator usually applies the binary change, so the team has to confirm which operator version supports the target Fabric image. HSM-backed MSP keys also require custom images, because the prebuilt images are not built with PKCS#11.
- Confirm which operator and version manage your peers and orderers, and whether that operator supports the target image.
- Rebuild each custom image for the target version with PKCS#11 support, then push it to your internal registry.
- Keep TLS keys file-based and limit the HSM to MSP keys, as the HSM guidance requires.
- Update the image on one node at a time and check health before you move to the next.
- Back up ledgers and MSPs from persistent volumes before each step, and store the copies outside the cluster.
On virtual machines or bare metal, the team replaces binaries and restarts services directly. You control the host, the service units and the timing, so the work depends on how well each host is documented before the change.
- Inventory the binaries, configuration files and service units on every node so you know exactly what changes.
- Confirm that the upgraded binary matches the release you chose and that configuration templates are updated to match it.
- Stop, replace and start one node at a time, and check the health endpoint before you continue.
- Copy the ledger and MSP directories off each host before the step, and test that a restore works.
- Schedule operating system and dependency updates separately from Fabric binary changes.
In an air-gapped network, the team cannot pull patches from the project directly. Artifacts arrive through your transfer process, and the team verifies them inside the enclave before any node changes.
- Define how release artifacts are downloaded outside the enclave, scanned and imported, and record each transfer in the change file.
- Verify checksums or signatures against the values your release process expects, and keep the evidence with the change record.
- Mirror container images into the internal registry and rebuild custom images from source inside the enclave.
- Confirm that the operations service health and version endpoints remain reachable from your internal monitoring.
- Keep the same four-step sequence, and schedule transfers far enough ahead of the change window to finish verification.
What the client needs to provide
Before an upgrade or support engagement starts, each member organization needs to name an owner for its orderer and peer nodes. That owner answers configuration questions, approves changes to their node, and can act during the change window. The consortium also agrees one change window that every member accepts, because a rolling upgrade of orderers and then peers only works when members can be reached during the same period. Ask each member to confirm its window in writing.
The team doing the work needs an accurate picture of the network as it is today. Provide the current inventory of Fabric versions on every orderer and peer, the channel capability levels of each application channel, and the versions of chaincode and client applications, including any client built on the Fabric Gateway client API. Access to non-production copies of the network, with ledger and MSP data close to production, lets the team rehearse each step. Confirm which Fabric release notes each member has reviewed and accepts before testing begins.
Backups and observability are inputs too. Each member should confirm where ledger and MSP backups are stored, that restores have been tested by someone other than the person who made the backup, and who can run a restore. The team also needs read access to the operations service health checks, logs and Prometheus metrics for every node, plus the alert routes that page the right owner. Without these, the team cannot verify a step before moving to the next one.
The first upgrade usually takes the most consortium time, because members have to agree on the sequence, the rollback trigger and the test evidence they will accept. Decide before go-live who answers at night, who approves a rollback, and who signs the go or no-go decision for each step. Record these roles in the support model. A named decision maker who can say no is more useful than a committee that meets after the window closes.
Frequently asked questions about Fabric upgrades and support
Should we stay on Hyperledger Fabric 2.5 LTS or move to 3.x?
Stay on 2.5 LTS if you need the line the Fabric documentation names for production users today and have no 3.x-only requirement. Move to 3.x when a requirement sits there, such as BFT ordering based on SmartBFT or Ed25519 MSP signing. Either way, Kafka ordering must be migrated to Raft and all channels must use the v2.x lifecycle before the upgrade. Both lines receive patch releases in parallel, so the choice turns on features and migration readiness.
Can one organization upgrade its own Fabric nodes without the consortium?
Yes for the binaries on nodes that organization operates, but network-wide steps need the consortium. Each organization can upgrade the orderer and peer binaries it runs, one node at a time, as the rolling upgrade steps describe. Channel capability levels are different: they govern rules for every member of a channel, so the channel's organizations must agree before anyone changes them. Agree the sequence, backups and rollback with the consortium before the first node changes, since mixed versions run during the rollout.
How long does a Hyperledger Fabric upgrade take?
The duration depends on your topology, so ask for a timeline built from your node count and channel list, since no generic figure is reliable. The main drivers are the number of orderers and peers, the number of channels and chaincode definitions to check, any prerequisite migrations, and how many organizations must coordinate their own rolling steps. HSM-backed keys, custom images and monitoring changes add verification work. The four documented steps are backup, orderer binaries, peer binaries and channel capability updates, and each repeats across nodes and environments.
What must our team provide before a Fabric upgrade engagement starts?
Your team must provide access, current state and decision owners before work begins, and the written scope will list the exact items. Expect to supply an inventory of orderer and peer versions, channel configurations, chaincode definitions and lifecycle status, plus the Fabric CA and MSP layout. Access to nodes, backup storage and HSM or key management details is needed to test backups before the first change. Named people from each consortium organization must approve maintenance windows and channel capability decisions.
Can an in-house team run a Fabric upgrade without outside help?
Yes, if the team has operated Fabric before, has tested backup and restore, and has the time and an organizational peer to coordinate with. The upgrade follows documented steps, so the skill gap is usually in preparation: confirming Kafka and legacy lifecycle migrations are complete, checking custom images and PKCS#11 builds, and reviewing channel policies. A dry run on a non-production copy lets the team practice the sequence before production. Independent review of the plan is another option if the team wants a second check before the change window.
How do we compare upgrade quotes and post go-live support terms?
Compare quotes line by line against the same written scope, including the topology, channels, environments and each upgrade step. Check whether post go-live support covers the agreed work, such as health checks and metrics review after the change, and whether a retainer for ongoing support, patch upgrades or continuous testing is priced separately. Ask who performs backups and restore tests, which assumptions the quote relies on and what changes trigger a new estimate. DeployOpen does not publish prices, so each quote follows from the written scope.
How DeployOpen scopes, delivers and supports Fabric upgrades
DeployOpen plans and carries out Hyperledger Fabric upgrades inside the infrastructure you control, starting from a written scope that names the release line, the nodes and the channels in play. Support after the upgrade can be set up as a retainer that covers patch releases and later changes.
How we scope
- Engagements are fixed-scope, with the upgrade path, nodes, channels and deliverables agreed in writing before work starts.
- We inventory every orderer, peer, Fabric CA and client application, and confirm which Fabric release each one runs today.
- We check prerequisites such as Kafka ordering moved to Raft and all channels on the v2.x lifecycle before any binary changes.
How we build
- We back up the ledger and MSPs for each node and verify that the backups can be restored in a test environment first.
- We upgrade orderer binaries and then peer binaries one node at a time, checking health and logs before moving to the next node.
- We update application channel capability levels only after all nodes run the target release, and we test client applications against the Fabric Gateway client API.
How we hand over
- You receive a runbook with the upgrade sequence, rollback points, backup locations and the checks run at each step.
- We document the release line you chose, including whether you stay on 2.5 LTS or move to 3.x, and the reasons behind that choice.
- We walk your operators through the operations service health checks, version endpoints and alerts used to confirm the upgrade.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, which can cover patch releases on your chosen line.
- Support scope is agreed in writing, so you can confirm which patch releases, reviews and on-call hours are included before you sign.
- Ask for a quote based on your written scope, including what recurs each year and which items are one-time work.
