Adding a New Organization

Adding a new organization to a running Hyperledger Fabric BFT network is a complex, multi-phase production operation. It involves genesis block regeneration, orderer cluster restarts, channel reconfiguration, and chaincode lifecycle updates. This procedure typically requires 5-10 minutes of orchestration with ~1-2 minutes of ordering service unavailability — well beyond the scope of a demo walkthrough.

This section provides an architectural overview of the steps involved.

Why It’s Complex

In Fabric BFT, organizations are embedded in the genesis block — the foundational configuration of the ordering service. Adding a new org means:

  • Genesis must be regenerated — all orderers restart with the new genesis, causing temporary ordering service downtime

  • BFT quorum changes — going from 4 orderers (f=1) to 5 orderers (still f=1) requires all nodes to agree on the new cluster membership

  • Chaincode endorsement policy — must be updated to include the new org, requiring approval from all existing orgs

  • Identity brokering — the new org’s Keycloak must be registered as an Identity Provider in the central Keycloak

Each of these steps has ordering dependencies — they must be executed in sequence, and a failure at any stage requires careful rollback.

High-Level Steps

Adding a 4th organization (e.g., "QuantumLeap") requires these phases:

  1. Infrastructure Deployment — Add the org config to the bootstrap chart, create a values override file, push to Git, and let ArgoCD deploy the new namespace with peer, orderer, CouchDB, Keycloak, and APIs

  2. Crypto & Secret Distribution — Wait for the org enrollment job to complete, then copy org secrets (admin-msp, peer-tls, orderer-msp, orderer-tls) to the central namespace with org-prefixed names

  3. Genesis Block Regeneration — Update configtx.yaml with the new org definition and a 5th orderer in ConsenterMapping, delete the existing genesis ConfigMap, and re-run the genesis job. This causes ~1-2 minutes of ordering service downtime.

  4. Channel Operations — Rejoin all orderers with the new genesis, join the new peer to the channel, and set the anchor peer for the new org

  5. Chaincode Lifecycle — Install the chaincode package on the new peer, approve with an updated endorsement policy (including the new org) at the next sequence number from all orgs, and commit

  6. Identity Brokering — Register the new org’s Keycloak as an OIDC Identity Provider in central Keycloak, create the Organization entry, and link the IDP

Files That Need Updating

A permanent (automated) addition requires changes to 10 files across the bootstrap chart, central chart scripts, and job templates — including configtx.yaml, generate-genesis.sh, copy-org-secrets.sh, channel-setup.sh, chaincode-lifecycle.sh, configure-identity-brokering.sh, and the channel-setup Job template for volume mounts.

Further Reading

  • The existing scripts in helm/components/certchain-central/scripts/ implement each phase for the initial 3-org setup — study them to understand the exact commands

  • The Production Architecture Guide covers the broader architectural considerations

  • Fabric documentation: Adding an Org to a Channel