Configuration file specification: Hyperledger-Fabric

A network.yaml file is the base configuration file designed in the Blockchain Automation Framework for setting up a Fabric DLT network. This file contains all the information related to the infrastructure and network specifications. Below shows its structure. ../_images/TopLevelClass-Fabric.png

Before setting up a Fabric DLT/Blockchain network, this file needs to be updated with the required specifications.

A sample configuration file is provided in the repo path:platforms/hyperledger-fabric/configuration/samples/network-fabricv2.yaml

The configurations are grouped in the following sections for better understanding.

  • type
  • version
  • docker
  • frontend
  • env
  • orderers
  • channels
  • organizations

Here is the snapshot from the sample configuration file

../_images/NetworkYamlFabric1.png

The sections in the sample configuration file are:

type defines the platform choice like corda/fabric, here in the example its Fabric

version defines the version of platform being used. The current Fabric version support is 1.4.8 & 2.2.0

frontend is a flag which defines if frontend is enabled for nodes or not. Its value can only be enabled/disabled. This is only applicable if the sample Supplychain App is being installed.

env section contains the environment type and additional (other than 8443) Ambassador port configuration. Vaule for proxy field under this section can be ‘ambassador’ or ‘haproxy’

The snapshot of the env section with example value is below

  env:
    type: "env_type"              # tag for the environment. Important to run multiple flux on single cluster
    proxy: haproxy                  # values can be 'haproxy' or 'none' (for minikube)
    ambassadorPorts:                # Any additional Ambassador ports can be given here, this is valid only if proxy='ambassador'
      portRange:              # For a range of ports 
        from: 15010 
        to: 15043
    # ports: 15020,15021      # For specific ports
    loadBalancerSourceRanges: # (Optional) Default value is '0.0.0.0/0', this value can be changed to any other IP adres or list (comma-separated without spaces) of IP adresses, this is valid only if proxy='ambassador'
    retry_count: 100                # Retry count for the checks
    external_dns: enabled           # Should be enabled if using external-dns for automatic route configuration

The fields under env section are

Field Description
type Environment type. Can be like dev/test/prod.
proxy Choice of the Cluster Ingress controller. Currently supports 'haproxy' only as 'ambassador' has not been implemented for Fabric
ambassadorPorts Any additional Ambassador ports can be given here. This is only valid if proxy: ambassador
loadBalancerSourceRanges (Optional) Restrict inbound access to a single or list of IP adresses for the public Ambassador ports to enhance BAF network security. This is only valid if proxy: ambassador.
retry_count Retry count for the checks.
external_dns If the cluster has the external DNS service, this has to be set enabled so that the hosted zone is automatically updated.

docker section contains the credentials of the repository where all the required images are built and stored.

The snapshot of the docker section with example values is below

  # Docker registry details where images are stored. This will be used to create k8s secrets
  # Please ensure all required images are built and stored in this registry.
  # Do not check-in docker_password.
  docker:
    url: "docker_url"
    username: "docker_username"
    password: "docker_password"

The fields under docker section are

Field Description
url Docker registry url
username Username credential required for login
password Password credential required for login

NOTE: Please follow these instructions to build and store the docker images before running the Ansible playbooks.


orderers section contains a list of orderers with variables which will expose it for the network.

The snapshot of the orderers section with example values is below

  # Remote connection information for orderer (will be blank or removed for orderer hosting organization)
  orderers:
    - orderer:
      type: orderer
      name: orderer1
      org_name: supplychain               #org_name should match one organization definition below in organizations: key            
      uri: orderer1.org1ambassador.blockchaincloudpoc.com:8443   # Can be external or internal URI for orderer which should be reachable by all peers
      certificate: /home/blockchain-automation-framework/build/orderer1.crt           # Ensure that the directory exists
    - orderer:
      type: orderer
      name: orderer2
      org_name: supplychain               #org_name should match one organization definition below in organizations: key            
      uri: orderer2.org1ambassador.blockchaincloudpoc.com:8443   # Can be external or internal URI for orderer which should be reachable by all peers
      certificate: /home/blockchain-automation-framework/build/orderer2.crt           # Ensure that the directory exists

