Configuration file specification: R3 Corda¶
A network.yaml file is the base configuration file for setting up a Corda DLT network. This file contains all the information related to the infrastructure and network specifications. Here is the structure of it.
Before setting up a Corda DLT/Blockchain network, this file needs to be updated with the required specifications.
A sample configuration file is provide in the repo path:platforms/r3-corda/configuration/samples/network-cordav2.yaml
The configurations are grouped in the following sections for better understanding.
- type
- version
- frontend
- env
- docker
- orderers
- organizations
Here is the snapshot from the sample configuration file
The sections in the sample configuration file are
type
defines the platform choice like corda/fabric/quorum. Use corda
for Corda Opensource and corda-enterprise
for Corda Enterprise.
version
defines the version of platform being used, here in example the Corda version is 4.0, the corda version 4.1 and 4.4 is also supported and should be used. Please note only 4.4 is supported for Corda Enterprise.
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. Value for proxy field under this section has to be ‘ambassador’ as ‘haproxy’ has not been implemented for Corda.
The snapshot of the env
section with example values is below
env:
type: "env-type" # tag for the environment. Important to run multiple flux on single cluster
proxy: ambassador # value has to be 'ambassador' as 'haproxy' has not been implemented for Corda
ambassadorPorts: 15010,15020 # Any additional Ambassador ports can be given here, must be comma-separated without spaces, this is valid only if proxy='ambassador'
retry_count: 20 # 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 ambassador only as haproxy has not been implemented for Corda |
ambassadorPorts | Any additional Ambassador ports can be given here; must be comma-separated without spaces like 15010,15020 . This is only valid if proxy: ambassador |
retry_count | Retry count for the checks. Use a large number if your kubernetes cluster is slow. |
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.
For Opensource Corda, the required instructions are found here.
For Corda Enterprise, all Docker images has to be built and stored in a private Docker registry before running the Ansible playbooks. The required instructions are found here.
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.
docker:
url: "<url>"
username: "<username>"
password: "<password>"
The fields under docker
section are
Field | Description |
---|---|
url | Docker registry url. Must be private registry for Corda Enterprise |
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.
The snapshot of the orderers
section with example values is below
# Remote connection information for doorman/idman and networkmap (will be blank or removed for hosting organization)
orderers:
- orderer:
name: doorman
type: doorman
uri: https://doorman.test.corda.blockchaincloudpoc.com:8443
certificate: home_dir/platforms/r3-corda/configuration/build/corda/doorman/tls/ambassador.crt
crlissuer_subject: "CN=Corda TLS CRL Authority,OU=Corda UAT,O=R3 HoldCo LLC,L=New York,C=US"
- orderer:
name: networkmap
type: networkmap
uri: https://networkmap.test.corda.blockchaincloudpoc.com:8443
certificate: home_dir/platforms/r3-corda/configuration/build/corda/networkmap/tls/ambassador.crt
truststore: home_dir/platforms/r3-corda-ent/configuration/build/networkroottruststore.jks #Certificate should be encoded in base64 format
truststore_pass: rootpassword
The orderers
section contains a list of doorman/networkmap which is exposed to the network. Each orderer
has the following fields:
Field | Description |
---|---|
type | For Corda, networkmap and doorman (idman for Corda Enterprise) are the only valid type of orderers. |
name | Only for Corda Enterprise. Name of the idman/networkmap service. |
uri | Doorman/IDman/Networkmap external URL. This should be reachable from all nodes. |
certificate | Absolute path to the public certificates for Doorman/IDman and Networkmap. |
crlissuer_subject | Only for Corda Enterprise Idman. Subject of the CRL Issuer. |
truststore | Only for Corda Enterprise Networkmap. Absolute path to the base64 encoded networkroot truststore. |
truststore_pass | Only for Corda Enterprise Networkmap. Truststore password |
The organizations
section allows specification of one or many organizations that will be connecting to a network. If an organization is also hosting the root of the network (e.g. doorman, membership service, etc), then these services should be listed in this section as well.
In the sample example the 1st Organisation is hosting the root of the network, so the services doorman, nms and notary are listed under the 1st organization’s service.
The snapshot of an organization field with sample values is below
- organization:
name: manufacturer
country: CH
state: Zurich
location: Zurich
subject: "O=Manufacturer,OU=Manufacturer,L=Zurich,C=CH"
type: node
external_url_suffix: test.corda.blockchaincloudpoc.com
cloud_provider: aws # Options: aws, azure, gcp
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 |
subordinate_ca_subject | Only for Corda Enterprise. Subordinate CA Subject for the CENM. |
type | This field can be doorman-nms-notary/node/cenm |
version | Defines the CENM version. Only for Corda Enterprise, must be 1.2 |
external_url_suffix | Public url suffix of the cluster. This is the configured path for the Ambassador Service on the DNS provider. |
cloud_provider | Cloud provider of the Kubernetes cluster for this organization. This field can be aws, azure or gcp |
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. |
credentials | Only for Corda Enterprise Networkmap. Credentials consumed during crypto-material creation |
cordapps (optional) | Cordapps Repo details which will be used to store/fetch cordapps jar Not Implemented for Corda Enterprise |
services | Contains list of services which could be peers/doorman/nms/notary/idman/signer |
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 organisation 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 organisation contains
Field | Description |
---|---|
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_ssh: "git@github.com/<username>/blockchain-automation-framework.git" # Gitops ssh url for flux value files
branch: "<branch_name>" # Git branch where release is being made
release_dir: "platforms/r3-corda/releases/dev" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/r3-corda/charts" # Relative Path where the Helm charts are stored in Git repo
git_push_url: "github.com/<username>/blockchain-automation-framework.git"
username: "<username>" # Git Service user who has rights to check-in in all branches
password: "<password>" # Git Server user password/personal token
email: "<git_email>" # Email to use in git config
private_key: "<path to gitops private key>"
The gitops
field under each organization contains
Field | Description |
---|---|
git_ssh | SSH 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_push_url | Gitops 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 |
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 |
The credentials
field under each organization contains
Field | Description |
---|---|
keystore | Contains passwords for keystores |
truststore | Contains passwords for truststores |
ssl | Contains passwords for ssl keystores |
For organization as type cenm the credential block looks like |
|
```yaml | |
credentials: | |
keystore: | |
keystore: cordacadevpass #notary keystore password | |
idman: password #idman keystore password | |
networkmap: password #networkmap keystore password | |
subordinateca: password #subordinateca keystore password | |
rootca: password # rootca keystore password | |
tlscrlsigner: password #tls-crl-signer keystore password | |
truststore: | |
truststore: trustpass #notary truststore password | |
rootca: password #network root truststore password | |
ssl: password #corda ssl truststore password | |
ssl: | |
networkmap: password #ssl networkmap keystore password | |
idman: password #ssl idman keystore password | |
signer: password #ssl signer keystore password | |
root: password #ssl root keystore password | |
``` | |
For organization as type node the credential section is under peers section and looks like |
|
```yaml | |
credentials: | |
truststore: | |
node: trustpass #node truststore password | |
keystore: | |
node: cordacadevpass #node keystore password | |
``` |
For cordapps fields the snapshot from the sample configuration file with the example values is below: This has not been implented for Corda Enterprise.
# Cordapps Repository details (optional use if cordapps jar are store in a repository)
cordapps:
jars:
- jar:
# e.g https://alm.accenture.com/nexus/repository/AccentureBlockchainFulcrum_Release/com/supplychain/bcc/cordapp-supply-chain/0.1/cordapp-supply-chain-0.1.jar
url:
- jar:
# e.g https://alm.accenture.com/nexus/repository/AccentureBlockchainFulcrum_Release/com/supplychain/bcc/cordapp-contracts-states/0.1/cordapp-contracts-states-0.1.jar
url:
username: "cordapps_repository_username"
password: "cordapps_repository_password"
The cordapps
optional field under each organization contains
Field | Description |
---|---|
jars | Contains list of jars with jar URL that needs to fetched and put into organisation nodes |
username | Cordapps Repository username |
password | Cordapps Repository password |
The services field for each organization under organizations
section of Corda contains list of services
which could be doorman/idman/nms/notary/peers for opensource, and additionally idman/networkmap/signer for Corda Enterprise.
The snapshot of doorman service with example values is below
services:
doorman:
name: doormanskar
subject: "CN=Corda Doorman CA,OU=DLT,O=DLT,L=Berlin,C=DE"
db_subject: "/C=US/ST=California/L=San Francisco/O=My Company Ltd/OU=DBA/CN=mongoDB"
type: doorman
ports:
servicePort: 8080
targetPort: 8080
tls: "on"
The fields under doorman
service are
Field | Description |
---|---|
name | Name for the Doorman service |
subject | Certificate Subject for Doorman service. Subject format can be referred at OpenSSL Subject |
db_subject | Certificate subject for mongodb database of doorman |
type | Service type must be doorman |
ports.servicePort | HTTP port number where doorman service is accessible |
ports.targetPort | HTTP target port number of the doorman docker-container |
tls | On/off based on whether we want TLS on/off for doorman |
The snapshot of nms service example values is below
nms:
name: networkmapskar
subject: "CN=Network Map,OU=FRA,O=FRA,L=Berlin,C=DE"
db_subject: "/C=US/ST=California/L=San Francisco/O=My Company Ltd/OU=DBA/CN=mongoDB"
type: networkmap
ports:
servicePort: 8080
targetPort: 8080
tls: "on"
The fields under nms
service are
Field | Description |
---|---|
name | Name of the NetworkMap service |
subject | Certificate Subject for NetworkMap service. Subject format can be referred at OpenSSL Subject |
db_subject | Certificate subject for mongodb database of nms. |
type | Service type must be networkmap |
ports.servicePort | HTTP port number where NetworkMap service is accessible |
ports.targetPort | HTTP target port number of the NetworkMap docker-container |
tls | On/off based on whether we want TLS on/off for nms |
For Corda Enterprise, following services must be added to CENM Support.
The snapshot of idman service with example values is below
services:
idman:
name: idman
subject: "CN=Test Identity Manager Service Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
crlissuer_subject: "CN=Corda TLS CRL Authority,OU=Corda UAT,O=R3 HoldCo LLC,L=New York,C=US"
type: cenm-idman
port: 10000
The fields under idman
service are
Field | Description |
---|---|
name | Name for the IDman service |
subject | Certificate Subject for Idman service. Subject format can be referred at OpenSSL Subject |
crlissuer_subject | Certificate subject for CRL Issuer service |
type | Service type must be cenm-idman |
port | HTTP port number where idman service is accessible internally |
The snapshot of networkmap service with example values is below
services:
networkmap:
name: networkmap
subject: "CN=Test Network Map Service Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
type: cenm-networkmap
ports:
servicePort: 10000
targetPort: 10000
The fields under networkmap
service are
Field | Description |
---|---|
name | Name for the Networkmap service |
subject | Certificate Subject for Networkmap service. Subject format can be referred at OpenSSL Subject |
type | Service type must be cenm-networkmap |
ports.servicePort | HTTP port number where networkmap service is accessible internally |
ports.targetPort | HTTP target port number of the networkmap docker-container |
The snapshot of signer service with example values is below
services:
signer:
name: signer
subject: "CN=Test Subordinate CA Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
type: cenm-signer
ports:
servicePort: 8080
targetPort: 8080
The fields under signer
service are
Field | Description |
---|---|
name | Name for the Signer service |
subject | Certificate Subject for Signer service. Subject format can be referred at OpenSSL Subject |
type | Service type must be cenm-signer |
ports.servicePort | HTTP port number where signer service is accessible |
ports.targetPort | HTTP target port number of the signer docker-container |
The snapshot of notary service with example values is below
# Currently only supporting a single notary cluster, but may want to expand in the future
notary:
name: notaryskar
subject: "O=Notary,OU=Notary,L=London,C=GB"
type: notary
p2p:
port: 10002
targetPort: 10002
ambassador: 15010 #Port for ambassador service (must be from env.ambassadorPorts above)
rpc:
port: 10003
targetPort: 10003
rpcadmin:
port: 10005
targetPort: 10005
dbtcp:
port: 9101
targetPort: 1521
dbweb:
port: 8080
targetPort: 81
The fields under notary
service are
Field | Description |
---|---|
name | Name of the notary service |
subject | Certificate Subject for notary service. Subject format can be referred at OpenSSL Subject |
type | Service type must be notary |
validating | Only for Corda Enterprise Notary. Determines if Notary is validating or non-validating. Use true or false |
emailAddress | Only for Corda Enterprise Notary. Email address in the notary conf. |
p2p.port | Corda Notary P2P port. Used for communication between the notary and nodes of same network |
p2p.targetport | P2P Port where notary service is running. |
p2p.ambassadorport | Port where notary service is exposed via Ambassador |
rpc.port | Corda Notary RPC port. Used for communication between the notary and nodes of same network |
rpc.targetport | RPC Port where notary services is running. |
rpcadmin.port | Corda Notary Rpcadmin port. Used for RPC admin binding |
dbtcp.port | Corda Notary DbTcp port. Used to expose database to other services |
dbtcp.targetPort | Corda Notary DbTcp target port. Port where the database services are running |
dbweb.port | Corda Notary dbweb port. Used to expose dbweb to other services |
dbweb.targetPort | Corda Notary dbweb target port. Port where the dbweb services are running |
The snapshot of peer service with example values is below
# The participating nodes are named as peers
services:
peers:
- peer:
name: manufacturerskar
subject: "O=Manufacturer,OU=Manufacturer,L=47.38/8.54/Zurich,C=CH"
type: node
p2p:
port: 10002
targetPort: 10002
ambassador: 15010 #Port for ambassador service (must be from env.ambassadorPorts above)
rpc:
port: 10003
targetPort: 10003
rpcadmin:
port: 10005
targetPort: 10005
dbtcp:
port: 9101
targetPort: 1521
dbweb:
port: 8080
targetPort: 81
springboot: # This is for the springboot server
targetPort: 20001
port: 20001
expressapi: # This is for the express api server
targetPort: 3000
port: 3000
The fields under each peer
service are
Field | Description |
---|---|
name | Name of the Corda Node |
type | Service type must be node |
subject | The node legal name subject. |
auth | Vault auth of the corda Node |
p2p.port | Corda Node P2P port.Used for communication between the nodes of same network |
rpc.port | Corda Node RPC port. Used for communication between the nodes of different network |
rpcadmin.port | Corda Node Rpcadmin port. Used for RPC admin binding |
dbtcp.port | Corda Node DbTcp port. Used to expose database to other services |
dbtcp.targetPort | Corda Node DbTcp target port. Port where the database services are running |
dbweb.port | Corda Node dbweb port. Used to expose dbweb to other services |
dbweb.targetPort | Corda Node dbweb target port. Port where the dbweb services are running |
springboot.port | Springboot server port. Used to expose springboot to other services |
springboot.targetPort | Springboot server target port. Port where the springboot services are running |
expressapi.port | Expressapi port. Used to expose expressapi to other services |
expressapi.targetPort | Expressapi target port. Port where the expressapi services are running |
For Corda Enterprise, following additional fields have been added under each peer
.
firewall:
enabled: true # true if firewall components are to be deployed
dmz: true # true if a separate k8s cluster is being used for Corda Float. false if same cluster is used.
dmz_k8s: # DMZ cluster details. Must be under the same Cloud provider as the main cluster.
context: "dmz_cluster_context"
config_file: "dmz_cluster_config"
float:
name: float
port: 39999
subject: "CN=Float Local,O=Local Only,L=London,C=GB"
bridge:
name: bridge
subject: "CN=Bridge Local,O=Local Only,L=London,C=GB"
port: 40000
tunnelport: 40000
hsm: # hsm support for future release
enabled: false
Field | Description |
---|---|
firewall.enabled | Can be true/false. True, if Corda Firewall components are to be deployed. False, if Firewall is not needed. Corda recommends usage of Firewall for all production deployments. |
firewall.dmz | Can be true/false. True, if Corda Firewall components are to be deployed on a separate DMZ Kubernetes cluster. False, if Firewall components are to be deployed on same Kubernetes cluster as the Node. Corda recommends usage of separate DMS cluster for all production deployments. |
firewall.dmz_k8s | This is used only id dmz: true . Contains the Kubernetes cluster context and config file path of the DMZ cluster. Note that the cluster should be in the same Cloud provider account as the Node cluster. |
firewall.float.name | Name of the Float component |
firewall.float.port | Internal port of the Float component |
firewall.float.subject | Subject of the Float component |
firewall.bridge.name | Name of the Bridge component |
firewall.bridge.port | Internal port of the Bridge component |
firewall.bridge.tunnelport | Tunnel port of the Bridge component |
firewall.bridge.subject | Subject of the Bridge component |
hsm.enabled | This is kept for future HSM integration |