The VMware Blockchain Orchestrator infrastructure descriptor file includes the definitions of all the available properties to configure in your vSphere infrastructure environment and deploy VMware Blockchain nodes.
Organization Parameters
Specify the keyword organization in the infrastructure descriptor file.
Parameter |
Description |
|---|---|
damlSdk |
Add the Daml (Digital Asset Modeling Language) SDK version. This parameter is optional. |
generatePassword |
A VMware Blockchain password is generated if the parameter is set to true. This parameter is optional. |
generateDamlDbPassword |
If the parameter is set to true, a Daml database password is generated. For cloning your deployment environment, verify that the generateDamlPassword parameter is not set to true. This parameter is optional. |
secureStore |
Encrypts secrets such as private keys with a symmetric key. You can retrieve the symmetric key file from the blockchain node VM port 8546. curl -X GET 127.0.0.1:8546/api/encryption/key The additional_info contains any additional information or can remain null in the response. When an error occurs, this option includes a probable reason. You must provide the storeType value in the descriptor file for the deployment to start. The following are the storeType values:
If Secure Store is not provided, the default setting is DISK, and the default URL is file:///config/agent/secrets/secret_key.json. If Secure Store is provided and the parameter option is left blank, the default setting is DISK with the default URL. This parameter is optional. |
Advanced Features Parameters
Specify the keyword advancedFeatures in the infrastructure descriptor file. You can use the advanced feature parameter for performance tuning.
Parameter |
Description |
|---|---|
CPU_PINNING |
If this advanced parameter is set to true, your system gets tuned for higher performance. Before enabling the parameter, verify that the underlying infrastructure can accommodate 128 vCPUs for each Replica node VM for increased performance. Setting the "CPU_PINNING": "True" enables high performance on all the Replica nodes after the deployment is complete. This parameter is optional. The vCPU values after deployment are listed as follows in the agent configuration files:
In cases where the recommended settings do not meet your requirements, you can tune the vCPU configuration.
Note:
You must consult the VMware Blockchain SRE team to verify that your environment can support the vCPU configuration. After you consult the VMware Blockchain SRE team, you can use the DAML_CONCORD_CPU_SET and DAML_EXECUTION_ENGINE_SET flags. For example, you can set the flag variables as "DAML_CONCORD_CPU_SET": "9-17", "DAML_EXECUTION_ENGINE_SET": "18-35" |
LOGGING_TIMEZONE |
Set the logging timezone value on the Daml Index DB container to a preferred canonical timezone, for example, "Australia/Sydney," to view the Daml Index DB logs in the specified timezone. If not configured, the logging timezone defaults to UTC. To change the logging timezone for the rest of the containers on the Replica and Client nodes, see the loggingTimezone parameter in the Zone section. This parameter is optional. |
ENABLE_DB_CHECKPOINT_BACKUP NUM_DB_SNAPSHOTS DB_SNAPSHOT_INTERVAL_HOURS |
Enables RocksDB checkpoint-based backup on all the Replica nodes in the Replica Network. This parameter is enabled by default on all the Replica nodes. If the parameter is false, the RocksDB checkpoint-based backup is deactivated on all Replica nodes. NUM_DB_SNAPSHOTS shows the number of database snapshots to be created or maintained in the Replica nodes. The DB_SNAPSHOT_INTERVAL_HOURS displays the minimum time interval between two snapshots. Sample configuration. {
"organization": {
...
"advancedFeatures" : {
...
"ENABLE_DB_CHECKPOINT_BACKUP": true
"NUM_DB_SNAPSHOTS": "2",
"DB_SNAPSHOT_INTERVAL_HOURS": "6"
}
},
...
}In the sample configuration, a maximum of two snapshots are retained. A new snapshot is created only after 6 hours, and the sequence number executed since the previous snapshot is greater or equal to 30000. This parameter is optional. |
vCenter Server Parameters
Specify the keyword vCenter in the infrastructure descriptor file.
Parameter |
Description |
|---|---|
url |
Enter the vCenter Server URL endpoint you configured. This parameter is mandatory. |
tlsCertificateData |
Enter the single line vCenter Server public key you extracted. This parameter is optional. |
userName |
Enter a vCenter Server user name with the Blockchain Service role permissions. This parameter is mandatory. |
password |
Enter your vCenter Server password. This parameter is mandatory. |
resourcePool |
Enter the vCenter Server resource pool you configured. This parameter is mandatory. |
storage |
Enter the vCenter Server storage or datastore you assigned. This parameter is mandatory. |
folder |
Enter the vCenter Server folder you designated. This parameter is mandatory. |
Replica and Client Node Network Parameters
Specify the keyword network in the infrastructure descriptor file.
If the NTP service is down or not synchronized, the time across Replica and Client nodes might become inaccurate, leading to data discrepancies or causing errors in the Daml Ledger API. To avoid any Daml Ledger API errors and data discrepancies, you must keep the NTP service up and synchronized to ensure that all the servers running VMware Blockchain reflect the accurate time.
Parameter |
Description |
|---|---|
name |
Enter the network name. This parameter is mandatory. |
gateway |
Enter the network gateway IP address. This parameter is mandatory. |
subnet |
Set the subnet mask between 0–32. This parameter is mandatory. |
nameServers |
Enter single or multiple server IP addresses. Separate the multiple server IP addresses with a comma without any spaces. This parameter is mandatory. |
Docker Container Registry Parameters
Specify the keyword containerRegistry in the infrastructure descriptor file.
If you are using a private Docker container registry, you must download trusted VMware images. See Download Trusted VMware Images for Your Private Docker Container Registry for vSphere
Parameter |
Description |
|---|---|
url |
Enter the Docker container registry URL so that VMware Blockchain can connect to the Docker repositories.
Note:
The Docker container registry can have a CA (Certificate Authority) or self-signed-based authentication. For example, the Docker container registry URL can be https://vmwaresaas.jfrog.io/vmwblockchain. This parameter is mandatory. |
userName |
Enter the Docker container registry user name. For example, the Docker container registry username can be vmbc-jfrog-reader@vmware. This parameter is mandatory. |
password |
Enter the Docker container registry password. This parameter is mandatory. |
tlsCertificateData |
Enter the single-line TLS certificate output value for a Docker container registry if it is based on a self-signed authentication. The keys must be generated using the RSA algorithm. This parameter is optional. |
Notary Server Parameters
If you use a private self-signed authentication, you must download trusted VMware images. See Download Trusted VMware Images for Your Private Docker Container Registry for vSphere
Parameter |
Description |
|---|---|
url |
Enter a trusted notary server URL so that VMware Blockchain can connect to the notary server.
Note:
The notary server can have a CA (Certificate Authority) or self-signed-based authentication. The notary server address where all the images are signed is https://notary.vdp.vmware.com. This parameter is mandatory. |
tlsCertificateData |
Enter the single-line TLS certificate output value for the notary server based on a self-signed authentication. The keys must be generated using the RSA algorithm. This parameter is optional. |
Wavefront Metrics Parameters
Specify the keyword wavefront in the infrastructure descriptor file.
The Wavefront parameters are optional.
If you use this parameter, both the url and token parameters are mandatory.
Parameter |
Description |
|---|---|
url |
Enter the Wavefront endpoint URL. |
token |
Enter the unique token value you generated from Wavefront. |
Elastic Search Metrics Parameters
Specify the keyword elasticSearch in the infrastructure descriptor file.
The Elasticsearch proxy parameters are optional.
If you use this parameter, then all the parameters are mandatory.
Parameter |
Description |
url |
Enter the ELK endpoint URL. |
userName |
Enter the Elasticsearch endpoint user name. |
password |
Enter the Elasticsearch endpoint password. |
Logging Parameters
Depending on the type of logging parameter you are using, specify the keyword LOG_INTELLIGENCE, LOG_INSIGHT, or HTTP in the infrastructure descriptor file.
Parameter |
Description |
type |
Enter the logging parameter type, Log Intelligence, vRealize Log Insight, or HTTP. This parameter is mandatory. |
address |
Enter the IP address or FQDN of the Log Intelligence, vRealize Log Insight, or HTTP. This parameter is mandatory. |
port |
Enter the Log Intelligence, vRealize Log Insight, or HTTP port. This parameter is optional. If the port number is not specified in the URL and provided as the port attribute value, then the endpoint configuration in Fluentd has the hostname:port URL form. |
userName |
Enter the vRealize Log Insight endpoint user name. This parameter is mandatory. For Log Intelligence, specify the authToken for user authentication instead. HTTP for the endpoint user name is optional. |
password |
Enter the vRealize Log Insight endpoint password. This parameter is mandatory. For Log Intelligence, specify the authToken for user authentication instead. HTTP for the endpoint password is optional. |
logInsightAgentId |
Enter the vRealize Log Insight agent ID. This parameter is optional. |
Zone Parameters
A zone is a set of standard infrastructure configurations applied to single or multiple blockchain deployments.
A zone can host multiple blockchain deployments that share the common infrastructure, such as network parameters, resource pool, storage, and compute resources. Multiple deployments in a single zone also share monitoring, logging, container registry, and proxy settings.
To establish a connection between your environment and the VMware Blockchain nodes, you must create a zone.
Parameter |
Description |
name |
Assign a zone name. This parameter is mandatory. |
vCenter |
Enter the vCenter Server URL endpoint you configured. This parameter is mandatory. |
network |
Enter the zone network properties. This parameter is mandatory. |
outboundProxy |
Enter the zone outbound proxy properties. This parameter is optional. |
containerRegistry |
Enter the zone Docker registry properties. This parameter is mandatory. |
wavefront |
Enter the zone Wavefront metrics properties. This parameter is optional. |
elasticSearch |
Enter the zone Elastic Search metrics properties. This parameter is optional. |
logManagement |
Enter the zone logging properties. Zone logging supports HTTP endpoints with token-based authentication or basic authentication with username and password authentication. Logging parameters can be configured to be sent to multiple endpoints concurrently. Basic authentication is optional. TLS for an HTTP logging destination is supported. If required, the logging destination server public key can be specified in the tlsCertificateData attribute. The keys must be generated using the RSA algorithm. For example, you can specify HTTP and basic authentication with username and password for logstash-server-1.com and logstash-server-2.com. Logging endpoint providers have their specifications for authentication tokens. You can also optionally provide basic authentication tokens, for example, endpoint-1.splunk.com.
Note:
You can specify only one basic authentication and authentication token. Some authentication tokens require "Bearer <token>". The token must be included in double-quotes syntax. For example, Splunk requires the authentication token "Splunk <token>". Check your logging endpoint server for the correct syntax.
Note:
The logging endpoint value for the address property is mandatory. Some logging endpoints require a port number to be specified in the URL. If the port number is specified in the URL, the port attribute value is ignored during the endpoint configuration. If the port number is not specified in the URL and provided as the port attribute value, then the endpoint configuration in Fluentd has the hostname:port URL form. This parameter is optional. Sample logManagement configuration. "logManagement": [
{
"type": "LOG_INSIGHT",
"address": "http://log-insight-server.com",
"port": "9543",
"userName": "loginsight-user",
"password": "loginsight-password",
"logInsightAgentId": "0"
},
{
"type": "LOG_INTELLIGENCE",
"address": "http://log-intelligence-server.com/v1/streams/ingestion-pipeline-stream",
"port": "9543",
"authToken": "\"Bearer <token>\""
},
{
"type": "HTTP",
"address": "http://logstash-server-1.com",
"port": "19999",
"userName": "logstash-user-1",
"password": "logstash-password-1"
},
{
"type": "HTTP",
"address": "https://logstash-server-2.com:8938",
"tlsCertificateData": "-----BEGIN CERTIFICATE-------
TLS Certificate Data
-----END CERTIFICATE-----"
},
{
"type": "HTTP",
"address": "https://endpoint-1.splunk.com:8088",
"authToken": "\"Splunk <token>\""
}
] |
pullMetricsEndpoint |
Activate the VMware Blockchain node VM metrics endpoints, manually retrieve the monitoring metrics data, and examine an error. The metrics data is available in the Prometheus format. You can download and analyze this data within your preferred monitoring metrics framework. This parameter is optional. If the parameter is not specified, the default configuration is enabled where the metrics can be retrieved from http://<Blockchain-VM-IP>:9273/metrics URL. You can use domain-validated or self-signed certificates. As a best practice, use domain-validated certificates. When the tlsCertificateData and tlsKeyData values are provided, the monitoring metrics data can be retrieved securely using an HTTPS protocol. The keys must be generated using the RSA algorithm. As a best practice, use these parameters to activate a secure endpoint connection. The same certificate pair specified in the infrastructure descriptor file is applied to all deployed VMware Blockchain node VMs. Use only domain-validated certificates because IP address-validated certificates are specific to an IP address and cannot be used. If the mentioned parameters are not specified, the monitoring metrics data is retrieved using an unsecured HTTP protocol. The HTTP protocol has weak security and must be used for internal use only. After deployment, you can validate whether the VMware Blockchain node VM endpoints are enabled and the monitoring metrics data retrieved. |
pullMetricsEndpoint userName |
Enter the endpoint access user name. This user name is used for all the VMware Blockchain node VMs that belong to a zone. This parameter is mandatory. |
pullMetricsEndpoint password |
Enter the endpoint access password. This password is used for all the VMware Blockchain node VMs that belong to a zone. This parameter is mandatory. |
pullMetricsEndpoint tlsCertificateData |
Enter the single-line TLS certificate output value for self-signed authentication. The keys must be generated using the RSA algorithm. You can convert the certificate file into a single-line string using the command, awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <cert_file_name>This parameter is optional. |
pullMetricsEndpoint tlsKeyData |
Enter the single-line TLS key data output value for self-signed authentication.
Note:
The private key must not contain a passphrase. You can convert the certificate file into a single-line string using the command, awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <cert_file_name>This parameter is optional. |
pushMetricsHttpEndpoint |
Configure the VMware Blockchain node VM metrics endpoints, collect the monitoring metrics data, and examine an error. The metrics data is available in JSON format. You can download and analyze this data within your preferred monitoring metrics framework. This parameter is optional. When the tlsCertificateData values are provided, the monitoring metrics data can be retrieved securely using an HTTPS protocol. The keys must be generated using the RSA algorithm. As a best practice, use these parameters to activate a secure endpoint connection. The same certificate pair specified in the infrastructure descriptor file is applied to all deployed VMware Blockchain node VMs. Use only domain-validated certificates because IP address-validated certificates are specific to an IP address and cannot be used. If the mentioned parameters are not specified, the monitoring metrics data is retrieved using an unsecured HTTP protocol. The HTTP protocol has weak security and must be used for internal use only. After deployment, you can validate whether the VMware Blockchain node VM endpoints are enabled and the monitoring metrics data retrieved. Sample pushMetricsHttpEndpoint configuration with authentication token and TLS. "pushMetricsHttpEndpoint": {
"url": "http://10.20.69.297:8088/services/collector/raw",
"token": "Splunk <token>",
"tlsCertificateData": "-----BEGIN CERTIFICATE-------
TLS Certificate Data
-----END CERTIFICATE-----"
} |
pushMetricsHttpEndpoint url |
Enter the endpoint URL and the port number. This parameter is mandatory. |
pushMetricsHttpEndpoint userName |
Enter the endpoint access user name. This user name is used for all the VMware Blockchain node VMs that belong to a zone.
Note:
Use either the basic authentication, including the username and password, or token authentication. If you use both the basic and token authentication together, you receive an error message. This parameter is optional. |
pushMetricsHttpEndpoint password |
Enter the endpoint access password. This password is used for all the VMware Blockchain node VMs that belong to a zone. This parameter is mandatory. |
pushMetricsHttpEndpoint tlsCertificateData |
Enter the single-line TLS certificate output value for self-signed authentication. The keys must be generated using the RSA algorithm. You can convert the certificate file into a single-line string using the command, awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <cert_file_name>This parameter is optional. |
pushMetricsHttpEndpoint token |
Enter the unique token value you generated from the endpoint.
Note:
Use either the basic authentication, including the username and password, or token authentication. If you use both the basic and token authentication together, you receive an error message. Depending on your endpoint, you might be required to include the bearer authentication. In this case, make sure that you add the complete bearer authentication string as, "token":"<endpoint_name> xxxx-xxxx-xxxx-xxxx". See the endpoint application documentation for additional details. This parameter is optional. |
clientBackup |
Configure this parameter to back up the deployed Client nodes. If the parameter values are not specified, default settings are used, and backups are determined by whether the deployment descriptor has the backupEnabled value set to True. This parameter is optional. Sample clientBackup configuration.
{
...
"zones": [
{
...
"clientBackup": {
"scheduleFrequency": "DAILY",
"retentionDays": 10
}
}
]
}
|
clientBackup scheduleFrequency |
Schedule the Client node backup frequency to HOURLY, EVERY_2_HOURS, EVERY_5_HOURS, EVERY_10_HOURS, EVERY_12_HOURS, or DAILY. If the schedule frequency values are not defined, a schedule is not entered into the system. If the schedule frequency parameter value is not provided, any existing schedule already defined in the system is erased. When the schedule frequency parameter value is specified, the system makes a full backup at every scheduled interval and saves it in the pre-defined /mnt/client-backups/<node-id> directory. You can manually request a Client node backup using the agent REST API on each Client node VMs. Use the API specification.
POST http://127.0.0.1:8546/api/backup
{
"retention_days": 33,
"schedule_frequency": "DAILY"
}
You can also use curl to issue the REST API.
curl -ik -X POST -d '{"retention_days": 33, "schedule_frequency": "DAILY"}' http://127.0.0.1:8546/api/backupThis parameter is optional. |
clientBackup retentionDays |
Enter the number of days to retain full Client node backups. If the parameter value is not specified or set to 0, a default value is 10 days is used. This parameter is optional. |
loggingTimezone |
Set the logging timezone on all the containers on the Replica and Client nodes, except the Daml Index DB. Configure the value to a preferred canonical timezone, for example, "Australia/Sydney," to view the container logs in the specified timezone. For the Daml Index DB logs, see the parameter LOGGING_TIMEZONE in the Advanced Feature section. If this parameter is not configured, the logging timezone defaults to UTC.
Note:
If the timezone name is invalid, the blockchain deployment might fail. The timezone name validation occurs during the deployment process. This parameter is optional. |