The fields under the each orderer are

Field Description
name Name of the orderer service
type For Fabric, orderer is the only valid type of orderers.
org_name Name of the organization to which this orderer belongs to
uri Orderer URL
certificate Path to orderer certificate. For inital network setup, ensure that the directory is present, the file need not be present. For adding a new organization, ensure that the file is the crt file of the orderer of the existing network.

The channels sections contains the list of channels mentioning the participating peers of the organizations.

The snapshot of channels section with its fields and sample values is below

    # The channels defined for a network with participating peers in each channel
  channels:
  - channel:
    consortium: SupplyChainConsortium
    channel_name: AllChannel
    orderer: 
      name: supplychain
    participants:
    - organization:
      name: carrier
      type: creator       # creator organization will create the channel and instantiate chaincode, in addition to joining the channel and install chaincode
      org_status: new
      peers:
      - peer:
        name: peer0
        gossipAddress: peer0.carrier-net.org3ambassador.blockchaincloudpoc.com:8443  # External or internal URI of the gossip peer
        peerAddress: peer0.carrier-net.org3ambassador.blockchaincloudpoc.com:8443 # External URI of the peer
      ordererAddress: orderer1.org1ambassador.blockchaincloudpoc.com:8443             # External or internal URI of the orderer
    - organization:      
      name: store
      type: joiner        # joiner organization will only join the channel and install chaincode
      org_status: new
      peers:
      - peer:
        name: peer0
        gossipAddress: peer0.store-net.org3ambassador.blockchaincloudpoc.com:8443
        peerAddress: peer0.store-net.org3ambassador.blockchaincloudpoc.com:8443 # External URI of the peer
      ordererAddress: orderer1.org1ambassador.blockchaincloudpoc.com:8443
    - organization:
      name: warehouse
      type: joiner
      org_status: new
      peers:
      - peer:
        name: peer0
        gossipAddress: peer0.warehouse-net.org2ambassador.blockchaincloudpoc.com:8443
        peerAddress: peer0.warehouse-net.org3ambassador.blockchaincloudpoc.com:8443 # External URI of the peer
      ordererAddress: orderer1.org1ambassador.blockchaincloudpoc.com:8443
    - organization:
      name: manufacturer
      type: joiner
      org_status: new
      peers:
      - peer:
        name: peer0
        gossipAddress: peer0.manufacturer-net.org2ambassador.blockchaincloudpoc.com:8443
        peerAddress: peer0.manufacturer-net.org3ambassador.blockchaincloudpoc.com:8443 # External URI of the peer
      ordererAddress: orderer1.org1ambassador.blockchaincloudpoc.com:8443
    genesis:
      name: OrdererGenesis

The fields under the channel are

Field Description
consortium Name of the consortium, the channel belongs to
channel_name Name of the channel
genesis.name Name of the genesis block
orderer.name Organization name to which the orderer belongs
participants Contains list of organizations participating in the channel

Each organization field under participants field of the channel contains the following fields

Field Description
name Organization name of the peer participating in the channel
type This field can be creator/joiner of channel
org_status new (for inital setup) or existing (for add new org)
ordererAddress URL of the orderer this peer connects to
peer.name Name of the peer
peer.gossipAddress Gossip address of the peer
peer.peerAddress External address of the peer

The organizations section contains the specifications of each organization.

In the sample configuration example, we have five organization under the organizations section

The snapshot of an organization field with sample values is below

  organizations:
    # Specification for the 1st organization. Each organization maps to a VPC and a separate k8s cluster
    - organization:
      name: supplychain
      country: UK
      state: London
      location: London
      subject: "O=Orderer,L=51.50/-0.13/London,C=GB"
      type: orderer
      external_url_suffix: org1ambassador.blockchaincloudpoc.com
      org_status: new
      ca_data:
        url: ca.supplychain-net:7054
        certificate: file/server.crt        # This has not been implemented 
      cloud_provider: aws   # Options: aws, azure, gcp, digitalocean, minikube

