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
A json-schema definition is provided in platforms/network-schema.json to assist with semantic validations and lints. You can use your favorite yaml lint plugin compatible with json-schema specification, like redhat.vscode-yaml for VSCode. You need to adjust the directive in template located in the first line based on your actual build directory:
# yaml-language-server: $schema=../platforms/network-schema.json
The configurations are grouped in the following sections for better understanding.
type
version
frontend
env
docker
network_services
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.7 is supported by latest release. Please note only 4.4 above 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: # 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: 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. 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 Bevel network security. 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 network_services section with example values is below
# Remote connection information for doorman/idman and networkmap (will be blank or removed for hosting organization)
network_services:
- service:
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"
- service:
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 network_services section contains a list of doorman/networkmap which is exposed to the network. Each service has the following fields:
| Field | Description |
|---|---|
| type | For Corda, networkmap and doorman (idman for Corda Enterprise) are the only valid type of network_services. |
| 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.5 |
| 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. |
| Firewall | Only for Corda Enterprise Networkmap. Contains firewall options and credentials |
| cordapps (optional) | Cordapps Repo details which will be used to store/fetch cordapps jar |
| 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_protocol: "https" # Option for git over https or ssh
git_url: "https://github.com/<username>/bevel.git" # Gitops htpps or 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_repo: "github.com/<username>/bevel.git"
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/bevel.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 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 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
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
auth: password #ssl auth keystore password
For organization as type node the credential section is under peers section and looks like
credentials:
truststore: trustpass #node truststore password
keystore: 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 |
For Corda Enterprise, following additional fields have been added under each organisation.
firewall:
enabled: true # true if firewall components are to be deployed
subject: "CN=Test Firewall CA Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
credentials:
firewallca: firewallcapassword
float: floatpassword
bridge: bridgepassword
The Firewall field under each node type organization contains; valid only for enterprise corda
| Field | Description |
|---|---|
| enabled | true/false for enabling firewall (external bridge and float) |
| subject | Certificate Subject for firewall, format at OpenSSL Subject |
| credentials | Contains credentials for bridge and float |
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/bridge/float 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 zone service with example values is below
services:
zone:
name: zone
type: cenm-zone
ports:
enm: 25000
admin: 12345
The fields under zone service are
| Field | Description |
|---|---|
| name | Name for the Zone service |
| type | Service type must be cenm-zone |
| ports.enm | HTTP enm port number where zone service is accessible internally |
| ports.admin | HTTP admin port number of zone service |
The snapshot of auth service with example values is below
auth:
name: auth
subject: "CN=Test TLS Auth Service Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
type: cenm-auth
port: 8081
username: admin
userpwd: p4ssWord
The fields under auth service are
| Field | Description |
|---|---|
| name | Name for the Auth service |
| subject | Certificate Subject for Auth service. Subject format can be referred at OpenSSL Subject |
| type | Service type must be cenm-auth |
| ports | HTTP port number where auth service is accessible internally |
| username | Admin user name for auth service |
| userpwd | Admin password for auth service |
The snapshot of gateway service with example values is below
gateway:
name: gateway
subject: "CN=Test TLS Gateway Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
type: cenm-gateway
ports:
servicePort: 8080
ambassadorPort: 15008
The fields under gateway service are
| Field | Description |
|---|---|
| name | Name for the Gateway service |
| subject | Certificate Subject for Gateway service. Subject format can be referred at OpenSSL Subject |
| type | Service type must be cenm-gateway |
| ports.servicePort | HTTP port number where gateway service is accessible internally |
| ports.ambassadorPort | Port where gateway service is exposed via Ambassador |
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: notary1
subject: "O=Notary,OU=Notary,L=London,C=GB"
serviceName: "O=Notary Service,OU=Notary,L=London,C=GB" # available for Corda 4.7 onwards to support HA Notary
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 node. Subject format can be referred at OpenSSL Subject |
| serviceName | Certificate Subject for notary service applicable from Corda 4.7 onwards. 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 float service with example values is below
float:
name: float
subject: "CN=Test Float Certificate, OU=HQ, O=HoldCo LLC, L=New York, C=US"
external_url_suffix: test.cordafloat.blockchaincloudpoc.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
k8s:
context: "float_cluster_context"
config_file: "float_cluster_config"
vault:
url: "float_vault_addr"
root_token: "float_vault_root_token"
gitops:
git_url: "https://github.com/<username>/bevel.git" # Gitops https or ssh url for flux value files
branch: "develop" # Git branch where release is being made
release_dir: "platforms/r3-corda-ent/releases/float" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/r3-corda-ent/charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "github.com/<username>/bevel.git" # Gitops git repository URL for git push
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user password/access token (Optional for ssh; Required for https)
email: "git_email" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
ports:
p2p_port: 40000
tunnelport: 39999
ambassador_tunnel_port: 15021
ambassador_p2p_port: 15020
The fields under float service are below. Valid for corda enterprise only.
| Field | Description |
|---|---|
| name | Name for the float service |
| subject | Certificate Subject for Float service. Subject format can be referred at OpenSSL Subject |
| 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. |
| ports.p2p_port | Peer to peer service port |
| ports.tunnel_port | Tunnel port for tunnel between float and bridge service |
| port.ambassador_tunnel_port | Ambassador port for tunnel between float and bridge service |
| gitops | Ambassador port Peer to peer |
The fields under bridge service are below. Valid for corda enterprise only.
| Field | Description |
|---|---|
| name | Name for the bridge service |
| subject | Certificate Subject for bridge service. Subject format can be referred at OpenSSL Subject |
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 |