Hyperledger Fabric migration services

What a Fabric migration covers

Fabric forces three kinds of migration on existing networks. Ordering moves from Kafka to Raft, chaincode moves from the legacy lifecycle to the v2.x lifecycle, and the network moves from the v2.5 LTS line to 3.x. Fabric v3.0 removed the Solo and Kafka consensus options and the v1.x legacy chaincode lifecycle, so a network still using any of them must complete those changes before it upgrades to 3.x. Give the Kafka and lifecycle work its own test and rollback plan, separate from the upgrade itself.

Four situations usually start this work. A consortium runs a Kafka ordering service that has to move to Raft. Some channels still depend on chaincode installed under the legacy lifecycle. The members have decided to adopt 3.x and need the prerequisites finished first. Or the network must leave its current hosting provider or move into air-gapped infrastructure. Each member organization holds its own peers, CA and MSP material, so a hosting move touches every member's keys, certificates and endpoints, and the cutover window depends on how many organizations must act together.

Consortia with in-house Fabric operators and a stable network often keep the migration in-house, since they already hold the ledger, MSP and certificate knowledge the work depends on. Teams with few Fabric staff, a cutover that needs several organizations to act in the same window, or a tight compliance deadline commonly bring in a partner for planning and cutover support. Before you decide, confirm which ordering service and lifecycle each channel uses, which peer and orderer versions run today, and who in each member organization can approve changes.

What the work includes

Five work packages cover the migration steps that Fabric itself requires, from ordering and chaincode through release readiness, hosting and cutover. The sixth card lists what you receive at the end.

Ordering migration from Kafka to Raft

Moves each channel's ordering from Kafka to a Raft cluster, the ordering service Fabric documentation recommends and the only option left after v3.0 removed Kafka. Every orderer operator agrees the consensus and node plan in writing before work starts, covering node count, operator per node, site placement and certificates. Check that the cluster keeps a majority during planned maintenance.

Chaincode lifecycle migration

Inventories every chaincode definition and installed package on each peer, then moves every channel to the v2.x lifecycle before any upgrade step. Endorsement policies are re-checked against the organizations that will sign after cutover. Package handling covers who holds package IDs and how legacy packages are kept for audit. Confirm that no channel still depends on the v1.x lifecycle.

Release line and client readiness

Runs pre-upgrade checks against the current network and records the release-line decision: stay on the v2.5 LTS line or move to 3.x. The decision weighs patch cadence, the need for BFT ordering and whether Ed25519 MSP signing is required. Client applications are tested against the Fabric Gateway client API, which supports both v2.5 and v3.0, so applications can move separately from the network.

Hosting environment move

Moves the network to a new hosting environment as one controlled change covering identities, MSPs, endpoints, DNS, storage and key custody. Where peer or orderer endpoints change, DNS names and TLS certificates must match the new addresses before traffic moves. Key custody is checked against the design: MSP keys can sit in an HSM through PKCS#11, while TLS keys stay file-based and need custom images.

Rehearsal and cutover support

Runs the full migration sequence in a non-production copy of the network before production, recording timings, failures and rollback steps in a rehearsal report. Cutover support covers the agreed change window, on-call coverage for each member organization and go or no-go checkpoints. Ask how the rehearsal copy is refreshed, how its keys are kept separate from production, and who signs the go decision.

Migration deliverables

Each engagement ends with a migration plan, a step-by-step runbook, the rehearsal report, backup and rollback evidence, updated network documentation and handover notes. Backup evidence should show that the ledger and MSPs restore successfully. Before work starts, ask which items each member organization receives and in what format.

What drives cost and duration

This table lists the factors that change migration effort, why each one matters and how to keep it under control, and consortium governance time is often the largest unplanned driver.