Each organization under the organizations section has the following fields.

Field Description
name Name of the organization
country Country of the organization
state State of the organization
location Location of the organization
subject Subject format can be referred at OpenSSL Subject
type This field can be orderer/peer
external_url_suffix Public url suffix of the cluster.
org_status new (for inital setup) or existing (for add new org)
ca_data Contains the certificate authority url and certificate path; this has not been implemented yet
cloud_provider Cloud provider of the Kubernetes cluster for this organization. This field can be aws, azure, gcp or minikube
aws When the organization cluster is on AWS
k8s Kubernetes cluster deployment variables.
vault Contains Hashicorp Vault server address and root-token in the example
gitops Git Repo details which will be used by GitOps/Flux.
services Contains list of services which could ca/peer/orderers/concensus based on the type of organization

For the aws and k8s field the snapshot with sample values is below

      aws:
        access_key: "<aws_access_key>"    # AWS Access key, only used when cloud_provider=aws
        secret_key: "<aws_secret>"        # AWS Secret key, only used when cloud_provider=aws
  
      # Kubernetes cluster deployment variables.
      k8s:        
        region: "<k8s_region>"
        context: "<cluster_context>"
        config_file: "<path_to_k8s_config_file>"

The aws field under each organization contains: (This will be ignored if cloud_provider is not ‘aws’)

Field Description
access_key AWS Access key
secret_key AWS Secret key

The k8s field under each organization contains

Field Description
region Region where the Kubernetes cluster is deployed, e.g : eu-west-1
context Context/Name of the cluster where the organization entities should be deployed
config_file Path to the kubernetes cluster configuration file

For gitops fields the snapshot from the sample configuration file with the example values is below

      # Git Repo details which will be used by GitOps/Flux.
      gitops:
        git_protocol: "https" # Option for git over https or ssh
        git_url: "https://github.com/<username>/blockchain-automation-framework.git" # Gitops htpps or ssh url for flux value files
        branch: "<branch_name>"                                                  # Git branch where release is being made
        release_dir: "platforms/hyperledger-fabric/releases/dev" # Relative Path in the Git repo for flux sync per environment. 
        chart_source: "platforms/hyperledger-fabric/charts"      # Relative Path where the Helm charts are stored in Git repo
        git_repo: "github.com/<username>/blockchain-automation-framework.git" # without https://
        username: "<username>"          # Git Service user who has rights to check-in in all branches
        password: "<password>"          # Git Server user password/personal token (Optional for ssh; Required for https)
        email: "<git_email>"              # Email to use in git config
        private_key: "<path to gitops private key>" # Path to private key (Optional for https; Required for ssh)

The gitops field under each organization contains

Field Description
git_protocol Option for git over https or ssh. Can be https or ssh
git_url SSH or HTTPs url of the repository where flux should be synced
branch Branch of the repository where the Helm Charts and value files are stored
release_dir Relative path where flux should sync files
chart_source Relative path where the helm charts are stored
git_repo Gitops git repo URL https URL for git push like "github.com/hyperledger-labs/blockchain-automation-framework.git"
username Username which has access rights to read/write on repository
password Password of the user which has access rights to read/write on repository (Optional for ssh; Required for https)
email Email of the user to be used in git config
private_key Path to the private key file which has write-access to the git repo (Optional for https; Required for ssh)

The services field for each organization under organizations section of Fabric contains list of services which could be ca/orderers/consensus/peers based on if the type of organization.

Each organization will have a CA service under the service field. The snapshot of CA service with example values is below

      # Services maps to the pods that will be deployed on the k8s cluster
      # This sample is an orderer service and includes a zk-kafka consensus
      services:
        ca:
          name: ca
          subject: "/C=GB/ST=London/L=London/O=Orderer/CN=ca.supplychain-net"
          type: ca
          grpc:
            port: 7054

The fields under ca service are

