Bringing Governance Engine Online

Edit online

This topic describes how to bring the Governance Engine online for IBM Digital Asset Haven by configuring HSM‑related settings, updating Terraform variables, and initializing the Governance Engine instance.

Before you begin

Ensure that all System Requirements are met.
Configure the IBM Digital Asset Haven LPAR by following the instructions in Configuring IBM Digital Asset Haven with HSM Signer.
You must enable TOFU mode for IBM Digital Asset Haven SaaS instances provisioned prior to the introduction of Governance Engine support (June 2026). By default this mode is disabled. For more information, see TOFU Mode for Governance Engine.

About this task

Bringing the Governance Engine online involves modifying the Terraform configuration file, configuring cryptographic settings for the Hardware Security Module, and starting the Governance Engine in standalone or high availability (HA) mode.

Note: All commands and scripts assume that HSM-SIGNER is used as the base directory.

Warning:

Do not attempt to destroy the Governance Engine instance.

The instance contains a persistent data volume with highly sensitive information related to digital wallets and financial transactions.
Loss of this data volume is irreversible.
Unauthorized modification can result in permanent loss of digital assets.

Handle the data volume with extreme caution.

Procedure

Copy ./contracts/terraform.tfvars.tmpl to ./contracts/terraform.tfvars and modify it.
Update the Crypto Card / HSM Configuration section in terraform.tfvars.
Set the Domain ID.
1. Run the following command to list the available domains:
```
ep11info -D
```
2. Convert the module-nr value to hexadecimal. For example, 7 becomes 0x7.
3. Choose a local crypto domain from the domain-nr column and convert it to hexadecimal. For example, 33 becomes 0x21.
4. Combine these values and set the DOMAIN_ID variable:
```
DOMAIN_ID="07.0021"
```

Set the master key verification pattern (MKVP)

Use the wrapping key column from the output above. Remove spaces and convert to lowercase:

 echo <wrapping key> | sed 's/ //g' | tr '[:upper:]' '[:lower:]' | sed 's/^/0x/'

Sample output:

$ echo "88888888 77777777 AAAAAAAA 11111111 55555555 77777777 55555555 00000000" | sed 's/ //g' | tr '[:upper:]' '[:lower:]' | sed 's/^/0x/' 0x8888888877777777aaaaaaaa1111111155555555777777775555555500000000

Update the MKVP variable with the following value

0x8888888877777777aaaaaaaa1111111155555555777777775555555500000000

Set the host key document name (HKD_NAME
1. Run the following script:
```
./scripts/machine.sh
```
  Sample output:
```
HKD-3333-11ABCDE
```
2. Update HKD_NAME with the output value.
Download and set the host key document certificate (HKD_CRT)
1. Login to https://www.ibm.com/support/resourcelink/
2. Download the certificate from
  https://www.ibm.com/support/resourcelink/api/content/raw/hkd-public/<HKD_NAME>.crt
3. Update HKD_CRT with the downloaded certificate.
  The HKD_CRT value will be in base64.
Generate and set the secret
1. Generate a unique secret and encode it in Base64:
```
echo <unique secret> | base64 -w0
```
  Sample output:
```
$ echo "HelloWorld" | base64 -w0 SGVsbG9Xb3JsZAo=
```
2. Update the secret variable with SGVsbG9Xb3JsZAo=
Configure Crypto passthrough by following the instructions provided in Crypto Passthrough
Update the following sections in terraform.tfvars:
- MEDIATED_DEVICE_UUID - Run the command uuidgen and update the MEDIATED_DEVICE_UUID with the output.
- Container image configuration – Specify the container image location. You can get the image location from sha256.
- Volume seed configuration – Set the volume seed according to encryption requirements.
- Registry configuration – Configure registry credentials and endpoint.
- Logging configuration – Refer to rsyslog configuration.
Configure backup server settings. This step applies only to HA deployments.
1. Set the backup server IP address
  Set the LPAR IP address of the backup Governance Engine server.
```
BACKUP_SERVER_IPADDR="1.2.3.4"
```
2. Set the backup server common name
  1. Obtain the backup server certificate file.
  2. Extract the certificate details.
```
openssl x509 -in <backup-cert>.pem -text -noout
```
  3. From the output, extract the CN value from the Subject field.
  4. Update the variable.
```
BACKUP_SERVER_CNAME="12345.store-abcde-f1234-567890abcd.1234567890ab"
```
Configuring switchover from backup to standalone active. This step is only required when the active sever is destroyed and the backup server is promoted to active.
By default, the SWITCHOVER_BACKUP_TO_ACTIVE flag is false. Set the flag to true to use the same database as a backup.
Starting the Governance Engine (Active server or standalone mode )
Run the following command on the active or standalone system.
```
./scripts/goveng_init.sh
```
- To bring up Governance Engine in standalone mode, ensure BACKUP_SERVER_IPADDR and BACKUP_SERVER_CNAME are not set in terraform.tfvars.
- To bring up Governance Engine in HA mode, ensure that both variables are set in terraform.tfvars.
Note: For HA deployments, ensure that the backup server is initialized first.
Sample output:
```
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.

Outputs:
vm_name = "goveng"
Governance Engine initialization completed successfully
```
Bring up the backup server (HA mode)
Perform the following steps on the backup LPAR.
```
./scripts/goveng_init.sh --backup
 
```
Sample output includes backup server configuration and successful initialization.

Verify deployment

Check the Governance Engine virtual machine status.

virsh list --all

Expected output:

Id   Name     State
-----------------------
2    goveng   running

What to do next

Bring up the HSM signer by following the instructions provided in Bringing HSM Signer Online.