Driver	Why it matters	How to keep it down
Member organizations and approvals	Every member must agree on channel membership, policy changes and orderer placement, and each approval adds calendar time.	Map approval steps and decision owners before the plan starts, and agree the change process in writing.
Orderers and ordering model	Kafka ordering must move to Raft before a 3.x upgrade, and each orderer added or removed changes the fault tolerance of the cluster.	Confirm the target consensus model and node count per organization, and rehearse the Kafka to Raft move on a copy first.
Channels and legacy chaincode	Chaincode still on the legacy lifecycle must be moved to the v2.x lifecycle on every channel before the upgrade can proceed.	Inventory channels and chaincode definitions, then migrate each channel and check endorsement policies after each change.
Ledger size and backup window	The upgrade guide starts with backing up the ledger and MSPs, so larger ledgers lengthen every rehearsal and cutover.	Measure ledger size on each peer and orderer, time a full backup and restore in staging, and schedule the window with members.
Environments to rehearse	Test, staging and production each need the full sequence of binary, lifecycle and capability changes, so every extra environment repeats the work.	Keep the same versions, configuration and channel layout across environments so rehearsal results carry into production.
Custom images and PKCS#11 HSM	Prebuilt Docker images lack PKCS#11, so HSM-backed MSP keys need custom images that must be rebuilt for each Fabric release.	Pin the HSM client library and base image, rebuild and scan them on every release, and keep TLS keys file-based as Fabric requires.
Client applications on older SDKs	The Gateway client API is compatible with v2.5 and v3.0, so applications can move separately, but older SDKs need their own testing.	Inventory each application's SDK and version, move to the Gateway client API where possible, and test against staging peers.
Certificate authority backend and certificate state	Fabric CA defaults to SQLite, and expiring enrollment or TLS certificates can stop orderers or peers during a migration.	Check certificate expiry dates and revocation lists first, and plan a move to PostgreSQL or MySQL if the CA runs on SQLite.
Identities and endpoints on the new host	If the hosting move changes peer, orderer or CA endpoints or identities, certificates, MSPs and anchor peer settings must be reissued and reconfigured.	Decide early whether identities stay the same, and confirm with each member how DNS, TLS names and anchor peers will change.

Migration phases and outputs

The sequence moves a Fabric network from its current ordering, lifecycle and release line to a supported target while keeping a tested way back at every stage.

Inventory channels, chaincode, MSPs and keys
The team records every channel, chaincode definition, MSP, certificate authority, HSM dependency and client application, along with the owner of each. Deliverable: a signed inventory showing which components use legacy Kafka ordering, legacy chaincode lifecycle definitions, or PKCS#11 HSM keys. Nothing moves until every organization confirms its list.
Set the target release line and ordering model
The consortium chooses the target line, either the 2.5 LTS line or 3.x, and confirms the ordering model, which is typically Raft because Fabric v3.0 removed Kafka and Solo. The output is a written target design covering orderer count, organization placement, HSM and custom image needs, and client application compatibility. Client applications can be upgraded separately from the network, so their plan is recorded here too.
Rehearse Kafka to Raft and lifecycle changes
The team runs the ordering migration and chaincode lifecycle conversion on a non-production copy of the network that mirrors production topology and data volume. Each rehearsal ends with a test log showing channel continuity, successful endorsements and transactions after the change. Findings feed back into the runbook before any production change is scheduled.
Verify backups, certificates and rollback plan
Before production work, the team restores a copy of the ledger and MSPs to confirm the backups are usable, reviews enrollment and TLS certificate expiry dates for every node and CA, and writes a rollback plan with named decision owners. The output is a signed readiness record that lists verified restore results, certificate dates and the exact rollback trigger conditions.
Run the production cutover in documented order
The change follows the Fabric upgrade sequence: back up the ledger and MSPs, upgrade orderer binaries in a rolling fashion, upgrade peer binaries in a rolling fashion, then update application channel capability levels. Each node is checked for health before the next one changes. The output is a change log with the version and capability state recorded at every step.
Validate and hand over operations
After cutover, the team checks operations service health endpoints, metrics, transaction flow and client application behavior, then compares results with the rehearsal test log. The handover pack contains the final architecture, runbooks, monitoring baselines, certificate renewal calendar and open issues with owners. The migration closes when the consortium signs off the handover.

What usually goes wrong

Most Fabric migration problems come from coordination, certificates, untested recovery paths and artifacts that were not rebuilt for the target release. Each risk below has a prevention step to settle before the cutover window opens.

Ordering plan without a majority

Consortium members must agree on the Kafka-to-Raft migration plan and the cutover window before any ordering node changes. During the move, the ordering service needs a healthy majority of its nodes, so one organization that delays its orderers can stall every channel. Confirm each member's written sign-off, a named window, and a rollback decision point before work starts.

Expired certificates found at cutover

Orderer and peer enrollment and TLS certificates are often checked for the first time during the cutover itself. An expired certificate can stop a node from rejoining the cluster at the worst possible moment. Inventory the expiry date of every certificate on every node and CA well before the window, and renew any that fall inside the migration period.

Backups and HSM keys never tested

A ledger or MSP backup that has never been restored is unproven. The same applies to MSP keys held in an HSM: if nobody has tested how a replacement node or HSM partition is provisioned and reconnected, recovery stalls. Rehearse a full ledger and MSP restore on a non-production copy, and document the HSM recovery steps with the HSM vendor.

Chaincode left on legacy lifecycle

Fabric v3.0 removes the v1.x legacy chaincode lifecycle, so every channel must already run its chaincode under the v2.x lifecycle before the upgrade. Teams often find packages installed with older tooling and approvals recorded in outdated formats. Inventory each chaincode definition per channel, migrate it on a test channel, and confirm every organization has approved the new definitions before upgrading binaries.

Custom images and SDKs left behind

