Add release notes for v2.2.1

Signed-off-by: David Enyeart <enyeart@us.ibm.com>

release_notes/v2.2.1.md

@@ -0,0 +1,190 @@
+v2.2.1 Release Notes - TBD, 2020
+================================
+
+What's New in Hyperledger Fabric v2.2.1
+---------------------------------------
+
+Hyperledger Fabric v2.2.1 provides important improvements and fixes, with a focus on the following areas:
+* Management of certificate expirations
+* Hardware security module (HSM) efficiency
+* Upgrade to v2.x
+
+
+Fixes
+-----
+
+**FAB-18163: orderer certificate expiration - TLSHandshakeTimeShift without separate cluster port**
+
+If the TLS certificates of the ordering service nodes expire and are not replaced in time,
+communication between them cannot be established, making it impossible to send
+new transactions to the ordering service. To recover from such a scenario, it is possible
+to configure a backwards timeshift that ordering service nodes will utilize for TLS
+handshakes so that transactions can be processed.
+If the Raft cluster service is sharing the orderer’s main gRPC server port,
+configure the new orderer.yaml `General.TLS.TLSHandshakeTimeShift` property.
+If using a separate cluster listener port,
+configure the orderer.yaml `General.Cluster.TLSHandshakeTimeShift` property.
+
+**FAB-18205: orderer certificate expiration - Permit peer CLI to communicate with orderers with expired TLS certificates**
+
+The change allows peer CLI to communicate with ordering service nodes with expired TLS certificates
+by setting the `--tlsHandshakeTimeShift` flag to a desired backwards timeshift.
+The change applies to the `peer channel fetch` and `peer channel update` commands to allow
+fetching configuration blocks and updating the channel configuration for orderers with expired TLS certificates.
+
+**FAB-18171: orderer certificate expiration - Disregard certificate validity period in intra-orderer communication**
+
+This change makes the orderer cluster authentication infrastructure
+disregard validity periods when comparing certificates, and only regard public keys.
+With this change, an expiring Raft TLS certificate can be replaced
+with a new certificate that has the same public key, without requiring channel configuration updates.
+
+**FAB-18188: peer and orderer certificate expiration - Log expiration date upon startup**
+
+The enrollment, TLS server, and TLS client certificate expiration dates are now logged upon peer and orderer startup.
+
+**peer and orderer PKCS#11 - Drain session pool before creating new sessions**
+
+If an invalid PKCS#11 session was acquired from the session pool,
+a new session would be immediately created instead of attempting to acquire another
+session from the pool.
+This change attempts to uses pooled sessions before creating new ones.
+
+**peer and orderer PKCS#11 - Add object handle cache**
+
+With this change, object handles are cached in the PKCS#11 implementation.
+In support of this change, in addition to pooling idle sessions, the
+provider tracks active sessions. If some condition occurs that results
+in all sessions being closed, cached object handles are no longer valid
+so the handle cache is purged.
+
+**FAB-18208: Do not sign gossip message if membership is empty**
+
+This change suppresses the signing of gossip messages if the message will not get
+sent regardless due to an empty gossip membership. The change reduces CPU consumption
+and eliminates unnecessary calls to an HSM.
+
+**peer and orderer PKCS#11 - Add log message if a key cannot be found**
+
+A debug message is now provided in the bccsp_p11 logger if a key cannot be found in the HSM.
+
+**FAB-18194: peer - Fix service discovery for legacy installed chaincodes**
+
+The service discovery endorsers query may fail with errors
+"failed constructing descriptor for chaincodes" and
+"required chaincodes are not installed on sufficient peers", even
+when a chaincode is installed on a sufficient number of peers.
+The peer initialization has been fixed so that chaincodes installed with the legacy chaincode
+lifecycle are correctly recognized by service discovery.
+
+**FAB-18191: peer - Remove contents of leveldb directory instead of the directory when dropping databases**
+
+The peer `upgrade-dbs`, `rebuild-dbs`, `reset`, and `rollback` commands each drop a peer's
+leveldb databases so that they can be rebuilt upon the next peer startup.
+The commands now remove all contents of the leveldb directories, rather than dropping the
+directory itself. This fix is required if mounting one of the leveldb directories in addition
+to the overall peer data directory as specified in core.yaml `peer.fileSystemPath`.
+
+**FAB-15810: peer - Deprioritize fetching of missing private data**
+
+The private data reconciler attempts to retrieve missing private data from other
+peers in a channel that belong to the same private data collection based on the interval
+configured in core.yaml `peer.gossip.pvtData.reconcileSleepInterval`
+(by default every one minute). If private data cannot be reconciled, it will be attempted
+every interval and may block the reconciliation of other private data. This fix places
+private data that can't be reconciled in a depriorized queue so that other private data
+can be reconciled. The depriorized entries will be re-attempted less often based on the
+interval configured in core.yaml `ledger.pvtdataStore.deprioritizedDataReconcilerInterval`
+(by default every 60 minutes).
+
+**orderer - Check suspect info once per suspect interval when using Raft**
+
+The Raft-based ordering service node was checking to see if it was evicted too often.
+This fix ensures that the ordering service node only checks once per suspect interval,
+which is every 10 minutes by default.
+
+**cryptogen - Duplicate alternate names in multi-domain certificates**
+
+When using cryptogen to generate certificates, the X509v3 Subject Alternative Name field contained duplicate entries.
+The Subject Alternative Name now contains one entry per alternate name.
+
+
+Deprecations (existing)
+-----------------------
+
+**FAB-15754: The 'Solo' consensus type is deprecated.**
+
+The 'Solo' consensus type has always been marked non-production and should be in
+use only in test environments, however for compatibility it is still available,
+but may be removed entirely in a future release.
+
+**FAB-16408: The 'Kafka' consensus type is deprecated.**
+
+The 'Raft' consensus type was introduced in v1.4.1 and has become the preferred
+production consensus type.  There is a documented and tested migration path from
+Kafka to Raft, and existing users should migrate to the newer Raft consensus type.
+For compatibility with existing deployments, Kafka is still supported,
+but may be removed entirely in a future release.
+Additionally, the fabric-kafka and fabric-zookeeper docker images are no longer updated, maintained, or published.
+
+**Fabric CouchDB image is deprecated**
+
+v2.2.0 added support for CouchDB 3.1.0 as the recommended and tested version of CouchDB.
+If prior versions are utilized, a Warning will appear in peer log.
+Note that CouchDB 3.1.0 requires that an admin username and password be set,
+while this was optional in CouchDB v2.x. See the
+[Fabric CouchDB documentation](https://hyperledger-fabric.readthedocs.io/en/v2.2.0/couchdb_as_state_database.html#couchdb-configuration)
+for configuration details.
+Also note that CouchDB 3.1.0 default max_document_size is reduced to 8MB. Set a higher value if needed in your environment.
+Finally, the fabric-couchdb docker image will not be updated to v3.1.0 and will no longer be updated, maintained, or published.
+Users can utilize the official CouchDB docker image maintained by the Apache CouchDB project instead.
+
+**FAB-7559: Support for specifying orderer endpoints at the global level in channel configuration is deprecated.**
+
+Utilize the new 'OrdererEndpoints' stanza within the channel configuration of an organization instead.
+Configuring orderer endpoints at the organization level accommodates
+scenarios where orderers are run by different organizations. Using
+this configuration ensures that only the TLS CA certificates of that organization
+are used for orderer communications, in contrast to the global channel level endpoints which
+would cause an aggregation of all orderer TLS CA certificates across
+all orderer organizations to be used for orderer communications.
+
+**FAB-17428: Support for configtxgen flag `--outputAnchorPeersUpdate` is deprecated.**
+
+The `--outputAnchorPeersUpdate` mechanism for updating anchor peers has always had
+limitations (for instance, it only works the first time anchor peers are updated).
+Instead, anchor peer updates should be performed through the normal config update flow.
+
+**FAB-15406: The fabric-tools docker image is deprecated**
+
+The fabric-tools docker image will not be published in future Fabric releases.
+Instead of using the fabric-tools docker image, users should utilize the
+published Fabric binaries. The Fabric binaries can be used to make client calls
+to Fabric runtime components, regardless of where the Fabric components are running.
+
+**FAB-15317: Block dissemination via gossip is deprecated**
+
+Block dissemination via gossip is deprecated and may be removed in a future release.
+Fabric peers can be configured to receive blocks directly from an ordering service
+node by using the following configuration:
+```
+peer.gossip.orgLeader: true
+peer.gossip.useLeaderElection: false
+peer.gossip.state.enabled: false
+```
+
+**FAB-15061: Legacy chaincode lifecycle is deprecated**
+
+The legacy chaincode lifecycle from v1.x is deprecated and will be removed
+in a future release. To prepare for the eventual removal, utilize the v2.x
+chaincode lifecycle instead, by enabling V2_0 application capability on all
+channels, and redeploying all chaincodes using the v2.x lifecycle. The new
+chaincode lifecycle provides a more flexible and robust governance model
+for chaincodes. For more details see the
+[documentation for enabling the new lifecycle](https://hyperledger-fabric.readthedocs.io/en/release-2.2/enable_cc_lifecycle.html).
+
+
+Change log
+----------
+For the full list of changes, refer to the release change log:
+https://github.com/hyperledger/fabric/blob/release-2.2/CHANGELOG.md#v221