Configuring the Infrastructure Descriptor Parameters on AWS

The VMware Blockchain Orchestrator infrastructure descriptor file includes the definitions of all the available properties to configure in your AWS 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.
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: INSECURE - Feature is not enabled, and secrets are written in plain text on the blockchain node VMs. Note: This option is not recommended if you are storing sensitive information. DISK - Specify a URL where the symmetric key file is written on the disk. The URL must start with file:///config/<URL>. If this option is left blank, the default URL is file:///config/agent/secrets/secret_key.json. NONE - Symmetric key is not written and stored in the memory only. 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 Associate the symmetric key file to a user and restart the VM. 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.

Parameter

Description

damlSdk

Add the Daml (Digital Asset Modeling Language) SDK version.

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:

INSECURE - Feature is not enabled, and secrets are written in plain text on the blockchain node VMs.

Note:
This option is not recommended if you are storing sensitive information.
DISK - Specify a URL where the symmetric key file is written on the disk. The URL must start with file:///config/<URL>. If this option is left blank, the default URL is file:///config/agent/secrets/secret_key.json.
NONE - Symmetric key is not written and stored in the memory only.
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
```
Associate the symmetric key file to a user and restart the VM.

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
ENABLE_DAML_OUTGOING_TLS	If this advanced parameter is true, the blockchain deployment requires the Daml Ledger external client TLS keys in the deployment descriptor file. The deployment process fails if the TLS keys are not provided or are incorrect. The default value is true. When the parameter value is false, the Daml Ledger external client TLS keys are ignored even if present. There are no error messages or warning notifications if the TLS keys are not provided. This parameter is optional.
ENABLE_TELEGRAF_PULL_TLS	If this advanced parameter is true, the blockchain deployment requires the Telegraf pull metrics TLS keys in the infrastructure descriptor file. The deployment process fails if the TLS keys are not provided or are incorrect. The default value is true. When the parameter value is false, the Telegraf pull metrics TLS keys are ignored even if present. There are no error messages or warning notifications if the TLS keys are not provided. This parameter is optional.
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_SIDE_CAR_VM_DEPLOYMENT	If this advanced parameter is true, the blockchain deployment creates a sideCar node. During provisioning, the log_parser_agent container is deployed on all the Replica and Client nodes and the log_parser_appliance container on the sideCar node. The blockchain deployment requires the sideCar and sideCarNodeSpec, which is similar to the replicaNodeSpec and clientNodeSpec in the deployment descriptor file. Note: The deployment process fails if this parameter is True and the sideCar and sideCarNodeSpec details are not provided. The log parser appliance is deployed with the blockchain nodes on a sideCar node. The log parser tool can parse up to 800 MB of compressed logs or 10 GB of logs in a single execution. Sample ENABLE_SIDE_CAR_VM_DEPLOYMENT configuration. "advancedFeatures": { "ENABLE_SIDE_CAR_VM_DEPLOYMENT": true } This parameter is optional.
PERFORM_CONCORD_METADATA_CLEANUP	Set the Concord metadata cleanup parameter to true for cloning VMware Blockchain nodes. Sample PERFORM_CONCORD_METADATA_CLEANUP configuration. "organization": { "blockchainVersion": "1.8.0.0.53", "damlSdkVersion": "2.4.0", "advancedFeatures" : {"PERFORM_CONCORD_METADATA_CLEANUP" : "True"} } This parameter is optional.

Replica and Client Node Network Parameters

Specify the keyword network in the infrastructure descriptor file.

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.

Tanzu Observability by Wavefront Metrics Parameters

Specify the keyword wavefront in the infrastructure descriptor file.

The Tanzu Observability by Wavefront parameters are optional.

If you use this parameter, both the url and token parameters are mandatory.

Parameter	Description
url	Enter the Tanzu Observability by Wavefront endpoint URL.
token	Enter the unique token value you generated from Tanzu Observability by 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.

Amazon CloudWatch Metrics Parameters

Specify the keyword monitoring in the infrastructure descriptor file under Organization.

The cloudwatchMetrics parameters are optional.

If you use this parameter, then all the parameters are mandatory.

Parameter

Description

zoneId

Specify any AWS zone from the infrastructure descriptor file, including the AWS login credentials.

This parameter is mandatory.

createDashboard

Set to true to create the system, network, and Docker metrics dashboards on the AWS CloudWatch platform during deployment.

Set to false to avoid creating metrics dashboards on the AWS CloudWatch platform during deployment.

This parameter is mandatory.

Sample createDashboard configuration.

"monitoring": {
      "cloudwatchMetrics": {
        "zoneId": "test-zone-1 - A",
        "createDashboard": true
      }
    }

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.

Amazon CloudWatch Logging Parameters

Specify the keyword AWS_CLOUDWATCH in the infrastructure descriptor file.

Parameter	Description
type	Enter the logging parameter type, AWS_CLOUDWATCH to configure sending logs to Amazon CloudWatch. This parameter is mandatory.
region	Enter the AWS region of deployment. This parameter is mandatory.
logGroupName	Enter the name of the log group to store the logs. This parameter is optional.
logStreamName	Enter the name of the log stream to store the logs. Each log group can have multiple log streams. This parameter is mandatory.
retentionDays	Enter the number of days in the integer format to retain logs. The default retention day is 7. This parameter is mandatory. Sample AWS_CLOUDWATCH configuration. "logManagement": [ { "type": "AWS_CLOUDWATCH", "cloudwatchLogConfig": { "region": "us-east-1", "logGroupName": "log-group-name", "logStreamName": "log-stream-name", "retentionDays": 7 } } ]

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.

region

Enter an AWS region for deployment.

This parameter is mandatory.

credentials

Enter an IAM user with EC2 instance launch privileges. You can use a session token.

This parameter is mandatory.

network

Enter the information required to place a VMware Blockchain node.

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.

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.

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.

telegrafFilters

Configure Telegraf to filter a subset of metrics based on the defined filtering options.

You must set up the Telegraf and Wavefront proxies during deployment. Verify that you have access to Cloudwatch to access the filtered metrics.

For example, you can group the metrics based on the Concord container, Daml components, Agent, clientservice containers, Ethrpc, and other inbuilt metrics. If there are grouped metrics with a pre-determined naming convention, such as certain prefixes or tags, those prefixes or tags can be used to filter the metrics. The Config service stores the Telegraf configurations on the /config/telegraf/telegraf.conf file.

Telegraf has the following filtering options:

namepass- An array of pattern strings that only points to the measurement name, which matches a pattern in the listed metrics.
namedrop- The inverse of the namepass filter. If a match is found, the point is discarded. The match is tested on points after passing the namepass test.

You can use some or all of the filtering options to group the metrics results.

Sample telegrafFilters configuration.

{
    ...
    "zones": [
        {
            ...           
            "telegrafFilters": {
               "concordNamepass": ["kvbc", "concord_counter"],
               "concordNamedrop": [],
               "damlNamepass": [],
               "damlNamedrop": ["daml_command"],
               "agentNamepass": ["agent.health", "agent.container"],
               "agentNamedrop": [],
               "clientserviceNamepass": [],
               "clientserviceNamedrop": [],
               "ethrpcNamepass": [],
               "ethrpcNamedrop": [],
               "systemExclude": ["cpu", "disk", "net_response", "kernel"]
            }
        }
    ]
}

This parameter is optional.

AWS Credentials Parameters

Specify the keyword credentials in the infrastructure descriptor file.

Parameter	Description
accessKeyId	Enter the IAM access key. This parameter is mandatory.
secretAccessKey	Enter the IAM secret key. This parameter is mandatory.
sessionToken	Enter the session token for the IAM user. This parameter is optional.

Parameter

Description

accessKeyId

Enter the IAM access key.

This parameter is mandatory.

secretAccessKey

Enter the IAM secret key.

This parameter is mandatory.

sessionToken

Enter the session token for the IAM user.

This parameter is optional.

AWS Network Parameters

Specify the keyword network in the infrastructure descriptor file.

Parameter	Description
subnetId	Enter the subnet ID to place the node. This parameter is mandatory.
securityGroupIds	Enter the security group ID list that controls the inbound or outbound network traffic. This parameter is mandatory.

Parameter

Description

subnetId

Enter the subnet ID to place the node.

This parameter is mandatory.

securityGroupIds

Enter the security group ID list that controls the inbound or outbound network traffic.

This parameter is mandatory.