Disabling automatic NATS configuration

BrokerGateway-managed NATS

Important

Automatic NATS configuration must either be consistently enabled in the entire cluster or disabled in the entire cluster. You cannot have part of the cluster rely on automatic NATS configuration and the other part on manual configuration.

Caution

If you disable automatic NATS configuration, this means you become responsible for maintaining the configuration of the appsettings.runtime.json and C:\Program Files\Skyline Communications\DataMiner BrokerGateway\nats-server\nats-server.config files, and you will need to ensure the synchronization of the credentials in the system.

Starting from DataMiner 10.5.0 [CU1]/10.5.4, it is possible to apply a manual NATS configuration when required. This is intended for scenarios where specific system characteristics, like high latency between nodes or geographically dispersed DataMiner Agents, necessitate a custom NATS layout.

Setting up BrokerGateway with a custom manual config will allow you to create superclusters and/or leaf nodes:

A cluster consists of all the nodes that are closely related by location. They should have low latency and high bandwidth between each other.
A supercluster is a collection of different clusters that can communicate with each other. It consists of two or more clusters. Clusters communicate with other clusters using gateway connections (port 7222). Each cluster consists of two or more nodes. These nodes communicate with each other using cluster connections (port 6222).
A leaf node is a node that is related to a specific cluster, but has a higher latency and/or lower bandwidth to the nodes of the actual cluster. Optionally, a cluster can have one or more leaf nodes attached to it. A leaf node communicates with the rest of the cluster using a specific leaf node connection (port 7422).

Setting up a manual config

Enable manual configuration by sending a POST request to https://[ip]/BrokerGateway/api/clusteringapi/setmanualconfigflag with the following request body:
```
{
  "distribute_in_cluster": true,
  "has_manual_config": true
}
```
Make sure the request includes a valid BrokerGateway API key in the BrokerGateway-Api-Key HTTP header. This Administrator key can be found in C:\Program Files\Skyline Communications\DataMiner BrokerGateway\appsettings.runtime.json.

Note that distribute_in_cluster must be set to true to ensure that the configuration flag is automatically propagated to all nodes in the cluster.

Apply a custom config by sending a POST request to https://[ip]/BrokerGateway/api/clusteringapi/applymanualconfig using a request body that contains the full cluster config.

Below is an example for a supercluster consisting of two clusters with leaf nodes:

{
  "regions": [
  {
    "name": "Cluster1",
    "nodes": [
    {
      "endpoint": "DMA1",
      "bgw_api_key": "BGW_API_KEY_1",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "DMA2",
      "bgw_api_key": "BGW_API_KEY_2",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "DMA3",
      "bgw_api_key": "BGW_API_KEY_3",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "LeafNode1",
      "bgw_api_key": "LeafNode_BGW_API_KEY_1",
      "is_leaf": true,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "LeafNode2",
      "bgw_api_key": "LeafNode_BGW_API_KEY_2",
      "is_leaf": true,
      "should_run_nats_node": true,
      "additional_endpoints": []
    }
    ]
  },
  {
    "name": "Cluster2",
    "nodes": [
    {
      "endpoint": "DMA4",
      "bgw_api_key": "BGW_API_KEY_4",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "DMA5",
      "bgw_api_key": "BGW_API_KEY_5",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "DMA6",
      "bgw_api_key": "BGW_API_KEY_6",
      "is_leaf": false,
      "should_run_nats_node": true,
      "additional_endpoints": []
    },
    {
      "endpoint": "LeafNode3",
      "bgw_api_key": "LeafNode_BGW_API_KEY_3",
      "is_leaf": true,
      "should_run_nats_node": true,
      "additional_endpoints": []
    }
    ]
  }
  ]
}

Each node requires the bgw_api_key of that BrokerGateway node. This can be found on that server in C:\Program Files\Skyline Communications\DataMiner BrokerGateway\appsettings.runtime.json. Use the API key with the role "BrokerGateway" on the specific node.

The additional_endpoints property allows you to specify extra endpoints that BrokerGateway must include when generating NATS certificates. This is required when adding nodes that are part of a Failover pair; in such cases, the Failover VIP or shared hostname should be listed here.

The should_run_nats_node property is currently non-functional but may be used in future releases.

Deconstructing the manual config

Look up the BrokerGateway API key in C:\Program Files\Skyline Communications\DataMiner BrokerGateway\appsettings.runtime.json.

You will need to use this Administrator key in the BrokerGateway-Api-Key HTTP header of the request mentioned below.
Disable manual configuration by sending a POST request to https://[ip]/BrokerGateway/api/clusteringapi/setmanualconfigflag with the following request body:
```
{
  "distribute_in_cluster": true,
  "has_manual_config": false
}
```
Run NATSRepair.exe to reset your NATS cluster to the default state.

Legacy SLNet-managed NAS/NATS

From DataMiner 10.2.0 [CU6]/10.2.8 onwards, you can enable the NATSForceManualConfig option so that NATS is not automatically configured in your DataMiner System. When you do so, you will need to configure a NATS cluster manually. There are two distinct methods to enable NATSForceManualConfig:

For all DMAs in the cluster via SLNetClientTestTool (recommended).
For one DMA at a time by changing MaintenanceSettings.xml.

Important

Caution

If you disable automatic NATS configuration, this means you become responsible for maintaining the configuration of the SLCloud.xml, nas.config, and nats-server.config files as well as ensuring the synchronization of the credentials in the system. From DataMiner 10.3.11/10.3.0 [CU8] onwards, when DataMiner makes changes to any of these files, the old version of that file is saved in the C:\Skyline DataMiner\Recycle Binfolder.

Note

Changes to the NATSForceManualConfig option are included in a DataMiner backup to make sure that the automatic NATS configuration status remains consistent after a backup is restored. From DataMiner 10.4.11/10.5.0 onwards, any changes made to the nats-server.config file after disabling automatic NATS configuration will also be included in DataMiner backups. Prior to this, you need to manually back up the nats-server.config file, located in the C:\Skyline DataMiner\NATS\nats-streaming-server\ folder. See nats-server.config file not included in DataMiner backups.