Prebuilt Fabric Docker images are not built with PKCS#11, so networks that keep MSP keys in an HSM need a custom image with that support, rebuilt for each target release. Client applications drift as well: confirm which Fabric Gateway client version each application uses and plan its upgrade on its own schedule. Test both the image and the client against the target network before cutover.

Endpoint and identity changes during a move

When a network moves hosting environments, changed hostnames, IP addresses or TLS endpoints can break peer discovery, because peers and clients rely on recorded addresses and certificate names. Peers may look healthy while gossip with the right members fails. Settle the endpoint map and certificate names before the move, update channel and connection profile references, and check discovery from each organization's side.

How the work differs by starting point

A Kafka-ordered network must leave Kafka before it can run Fabric v3.0, because v3.0 removes Kafka consensus. The work changes the ordering layer, while channels, the ledger and MSPs carry over.

Consensus change: Plan the move to Raft, including how orderer identities and channel consenter sets are updated.
Node placement: Decide which organizations host orderers and where, since cluster tolerance depends on how many nodes you run.
Cluster sizing: A five node Raft cluster tolerates the loss of two nodes. Confirm the node count your consortium needs before committing to hardware.
Orderer replacement rehearsal: Practice replacing an orderer in a non-production copy of the network, with backups taken first.
Kafka retirement: Keep Kafka running until the cutover is verified, then decommission it under your change process.

What you need to provide

Before discovery starts, the client supplies access and material that only the member organizations hold. That means access to every orderer and peer host and to the Fabric CA servers, plus a current inventory of channels, chaincode definitions and MSP material for each organization. Access to ledger backups and MSP backups is needed early, because the migration plan depends on a restorable state that can be checked before any change is made. Inventory is the input most often missing, and its absence is the most common reason discovery runs long. Each gap means a second round of questions to a member who may not have answered the first.

Named owners and change windows. Each member organization names an owner who can approve changes and sign off cutover for that organization. Each member also agrees change windows in writing, since a Raft migration or a rolling binary upgrade cannot proceed on one member's schedule alone. Chaincode developers who can explain lifecycle history, endorsement policies and past package versions should be available during discovery. If the network uses an HSM, provide the vendor, the model, the PKCS#11 library details and the slot configuration. Note that TLS keys stay file-based, so the HSM scope must be stated precisely.

Decisions the client must make. Three decisions shape the whole plan and should be made before scoping is signed. The first is the release line: whether the network moves to the 2.5 LTS line or to 3.x, which affects how much ordering and lifecycle work is needed. The second is the ordering model, Raft or BFT, along with the number of orderers and where they sit across organizations and sites. The third is the hosting target for a move between environments, including the cloud accounts, data centers or clusters that will run the nodes. The target hosting design should be documented in enough detail to test network paths, DNS, storage and certificate subject names.

What to confirm early. Ask each member whether a complete inventory exists and who maintains it. Confirm which Fabric version every node runs today, because the upgrade path depends on it. Ask whether any custom images are in use, since PKCS#11 needs custom images that the prebuilt Docker images do not provide. Confirm that a restore from backup has been tested at least once, not assumed. Ask who in each organization will receive a sign-off request and how quickly that person can respond during a cutover window.

What teams keep and what they outsource

This table shows which parts of a Hyperledger Fabric migration teams usually keep in-house, which they share or outsource, and the skills each part requires, so you can see where a partner adds the most value.

Work part	Usually kept in-house	Usually outsourced or shared	Skills needed
Consortium governance and approvals	Decisions on channel membership, endorsement policy changes and sign-off on the migration window	Partner facilitates workshops, drafts change requests and records approval evidence	Consortium governance, change management, familiarity with Fabric channel and policy configuration
Chaincode inventory and lifecycle changes	Developers own chaincode logic, dependencies and test results for each contract	Partner builds inventory tooling and checks that every channel is on the v2.x lifecycle	Go or other chaincode language skills, Fabric chaincode lifecycle commands, scripting for inventory checks
Ordering migration design	Owner of the target ordering topology and node placement decisions	Partner or an experienced in-house operator designs the Kafka-to-Raft cutover path	Raft operations, consenter set changes, Kafka and Zookeeper familiarity, orderer configuration
Rehearsal and runbook	Operators run rehearsals on their own infrastructure and record timings and failures	Partner writes step-by-step runbooks and reviews rehearsal results with the team	Fabric operations, container and orchestration tooling, change and rollback planning
Production cutover	Internal change owners approve each step and keep authority to halt	Partner is on call during the cutover window and executes agreed steps alongside staff	Raft operations, orderer and peer administration, backup and restore procedures
Post-cutover monitoring and handover	Platform team runs daily monitoring, alert response and on-call rotation	Partner reviews dashboards, alert thresholds and handover documentation	Operations service metrics and health checks, Prometheus or StatsD, log level management
Certificate and key custody decisions	Security and PKI owners decide where MSP and TLS keys live and who holds HSM access	Partner documents options and configures agreed setups, but does not hold keys	Fabric CA administration, PKCS#11 and HSM configuration, container image work for custom peer and orderer builds

