Docs: Setting up a HA notary (#1169)

Minor fixes: rename Notary -> notary, replica -> worker.
This commit is contained in:
Andrius Dagys 2018-07-02 10:38:56 +01:00 committed by GitHub
parent b48c691abb
commit b45472d579
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 54 additions and 52 deletions

View File

@ -54,7 +54,7 @@ Configuration
Configure the MySQL Root Password (if necessary)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some distros allow root access to the database through a Unix domain socket, others
Some distributions allow root access to the database through a Unix domain socket, others
require you to find the temporary password in the log file and change it upon
first login.

View File

@ -8,27 +8,25 @@ Expected Outcome
~~~~~~~~~~~~~~~~
You will go from a set of configuration files to a fully functional Corda network.
The network map will be advertising the service identity of the Notary. Every
notary replica has obtained its own identity and the shared service identity
The network map will be advertising the service identity of the notary. Every
notary worker has obtained its own identity and the shared service identity
from the doorman.
Using the registration tool, you will obtain the serivce identity of your notary
cluster and distribute it to the keystores of all replicas of your notary
cluster.
Using the registration tool, you will obtain the service identity of your notary
cluster and distribute it to the keystores of all worker nodes.
The individual node identity is used by the messaging layer to route requests to
individual notary replicas. The notary replicas sign using the service identity
private key.
specific workers. The workers sign transactions using the service identity private key.
======== =========================== ===========================
Host Individual identity Service identity
======== =========================== ===========================
notary-1 O=Replica 1, L=London, C=GB O=HA Notary, L=London, C=GB
notary-2 O=Replica 2, L=London, C=GB O=HA Notary, L=London, C=GB
notary-3 O=Replica 3, L=London, C=GB O=HA Notary, L=London, C=GB
======== =========================== ===========================
======== ========================== ===========================
Host Individual identity Service identity
======== ========================== ===========================
notary-1 O=Worker 1, L=London, C=GB O=HA Notary, L=London, C=GB
notary-2 O=Worker 2, L=London, C=GB O=HA Notary, L=London, C=GB
notary-3 O=Worker 3, L=London, C=GB O=HA Notary, L=London, C=GB
======== ========================== ===========================
The notaries will be visible and available on the network. To list available notary
The notary workers will be visible and available on the network. To list available notary
identities using the Corda node shell
.. code:: sh
@ -43,7 +41,7 @@ CorDapp developers should select the notary service identity from the network ma
serviceHub.networkMapCache.getNotary(CordaX500Name("HA Notary", "London", "GB"))
Every notary replica's keystore contains the private key of the replica and the
Every notary worker's keystore contains the private key of the replica and the
private key of the notary service (with aliases ``identity-private-key`` and
``distributed-notary-private key`` in the keystore). We're going to create and
populate the node's keystores later in this tutorial.
@ -52,7 +50,7 @@ The Notary, the Doorman and the Network Map
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The notary is an essential component of every Corda network, therefore the
Notary identity needs to be created first, before other nodes can join the
notary identity needs to be created first, before other nodes can join the
network, since the Notary identity is part of the network parameters.
Adding a Corda notary to an existing network is covered in
the network services documentation (TBD where this is hosted). Removing a notary from a network
@ -76,9 +74,9 @@ Registering with the Doorman
Obtaining the individual Node Identities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Write the configuration files for your replicas as described in :doc:`installing-the-notary-service`.
Write the configuration files for your notary nodes as described in :doc:`installing-the-notary-service`.
Register all the notary replicas with the doorman using the ``--initial-registration`` flag.
Register all the nodes with the doorman using the ``--initial-registration`` flag.
.. code:: sh
@ -91,7 +89,7 @@ Obtaining the distributed Service Identity
Once you completed the initial registration for all notary nodes, you can use
the registration tool to submit the certificate signing request (CSR) for the
service identity of your notary cluster. Read the documentation about the
service identity of your notary cluster. Read the documentation about the
`registration tool <https://github.com/corda/network-services/tree/master/registration-tool>`__
for detailed instructions.

View File

@ -4,7 +4,7 @@ Setting up the Notary Service
In the previous section of this tutorial we set up a Percona cluster.
On top of the Percona cluster we're deploying three Corda Enterprise Notary nodes ``notary-{1,2,3}`` and
On top of the Percona cluster we're deploying three notary worker nodes ``notary-{1,2,3}`` and
a single regular Corda node ``node-1`` that runs the notary health-check CorDapp.
If you're deploying VMs in your environment you might need to adjust the host names accordingly.

View File

@ -6,13 +6,13 @@ About the HA Notary Installation
================================
In this chapter you'll learn how to set up, configure and start a highly
available (HA) Corda Enterprise Notary from scratch. If you're targeting an
available (HA) Corda Enterprise notary service from scratch. If you're targeting an
environment with doorman and network map, you require the registration tool. If
you don't require the doorman and network map, and you don't want to join an
existing network, the bootstrapper allows you to set up a cluster of nodes from
a set of configuration files.
The HA Notary relies on a Percona/XtraDB (Percona) cluster. How to set up Percona
The HA notary relies on a Percona/XtraDB (Percona) cluster. How to set up Percona
is described below.
This guide assumes you're running a Debian-based Linux OS.
@ -26,23 +26,27 @@ Overview
.. image:: resources/ha-notary-overview2.png
:scale: 75 %
The figure above displays the Corda nodes in green on the top, then the Corda
notaries in red in the middle and on the bottom are the Percona nodes in blue.
The figure above displays Corda client nodes in green on the top, then the Corda
notary worker nodes in red in the middle and on the bottom are the Percona nodes in blue.
Corda nodes that request a notarisation by the service name of the Notary,
will connect to the available Notary nodes in a round-robin fashion.
Client nodes that request a notarisation by the service name of the notary,
will connect to the available worker nodes in a round-robin fashion.
Since our Notary cluster consists of several Percona nodes and several Corda
Notary nodes, we achieve high availability (HA). Individual nodes of the
Percona and Notary clusters can fail, while clients are still able to
notarise transactions. The Notary cluster remains available. A three-node
The task of a worker node is to verify the notarisation request, the transaction timestamp (if present),
and resolve and verify the transaction chain (if the notary service is validating). It then commits the
transaction's input states to the Percona database.
Since our notary cluster consists of several Percona nodes and several
worker nodes, we achieve high availability (HA). Individual nodes of the
Percona and notary clusters can fail, while clients are still able to
notarise transactions. The notary cluster remains available. A three-node
Percona cluster as shown in the figure above can tolerate one crash fault.
.. note::
In production you should consider running five nodes or more, to be able to
tolerate more than one simultaneous crash fault. One single Corda Notary
replica is enough to serve traffic in principal, although its capacity might
tolerate more than one simultaneous crash fault. One single Corda notary
worker is enough to serve traffic in principle, although its capacity might
not be sufficient, depending on your throughput and latency requirements.
Colocating Percona and the Notary Service
@ -51,34 +55,34 @@ Colocating Percona and the Notary Service
.. image:: resources/percona-colocated.png
:scale: 50%
You can run a Percona DB service and a Corda Notary service on the same machine.
You can run a Percona Server and a Corda notary worker on the same machine.
Summary
+++++++
* Corda nodes communicate with the Notary cluster via P2P messaging, the messaging layer handles selecting an appropriate Notary replica by the service legal name.
* Corda nodes connect to the Notary cluster members round-robin.
* The notaries communicate with the underlying Percona cluster via JDBC.
* Client nodes communicate with the notary cluster via P2P messaging, the messaging layer handles selecting an appropriate notary worker node by the service legal name.
* Client nodes connect to the notary cluster members round-robin.
* The notary worker nodes communicate with the underlying Percona cluster via JDBC.
* The Percona nodes communicate with each other via group communication (GComm).
* The Percona replicas should only be reachable from each other and from the Notary nodes.
* The Notary P2P ports should be reachable from the internet (or at least from the rest of the Corda network you're building or joining).
* We recommend running the notaries and the Percona service in a joined private subnet, opening up the P2P ports of the notaries for external traffic.
* The Percona replicas should only be reachable from each other and from the worker nodes.
* The worker P2P ports should be reachable from the internet (or at least from the rest of the Corda network you're building or joining).
* We recommend running the worker nodes and the Percona service in a joined private subnet, opening up the P2P ports of the workers for external traffic.
Legal Names and Identities
++++++++++++++++++++++++++
Every Notary replica has two legal names. Its own legal name, specified by
``myLegalName``, e.g ``O=Replica 1, C=GB, L=London`` and the service legal name
Every notary worker node has two legal names. Its own legal name, specified by
``myLegalName``, e.g ``O=Worker 1, C=GB, L=London`` and the service legal name
specified in configuration by ``notary.serviceLegalName``, e.g. ``O=HA Notary,
C=GB, L=London``. Only the service legal name is included in the network
parameters. CorDapp developers should select the Notary service identity from the network map cache.
parameters. CorDapp developers should select the notary service identity from the network map cache.
.. code:: kotlin
serviceHub.networkMapCache.getNotary(CordaX500Name("HA Notary", "London", "GB"))
Every Notary replica's keystore contains the private key of the replica and the
private key of the Notary service (with aliases ``identity-private-key`` and
Every notary worker's keystore contains the private key of the worker and the
private key of the notary service (with aliases ``identity-private-key`` and
``distributed-notary-private key`` in the keystore). We're going to create and
populate the node's keystores later in this tutorial.
@ -96,7 +100,7 @@ Choosing Installation Path
Expected Data Volume
====================
For non-validating notaries the Notary stores roughly one kilobyte per transaction.
For non-validating notaries the notary stores roughly one kilobyte per transaction.
Prerequisites
=============
@ -108,7 +112,7 @@ Prerequisites
* Network Registration tool (only required when setting up a network with doorman and network map)
* Root access to a Linux machine or VM to install Percona
* The private IP addresses of your DB hosts (where we're going to install Percona)
* The public IP addresses of your Notary hosts (in order to advertise these IPs for P2P traffic)
* The public IP addresses of your notary hosts (in order to advertise these IPs for P2P traffic)
Your Corda distribution should contain all the JARs listed above.
@ -126,7 +130,7 @@ keep them safe.
Password or Keystore Description
================================ ============================================================================================================
database root password used to create the Corda user, setting up the DB and tables (only required for some installation methods)
Corda DB user password used by the Notary service to access the DB
Corda DB user password used by the notary service to access the DB
SST DB user password used by the Percona cluster for data replication (SST stands for state snapshot transfer)
Network root truststore password (not required when using the bootstrapper)
Node keystore password (not required when using the bootstrapper)
@ -141,7 +145,7 @@ Percona Cluster
===== =======================
Port Purpose
===== =======================
3306 MySQL client connections (from the Corda Notary nodes)
3306 MySQL client connections (from the Corda notary nodes)
4444 SST via rsync and Percona XtraBackup
4567 Write-set replication traffic (over TCP) and multicast replication (over TCP and UDP)
4568 IST (Incremental State Transfer)
@ -160,7 +164,7 @@ P2P Port 10002 P2P traffic (external)
RPC Port 10003 RPC traffic (internal only)
========= ======= ==============================
Later in the tutorial we're covering the Notary service configuration in details, in :doc:`installing-the-notary-service`.
Later in the tutorial we're covering the notary service configuration in details, in :doc:`installing-the-notary-service`.
Keys and Certificates
+++++++++++++++++++++

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

@ -24,7 +24,7 @@ trustStorePassword = ""
p2pAddress : "{{ fully qualified domain name, e.g. host.example.com (or localhost in development) }}:{{ P2P port }}"
rpcUsers=[]
myLegalName : "O=Replica 1, C=GB, L=London"
myLegalName : "O=Worker 1, C=GB, L=London"
// We recommend using Postgres for the node database, or an other supported
// database that you already have set up. Note that the notarised states

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.6 KiB

After

Width:  |  Height:  |  Size: 4.6 KiB