github.com/kaituanwang/hyperledger@v2.0.1+incompatible/docs/source/discovery-overview.rst (about)

     1  Service Discovery
     2  =================
     3  
     4  Why do we need service discovery?
     5  ---------------------------------
     6  
     7  In order to execute chaincode on peers, submit transactions to orderers, and to
     8  be updated about the status of transactions, applications connect to an API
     9  exposed by an SDK.
    10  
    11  However, the SDK needs a lot of information in order to allow applications to
    12  connect to the relevant network nodes. In addition to the CA and TLS certificates
    13  of the orderers and peers on the channel -- as well as their IP addresses and port
    14  numbers -- it must know the relevant endorsement policies as well as which peers
    15  have the chaincode installed (so the application knows which peers to send chaincode
    16  proposals to).
    17  
    18  Prior to v1.2, this information was statically encoded. However, this implementation
    19  is not dynamically reactive to network changes (such as the addition of peers who have
    20  installed the relevant chaincode, or peers that are temporarily offline). Static
    21  configurations also do not allow applications to react to changes of the
    22  endorsement policy itself (as might happen when a new organization joins a channel).
    23  
    24  In addition, the client application has no way of knowing which peers have updated
    25  ledgers and which do not. As a result, the application might submit proposals to
    26  peers whose ledger data is not in sync with the rest of the network, resulting
    27  in transaction being invalidated upon commit and wasting resources as a consequence.
    28  
    29  The **discovery service** improves this process by having the peers compute
    30  the needed information dynamically and present it to the SDK in a consumable
    31  manner.
    32  
    33  How service discovery works in Fabric
    34  -------------------------------------
    35  
    36  The application is bootstrapped knowing about a group of peers which are
    37  trusted by the application developer/administrator to provide authentic responses
    38  to discovery queries. A good candidate peer to be used by the client application
    39  is one that is in the same organization. Note that in order for peers to be known
    40  to the discovery service, they must have an ``EXTERNAL_ENDPOINT`` defined. To see
    41  how to do this, check out our :doc:`discovery-cli` documentation.
    42  
    43  The application issues a configuration query to the discovery service and obtains
    44  all the static information it would have otherwise needed to communicate with the
    45  rest of the nodes of the network. This information can be refreshed at any point
    46  by sending a subsequent query to the discovery service of a peer.
    47  
    48  The service runs on peers -- not on the application -- and uses the network metadata
    49  information maintained by the gossip communication layer to find out which peers
    50  are online. It also fetches information, such as any relevant endorsement policies,
    51  from the peer's state database.
    52  
    53  With service discovery, applications no longer need to specify which peers they
    54  need endorsements from. The SDK can simply send a query to the discovery service
    55  asking which peers are needed given a channel and a chaincode ID. The discovery
    56  service will then compute a descriptor comprised of two objects:
    57  
    58  1. **Layouts**: a list of groups of peers and a corresponding amount of peers from
    59     each group which should be selected.
    60  2. **Group to peer mapping**: from the groups in the layouts to the peers of the
    61     channel. In practice, each group would most likely be peers that represent
    62     individual organizations, but because the service API is generic and ignorant of
    63     organizations this is just a "group".
    64  
    65  The following is an example of a descriptor from the evaluation of a policy of
    66  ``AND(Org1, Org2)`` where there are two peers in each of the organizations.
    67  
    68  .. code-block:: JSON
    69  
    70     Layouts: [
    71          QuantitiesByGroup: {
    72            “Org1”: 1,
    73            “Org2”: 1,
    74          }
    75     ],
    76     EndorsersByGroups: {
    77       “Org1”: [peer0.org1, peer1.org1],
    78       “Org2”: [peer0.org2, peer1.org2]
    79     }
    80  
    81  In other words, the endorsement policy requires a signature from one peer in Org1
    82  and one peer in Org2. And it provides the names of available peers in those orgs who
    83  can endorse (``peer0`` and ``peer1`` in both Org1 and in Org2).
    84  
    85  The SDK then selects a random layout from the list. In the example above, the
    86  endorsement policy is Org1 ``AND`` Org2. If instead it was an ``OR`` policy, the SDK
    87  would randomly select either Org1 or Org2, since a signature from a peer from either
    88  Org would satisfy the policy.
    89  
    90  After the SDK has selected a layout, it selects from the peers in the layout based on a
    91  criteria specified on the client side (the SDK can do this because it has access to
    92  metadata like ledger height). For example, it can prefer peers with higher ledger heights
    93  over others -- or to exclude peers that the application has discovered to be offline
    94  -- according to the number of peers from each group in the layout. If no single
    95  peer is preferable based on the criteria, the SDK will randomly select from the peers
    96  that best meet the criteria.
    97  
    98  Capabilities of the discovery service
    99  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   100  
   101  The discovery service can respond to the following queries:
   102  
   103  * **Configuration query**: Returns the ``MSPConfig`` of all organizations in the channel
   104    along with the orderer endpoints of the channel.
   105  * **Peer membership query**: Returns the peers that have joined the channel.
   106  * **Endorsement query**: Returns an endorsement descriptor for given chaincode(s) in
   107    a channel.
   108  * **Local peer membership query**: Returns the local membership information of the
   109    peer that responds to the query. By default the client needs to be an administrator
   110    for the peer to respond to this query.
   111  
   112  Special requirements
   113  ~~~~~~~~~~~~~~~~~~~~~~
   114  When the peer is running with TLS enabled the client must provide a TLS certificate when connecting
   115  to the peer. If the peer isn't configured to verify client certificates (clientAuthRequired is false), this TLS certificate
   116  can be self-signed.
   117  
   118  .. Licensed under Creative Commons Attribution 4.0 International License
   119     https://creativecommons.org/licenses/by/4.0/