Questions buyers ask

What does a Fabric migration cost and what drives it?

Cost follows the written scope, and DeployOpen does not publish a price list. The main drivers are the number of organizations, peers and orderers, the channels and chaincode definitions to move to the v2.x lifecycle, whether Kafka ordering must be replaced with Raft, how many environments need staging and testing, and any HSM or custom image work. Consortium coordination time is often the largest item teams forget to budget. Ask every quote to separate one-time migration work from recurring costs such as node hosting, monitoring, certificate operations and upgrades.

How long does a Fabric migration take from start to finish?

Duration depends on how many member organizations must agree, test and sign off, how many channels are involved, and how many environments must pass through staging before production. No fixed timeline applies across networks. Ask for a phased plan with milestones, a named approval point for each organization, and the test evidence each phase must produce before the next begins. The Fabric upgrade sequence (back up, upgrade orderers, upgrade peers, then update channel capabilities) gives a useful skeleton for that plan.

Does a Fabric migration require network downtime?

Fabric's upgrade guide describes orderer and peer binary upgrades as rolling, so nodes are upgraded one at a time, which reduces the outage risk. Rolling does not mean risk-free. Channel capability updates and any Kafka-to-Raft cutover need planned windows and rehearsal in staging. Before each step, back up the ledger and MSPs and confirm you can restore them. Ask the partner to state in writing which steps they expect to be non-disruptive and which require a maintenance window.

Can our own team run a Fabric migration without an outside partner?

Some teams can, because the Fabric documentation is public. The work requires working operational knowledge of peers, orderers and Fabric CA, plus change control across every member organization, since each one upgrades its own nodes. Assess your team against each migration step, including certificate renewal and rollback. If you bring in a partner, verify Fabric experience by asking for named operational references, a sample upgrade runbook and an explanation of how they handled a failed step. Get the split of responsibilities in writing.

Do we have to move to Fabric 3.x now?

No requirement forces an immediate move, but the timing matters. Fabric v2.5 is the long-term support release for production users, and both the 2.5 and 3.x lines receive patch releases, including v2.5.16 and v3.1.5 published on June 18, 2026. Fabric v3.0 removed Kafka and Solo consensus and the v1.x legacy chaincode lifecycle, so networks still using those must migrate first. Confirm with your consortium which line your support policy allows and the date by which you expect to move.

Does switching from Kafka ordering to Raft require a new network?

Whether a new network is needed depends on your current configuration, so confirm it in writing before planning. Fabric documentation recommends Raft, which keeps working while a majority of ordering nodes are available. A five node Raft cluster tolerates the loss of two nodes. Ask the partner to describe the cutover sequence, the backups taken beforehand and how channels move to the new orderers. Because Fabric v3.0 removed Kafka, this change cannot be deferred if you plan to move to 3.x.

How DeployOpen runs a Fabric migration

DeployOpen plans, builds and documents Hyperledger Fabric migrations inside the infrastructure your consortium controls, following the order Fabric's own upgrade path requires. Engagements are fixed-scope, with the scope agreed in writing before work starts.

How we scope

Inventory every channel, chaincode definition, orderer and peer, and confirm which still use Kafka ordering or legacy lifecycle.
Record the target line, either 2.5 LTS or 3.x, and the ordering model, with Raft or BFT, each organization will run.
Agree in writing which migration steps, environments and organizations are in scope, along with the acceptance tests and documentation to be delivered.

How we build

Migrate Kafka ordering to Raft and move every channel to the v2.x chaincode lifecycle before any Fabric 3.x binary is deployed.
Rehearse the four-step upgrade in a non-production environment: backup, orderer rolling upgrade, peer rolling upgrade, then channel capability levels.
Test endorsement, ordering, gossip and client application connectivity after each step, and confirm MSP keys and HSM integration still work on the target version.

How we hand over

Deliver runbooks for each migration step, the rollback point before each change and the backup and restore procedure for the ledger and MSPs.
Document the final topology, channel configuration, capability levels and certificate expiry dates so your team can operate the network after cutover.
Walk through the operations service checks, health endpoints and log level changes with the teams who will run the network day to day.

How we support

Ask whether post go-live support is covered in the written scope or sold as a retainer, and what response expectations apply.
Plan follow-on patch upgrades on the chosen LTS or 3.x line, and confirm which client applications can move separately through the Fabric Gateway client API.
Agree with your consortium who owns each organization's peers, orderers, certificate authorities and HSMs after handover.

Hyperledger Fabric migration