DB Design for multi-ASIC scenarios

doc/multi_asic/DB_Design_for_multi_asic.md

@@ -0,0 +1,237 @@
+# DB Design for multi-ASIC scenarios
+
+- [DB Design for multi-ASIC scenarios](#db-design-for-multi-asic-scenarios)
+- [Revision](#revision)
+- [1.BACKGROUND](#1background)
+- [2.SCOPE](#2scope)
+- [3.DESIGN OVERVIEW](#3design-overview)
+- [4.DB Schema Design](#4db-schema-design)
+- [5.Requirements](#5requirements)
+  * [5.1 config reload <filename\>](#51-config-reload--filename--)
+  * [5.2 config override](#52-config-override)
+  * [5.3 config apply-patch](#53-config-apply-patch)
+  * [5.4 show runningconfiguration all](#54-show-runningconfiguration-all)
+  * [5.5 config save](#55-config-save)
+- [6.Conclusion](#6conclusion)
+
+# Revision
+
+| Rev | Date        | Author             | Change Description  |
+|:---:|:-----------:|:------------------:|---------------------|
+| 0.1  | 09/24/2024 | Jingwen Xie        | Initial version     |
+
+# 1.BACKGROUND
+
+SONiC uses minigraph as configuration truth generation for both single ASIC and multi-ASIC. In multi-ASIC, SONiC itself will generate HOST and ASIC DB configurations based on single minigraph file.
+
+In the future, SONiC will deprecate minigraph and fetch the Golden Config generated by Network Device Management(NDM) team. In the single ASIC workflow, NDM will be responsible to generate the Golden Config. Config Push Service(HwProxy) will push the config to SONiC. Then SONiC will load the Golden Config. However, NDM, HwProxy and SONiC  doesn’t have a workflow for multi-asic scenario to consume Golden Config. 
+
+In existing minigraph workflow, NDM/HwProxy will treat multi-asic SONiC device just as the single ASIC device, which means only one minigraph file will be provided to SONiC to generate all the  configuration no matter it is single ASIC or multi-asic. During multi-asic config generation, a single minigraph will be generated and deployed in SONiC device. SONiC has its minigraph parsing logic to break one piece of config into small pieces for host and each ASIC.
+
+We assume NDM/HwProxy will follow the above existing minigraph workflow, where only one Golden Config file will be generated and deployed in SONiC’s multi-asic device. 
+# 2.SCOPE
+
+This document describes the high level design of DB schema of multi-asic scenarios. 
+
+# 3.DESIGN OVERVIEW
+
+A single Golden Config will be provided as the ground truth of multi-asic SONiC configuration source.
+
+**Objective:**
+
+This DB design will be used for a single source of truth of multi-asic device configuration in the future.
+
+**Requirements:**
+
+- `config reload` should be able to reload one desired Golden Config file for multi-asic.
+- `config override-config-table` should be able to perform override one desired Golden Config file for multi-aisc.
+- `show runningconfiguration all` should be able to show all host and asics config in the format of desired Golden Config.
+- `config apply-patch` should be able to perform config update change based on the Jsondiff of desired Golden Config.
+- `config save` should be able to save all config to one file of desired Golden Config format.
+
+
+# 4.DB Schema Design
+
+The new DB schema provides another layer of Host and Asic as key, then appends relative configuration as the value.
+```
+{
+    "localhost"：{
+        "FEATURE": {…}，
+        "ACL_TABLE": {…},
+        …
+    }，
+    "asic0"：{
+        "FEATURE": {…},
+        "ACL_TABLE": {…},
+        …
+    },
+    …
+}
+
+```
+
+# 5.Requirements
+
+## 5.1 config reload <filename\>
+
+Current config reload CLI supports multi-asic reload by providing N config files, where N is the sum of host and ASICs. The config file for host will be `/etc/sonic/config_db.json`, and the config file for ASIC will be `/etc/sonic/config_db0.json`, `/etc/sonic/config_db1.json`, and so on.
+
+To support the single Golden Config JSON file described earlier, SONiC should be able to consume one file to generate all configs of host and ASIC. To make it backward compatible, we need to add the multi ASIC support to make it be able to consume one Golden Config JSON file.
+
+**SCENARIOS**
+
+1. Existing support for single ASIC:
+
+- `config reload`
+
+It will reload the default config file: /etc/sonic/config_db.json
+
+- `config reload tmp_config_db.json`
+
+It will reload the tmp_config_db.json
+
+2. Existing support for multi-ASIC:
+
+- `config reload`
+
+It will reload the default config file: `/etc/sonic/config_db.json, /etc/sonic/config_db0.json, …, /etc/sonic/config_db5.json`
+
+- `config reload tmp_config_db.json,tmp_config_db0.json,…,tmp_config_db5.json`
+
+It will reload the specified list of tmp config files.
+
+3. Extra support for multi-ASIC:
+
+- `config reload golden_config_db.json`
+
+It will reload the single JSON file with format in chapter 4 to all configDBs. 
+
+## 5.2 config override 
+Current config override CLI only support single ASIC override. Its logic needs to be modified to support override in multi-asic scenarios.[PR](https://github.com/sonic-net/sonic-utilities/pull/2738) 
+
+Take one table "MACSEC_PROFILE" for example. Suppose we have golden_config_db.json in below:
+
+```
+{
+      "localhost":{
+           "MACSEC_PROFILE":{}
+      },
+      "asic0":{
+          "MACSEC_PROFILE":{
+               "entry":{"k":"v"}
+          }
+     },
+     "asic1":{
+          "MACSEC_PROFILE":{
+               "entry":{"k":"v"}
+          }
+     },
+     …
+}
+```
+
+After override, each of ConfigDB should be updated below:
+
+- host: 
+
+The MACSEC_PROFILE table will be removed no matter what it was before override since empty json means table removal.
+
+```
+{
+    "MACSEC_PROFILE":{},
+}
+```
+- asic0, asic1,...
+
+The MACSEC_PROFILE table will be exactly be what resides the golden config no matter what it was.
+```
+{
+    "MACSEC_PROFILE":{
+        "entry":{"k":"v"}
+    },
+}
+```
+## 5.3 config apply-patch
+
+Current config apply-patch CLI doesn’t support multi-asic. To support GCU in multi-asic, we need to modify the patch to make host and ASIC consume the patch in a loop. 
+The GCU command will keep the same as before. patch will stays the same and follow  JSON Patch (RFC6902). 
+
+- config apply-patch patch.json
+
+Example of patch.json. This patch is to change asic0 and asic1’s k to “value”.
+
+```
+[
+ {
+  "op": "replace",
+  "path": "/asic1/MACSEC_PROFILE/entry/k",
+  "value": "value"
+ },
+ {
+  "op": "replace",
+  "path": "/asic0/MACSEC_PROFILE/entry/k",
+  "value": "value"
+ }
+]
+
+```
+## 5.4 show runningconfiguration all
+
+`show runningconfiguration all` should display the configuration of all asic configuration in below format:
+
+```
+{
+    "localhost"：{
+        "MGMT_INTERFACE": {…}，
+        "ACL_TABLE": {…},
+        …
+    }，
+    "asic0"：{
+        "MGMT_INTERFACE": {…},
+        "ACL_TABLE": {…},
+        …
+    },
+    "asic1"：{
+        "MGMT_INTERFACE": {…},
+        "ACL_TABLE": {…},
+        …
+    },
+    …
+}
+```
+
+## 5.5 config save
+Current config save will generate N config files, where N is the sum of host and ASICs. The CLI will keep the same behavior as before. 
+SCENARIOS 
+
+1. Existing support for single ASIC:
+
+- `config save`
+
+It will save to the default config file: /etc/sonic/config_db.json
+
+- `config save tmp_config_db.json`
+
+It will save config to the tmp_config_db.json
+
+2. Existing support for multi-ASIC:
+
+- `config save`
+
+It will save to the default config file: /etc/sonic/config_db.json, /etc/sonic/config_db0.json, …, /etc/sonic/config_db5.json
+
+- `config save tmp_config_db.json,tmp_config_db0.json,…,tmp_config_db5.json`
+
+It will save to the specified list of tmp config files.
+
+3. Extra support for multi-ASIC:
+
+- `config save all_config_db.json`
+
+It will save the single JSON file with format of chatper 4 to all configDBs.
+
+
+# 6.Conclusion
+
+To support this DB schema, all we need to do is to add one layer of host or ASIC information. SONiC YANG models can stay as of now and no new fields need to be added.
+