Field Description
name Certificate Authority service name
subject Subject format can be referred at OpenSSL Subject
type Type must be ca for certification authority
grpc.port Grpc port number

Each organization with type as peer will have a peers service. The snapshot of peers service with example values is below

        peers:
        - peer:
          name: peer0          
          type: anchor    # This can be anchor/nonanchor. Atleast one peer should be anchor peer.         
          gossippeeraddress: peer0.manufacturer-net:7051 # Internal Address of the other peer in same Org for gossip, same peer if there is only one peer 
          peerAddress: peer0.carrier-net.org3ambassador.blockchaincloudpoc.com:8443 # External URI of the peer
          cli: disabled      # Creates a peer cli pod depending upon the (enabled/disabled) tag.         
          grpc:
            port: 7051         
          events:
            port: 7053
          couchdb:
            port: 5984
          restserver:           # This is for the rest-api server
            targetPort: 20001
            port: 20001 
          expressapi:           # This is for the express api server
            targetPort: 3000
            port: 3000
          chaincode:
            name: "chaincode_name" #This has to be replaced with the name of the chaincode
            version: "chaincode_version" #This has to be replaced with the version of the chaincode
            maindirectory: "chaincode_main"  #The main directory where chaincode is needed to be placed
            repository:
              username: "git_username"          # Git Service user who has rights to check-in in all branches
              password: "git_password"
              url: "github.com/hyperledger-labs/blockchain-automation-framework.git"
              branch: develop
              path: "chaincode_src"   #The path to the chaincode 
            arguments: 'chaincode_args' #Arguments to be passed along with the chaincode parameters
            endorsements: "" #Endorsements (if any) provided along with the chaincode

The fields under peer service are

Field Description
name Name of the peer. Must be of the format peer0 for the first peer, peer1 for the second peer and so on.
type Type can be anchor and nonanchor for Peer
gossippeeraddress Gossip address of another peer in the same Organization. If there is only one peer, then use that peer address. Must be internal as the peer is hosted in the same Kubernetes cluster.
peerAddress External address of this peer. Must be the HAProxy qualified address. If using minikube, this can be internal address.
cli Optional field. If enabled will deploy the CLI pod for this Peer. Default is disabled.
grpc.port Grpc port
events.port Events port
couchdb.port Couchdb port
restserver.targetPort Restserver target port
restserver.port Restserver port
expressapi.targetPort Express server target port
expressapi.port Express server port
chaincode.name Name of the chaincode
chaincode.version Version of the chaincode. Please do not use . (dot) in the version.
chaincode.maindirectory Path of main.go file
chaincode.repository.username Username which has access to the git repo containing chaincode
chaincode.repository.password Password of the user which has access to the git repo containing chaincode
services.peer.chaincode.repository.url URL of the git repository containing the chaincode
chaincode.repository.branch Branch in the repository where the chaincode resides
chaincode.repository.path Path of the chaincode in the repository branch
chaincode.arguments Arguments to the chaincode
chaincode.endorsements Endorsements (if any) provided along with the chaincode

The organization with orderer type will have concensus service. The snapshot of consensus service with example values is below

        consensus:
          name: kafka
          type: broker
          replicas: 4
          grpc:
            port: 9092

The fields under consensus service are

Field Description
name Name of the Consensus service. Can be raft or kafka.
type Only for kafka. Consensus service type, only value supported is broker currently
replicas Only for kafka. Replica count of the brokers
grpc.port Only for kafka. Grpc port of consensus service

The organization with orderer type will have orderers service. The snapshot of orderers service with example values is below

        orderers:
        # This sample has multiple orderers as an example.
        # You can use a single orderer for most production implementations.
        - orderer:
          name: orderer1
          type: orderer
          consensus: kafka
          grpc:
            port: 7050
        - orderer:
          name: orderer2
          type: orderer
          consensus: kafka
          grpc:
            port: 7050 

The fields under orderer service are

Field Description
name Name of the Orderer service
type This type must be orderer
consensus Consensus type, for example: kafka, raft
grpc.port Grpc port of orderer

\ ** feature is in future scope