Merge branch 'sonic-net:master' into master

doc/BGP/BGP-router-id.md

@@ -0,0 +1,172 @@
+# BGP Router ID Explicitly Configured
+
+- [Revision](#revision)
+- [Definitions/Abbreviations](#definitionsabbreviations)
+- [Scope](#scope)
+- [Overview](#overview)
+- [Requirements](#requirements)
+- [High Level Design](#high-level-design)
+- [Config DB Enhancement](#config-db-enhancement)
+    - [DEVICE_METADATA](#device_metadata)
+
+### Revision
+
+| Revision | Date        | Author           | Change Description |
+| -------- | ----------- | ---------------- | ------------------ |
+| 1.0      | Mar 27 2024 | Yaqiang Zhu, Jing Kan | Initial proposal   |
+
+### Definitions/Abbreviations
+
+| Definitions/Abbreviation | Description |
+| ------------------------ | ----------- |
+| FRR | A free and open source Internet routing protocol suite for Linux and Unix platforms |
+| BGP Router ID | 32-bit value that uniquely identifies a BGP device |
+| AS | Autonomous System |
+| iBGP | Internal Border Gateway Protocol, which is used inside the autonomous systems |
+| eBGP | External Border Gateway Protocol, which is used between autonomous systems |
+
+### Scope
+
+This document describes a mechanism to allow user explicitly configure BGP router id.
+
+### Overview
+
+Currently, there are some BGP hard codings in SONiC:
+1. BGP router id was defined as a 32-bit value that uniquely identifies a BGP device. In single-asic device, SONiC uses Loopback0 IPv4 address as BGP router id. In mult-asic and uses Loopback4096 IPv4 address as BGP router id (for both iBGP and eBGP). This coupling prevents users from using customized router id. If IPv4 address of Loopback0 / Loopback4096 don't exist, BGP router id wouldn't be configured, then FRR would choose the largest IP address in device to be BGP router id. If the router id choosen by FRR is not unique, it would be considered an error.
+2. In single-asic device, SONiC wouldn't add BGP peer when there is not Loopback0 IPv4 exists. In multi-asic, SONiC wouldn't add eBGP peer when there is not Loopback0 IPv4 exists.
+
+Below is current workflow about BGP and router id in single-asic, only includes contents related to Loopback0.
+
+1. After bgp container started, configuration file `/etc/frr/bgpd.conf` for bgpd would be rendered. It will use Loopback0 IPv4 address as BGP router id, if it doesn't exist, the BGP router id wouldn't be specified.
+2. bgpd start with configuration rendered before. If BGP router id is not specified, it would choose an IP address in device to be BGP router id.
+3. After bgpcfgd started, it will add bgp peer depends on whether Loopback0 IPv4 exist. If Loopback0 IPv4 doesn't exist, stop to process neighbors adding and return with False signal.
+
+<p align=center>
+<img src="img/origin_bgp_seq.png" alt="Origin bgp seq" width=700>
+</p>
+
+Below is current workflow about BGP and router id in multi-asic, only includes contents related to Loopback0 and Loopback4096. To be clarified that due to space limitations, the figure below only describes the behavior of one aisc in a multi-asic system. The behavior of other asics is similar to this one, except that they will start their own bgp\[x\] containers and read their respective config_db.
+
+1. After bgp container of each asic started, configuration file `/etc/frr/bgpd.conf` for bgpd would be rendered. It will use Loopback4096 IPv4 address configured in correspond config_db as BGP router id, if it doesn't exist, the BGP router id wouldn't be specified.
+2. bgpd start with configuration rendered before. If BGP router id is not specified, it would choose an IP address in device to be BGP router id.
+3. After bgpcfgd started, it will add bgp peer depends on whether Loopback0 and Loopback4096 IPv4 exist:
+   1. If Loopback0 IPv4 doesn't exist, stop to process BGP neighbors adding and return with False signal.
+   2. Else
+      1. If IPv4 address of Loopback4096 exists, add iBGP peer; else process iBGP neighbors adding and exit with False signal.
+      2. If current asic is FrontEnd, add eBGP peer.
+
+<p align=center>
+<img src="img/origin_bgp_seq_multi_asic.png" alt="Origin bgp seq multi asic" width=750>
+</p>
+
+### Requirements
+
+Add support to allow user explicitly configure BGP router id.
+
+### High Level Design
+
+2 aspects enhancement:
+
+1. Add a field `bgp_router_id` in `CONFIG_DB["DEVICE_METADATA"]["localhost"]` to support explicitly configure BGP router id. For multi-asic devices, this configuraion would be added to correspond config_db for each asic. If `CONFIG_DB["DEVICE_METADATA"]["localhost"]["bgp_router_id"]` configured, always use it as BGP router id. With this change, the new BGP router id configuration behavior will be like follow table. To be clarified that when bgp_router_id doesn't be configured, the behavior is totally same as previously.
+
+|           | Loopback0/Loopback4096 IPv4 address exists | Loopback0/Loopback4096 IPv4 address doesn't exist |
+|--------------|-------|------------|
+| bgp_router_id configured | Honor bgp_router_id | Honor bgp_router_id |
+| bgp_router_id doesn't be configured | Honor Loopback0/Loopback4096 IPv4 address | FRR default router ID value is selected as the largest IP address of the device. When router zebra is not enabled bgpd can’t get interface information so router-id is set to 0.0.0.0 |
+
+2. In single-asic scenario, remove strong dependencies on Loopback0 IPv4 address when adding BGP peer in the situation that bgp_router_id is configured. With this change, the new BGP peer adding behavior will be like follow table. 2 points need To be clarified:
+   1. When bgp_router_id doesn't be configured, the behavior is totally same as previously.
+   2. We won't modify the logic of adding internal peer, it will still follow previous logic to treat Loopback4096 IPv4 address as required factor.
+
+|          | Loopback0 IPv4 address exists | Loopback0 IPv4 address doesn't exist |
+|--------------|-------|------------|
+| bgp_router_id configured | Add BGP peer | Add BGP peer |
+| bgp_router_id doesn't be configured | Add BGP peer | Do not add BGP peer |
+
+#### Single-asic
+
+Below is new workflow for single-asic, the main changes are in `1.` and `3.`.
+
+1. After bgp container started, configuration file `/etc/frr/bgpd.conf` for bgpd is would be rendered.
+   * If CONFIG_DB`["DEVICE_METADATA"]["localhost"]["bgp_router_id"]` exists, use it as BGP router id.
+   * Else if Loopback0 IPv4 address exists, use it as BGP router id.
+   * Else, BGP router id wouldn't be specified. To be clarified that this scenario is out of scope for current HLD, behavior in the scenario that router-id isn't specified is totally same as previous.
+2. bgpd start with configuration rendered before. If router id is not specified, it would choose an IP address in device to be router id, which would cause BGP cannot work if the router id is not unique in network.
+3. After bgpcfgd started, it will start BGP peer based on configuration.
+   * If Loopback0 IPv4 address exists, continue to add BGP peer.
+   * Else if CONFIG_DB`["DEVICE_METADATA"]["localhost"]["bgp_router_id"]` exists, continue to add BGP peer.
+   * Else, stop to process neighbors adding and return with False signal.
+
+<p align=center>
+<img src="img/new_bgp_seq.png" alt="New bgp seq" width=750>
+</p>
+
+#### Multi-asic
+
+Below is new workflow for multi-asic, the main changes are in `1.` and `3.`. To be clarified that due to space limitations, the figure below only describes the behavior of one aisc in a multi-asic system. The behavior of other asics is similar to this one, except that they will start their own bgp\[x\] containers and read their respective config_db.
+
+1. After bgp0 container started, configuration file `/etc/frr/bgpd.conf` for bgpd is would be rendered.
+   * If CONFIG_DB`["DEVICE_METADATA"]["localhost"]["bgp_router_id"]` exists, use it as BGP router id.
+   * Else if Loopback4096 IPv4 address exists, use it as BGP router id.
+   * Else, BGP router id wouldn't be specified. To be clarified that this scenario is out of scope for current HLD, behavior in the scenario that router-id isn't specified is totally same as previous.
+2. bgpd start with configuration rendered before. If router id is not specified, it would choose an IP address in device to be router id, which would cause BGP cannot work if the router id is not unique in network.
+3. After bgpcfgd started, it will start BGP peer based on configuration.
+   * If current asic is FrontEnd
+     * If Loopback0 IPv4 address exists or bgp_router_id configured
+       * Add eBGP peer.
+       * If Loopback4096 IPv4 address exists, add iBGP peer.
+     * Else, stop to process neighbors adding and return with False signal.
+   * Else if current asic is BackEnd
+     * If Loopback0 IPv4 address exists or bgp_router_id configured
+       * If Loopback4096 IPv4 address exists, add iBGP peer
+       * Else, stop to process iBGP neighbors adding and return with False signal.
+     * Else, stop to process neighbors adding and return with False signal.
+
+<p align=center>
+<img src="img/new_bgp_seq_multi_asic.png" alt="New bgp seq multi asic" width=750>
+</p>
+
+### Config DB Enhancement
+
+#### DEVICE_METADATA
+
+**Configuration schema in ABNF format:**
+
+```abnf
+; DEVICE_METADATA table
+key             = DEVICE_METADATA|localhost ; Device metadata configuration table
+; field         = value
+bgp_router_id   = inet:ipv4-address         ; Customized BGP router id
+```
+
+**Sample of CONFIG DB snippet:**
+
+```json
+{
+    "DEVICE_METADATA": {
+        "localhost": {
+            "bgp_router_id": "10.1.0.32"
+        }
+    }
+}
+```
+
+**Snippet of `sonic-device_metatadata.yang`:**
+
+```
+module sonic-device_metadata {
+    container sonic-device_metadata {
+        container DEVICE_METADATA {
+            container localhost {
+                leaf bgp_router_id {
+                    type inet:ipv4-address
+                }
+            }
+            /* end of container localhost */
+        }
+        /* end of container DEVICE_METADATA */
+    }
+    /* end of top level container */
+}
+/* end of module sonic-device_metadata */
+```

doc/config-generic-update-rollback/SONiC_Generic_Config_Update_and_Rollback_Design.md

@@ -88,6 +88,7 @@
       - [3.2.2.1 Configuration Commands](#3221-configuration-commands)
       - [3.2.2.2 Show Commands](#3222-show-commands)
       - [3.2.2.3 Debug Commands](#3223-debug-commands)
+    + [3.2.3 Multi ASIC support](#323-multi-asics-support)
 - [4 Flow Diagrams](#4-flow-diagrams)
 - [5 Error Handling](#5-error-handling)
 - [6 Serviceability and Debug](#6-serviceability-and-debug)
@@ -872,6 +873,138 @@ show rollback log [exec | verify | status]
 
 Use the *verbose* option to view additional details while executing the different commands.
 
+### 3.2.3 Multi ASICs Support
+
+The initial design of the SONiC Generic Configuration Update and Rollback feature primarily focuses on single-ASIC platforms. To cater to the needs of Multi-ASIC platforms, this section introduces enhancements to support configuration updates and rollbacks across multiple ASICs and the host namespace.
+
+#### 3.2.3.1 Overview
+
+In Multi-ASIC SONiC platforms, configurations can be applied either globally, affecting all ASICs, or individually, targeting a specific ASIC or the host. The configuration management tools must, therefore, be capable of identifying and applying configurations based on their intended scope.
+
+#### 3.2.3.2 Namespace-aware Configuration Management
+
+The SONiC utilities for configuration management (apply-patch, checkpoint, and rollback) will be enhanced to become namespace-aware. These utilities will determine the target namespace for each operation from the configuration patch itself or from user input for operations that involve checkpoints and rollbacks.
+
+#### 3.2.3.3 JSON Patch Format Extension
+
+The JSON Patch format will be extended to include the namespace identifier for each operation's path. Path that operations the host namespace will be marked with a "localhost" identifier, while those intended for a specific ASIC will include an "asicN" identifier, where N denotes the ASIC number.
+
+```json
+[
+    {
+        "op": "add",
+        "path": "/asic0/PORTCHANNEL/PortChannel102/admin_status",
+        "value": "down"
+    },
+    {
+        "op": "replace",
+        "path": "/localhost/BGP_DEVICE_GLOBAL/STATE/tsa_enabled",
+        "value": "true"
+    },
+    {
+        "op": "replace",
+        "path": "/asic0/BGP_DEVICE_GLOBAL/STATE/tsa_enabled",
+        "value": "true"
+    },
+    {
+        "op": "replace",
+        "path": "/asic1/BGP_DEVICE_GLOBAL/STATE/tsa_enabled",
+        "value": "true"
+    }
+]
+```
+
+#### 3.2.3.4 Applying Configuration Changes
+
+When applying a configuration patch, the system will:
+
+    Parse the extended JSON Patch to identify the target namespaces.
+    Apply the operations intended for the host namespace directly to the host's configuration database.
+    Apply ASIC-specific operations to the respective ASIC's configuration database.
+
+#### 3.2.3.5 Checkpoints and Rollbacks
+
+Checkpoint and rollback operations will be enhanced to support Multi-ASIC platforms by:
+
+    Capturing the configuration state of all ASICs and the host namespace when creating a checkpoint.
+    Allowing rollbacks to restore the configuration state of all ASICs and the host namespace to a specific checkpoint.
+
+#### 3.2.3.6 Implementation Details
+
+The extension of the SONiC Generic Configuration Update and Rollback feature to support Multi-ASIC platforms enhances the flexibility and manageability of SONiC deployments in complex environments. By introducing namespace-aware configuration management, SONiC can efficiently handle the intricacies of Multi-ASIC platforms, ensuring smooth and reliable operation.
+
+    Namespace-aware Utilities: Update the SONiC configuration utilities to handle namespace identifiers in the configuration patches and command-line options for specifying target namespaces for checkpoints and rollbacks.
+
+    Validation and Verification: Extend the configuration validation and verification mechanisms to cover Multi-ASIC scenarios, ensuring that configurations are valid and consistent across all ASICs and the host.
+
+    CLI Enhancements: Introduce new CLI options to specify target namespaces for configuration operations, and to manage checkpoints and rollbacks in a Multi-ASIC environment.
+
+    Testing: Develop comprehensive test cases to cover Multi-ASIC configuration updates, including scenarios that involve simultaneous updates to multiple ASICs and the host.
+
+| Pull Request | Description |
+| --------- | ----------- |
+|[Add Multi ASIC support for apply-patch](https://github.com/sonic-net/sonic-utilities/pull/3249)|1. Categorize configuration as JSON patch format per ASIC.<br>2. Apply patch per ASIC, including localhost. |
+|[Add Multi ASIC support for Checkpoint and Rollback](https://github.com/sonic-net/sonic-utilities)|To be implemented|
+
+#### 3.2.3.7 Enhancement
+
+Given that applying patches or performing other actions on multiple ASICs can be time-consuming, we are introducing the -p option to expedite the process. This option operates under the assumption that each ASIC functions independently.
+
+| Pull Request | Description |
+| --------- | ----------- |
+|[Add Multi ASIC support for parallel option](https://github.com/sonic-net/sonic-utilities)|To be implemented|
+
+1. apply-patch
+    ```python
+    @config.command('apply-patch')
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='applying the change to all ASICs parallelly')
+    ...
+    def apply_patch(ctx, patch_file_path, format, dry_run, parallel, ignore_non_yang_tables, ignore_path, verbose):
+        ...
+    ```
+2. checkpoint
+    ```python
+    @config.command()
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='taking the checkpoints to all ASICs parallelly')
+    ...
+    def checkpoint(ctx, checkpoint_name, verbose):
+    ```
+3. replace
+    ```python
+    @config.command()
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='replacing the change to all ASICs parallelly')
+    ...
+    def replace(ctx, target_file_path, format, dry_run, ignore_non_yang_tables, ignore_path, verbose):
+        ...
+    ```
+4. rollback
+    ```python
+    @config.command()
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='rolling back the change to all ASICs parallelly')
+    ...
+    def rollback(ctx, checkpoint_name, dry_run, ignore_non_yang_tables, ignore_path, verbose):
+    ```
+5. list_checkpoints
+    ```python
+    @config.command()
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='listing the change to all ASICs parallelly')
+    ...
+    def list_checkpoints(ctx, checkpoint_name, dry_run, ignore_non_yang_tables, ignore_path, verbose):
+    ```
+6. delete_checkpoint
+    ```python
+    @config.command()
+    ...
+    @click.option('-p', '--parallel', is_flag=True, default=False, help='listing the change to all ASICs parallelly')
+    ...
+    def delete_checkpoint(ctx, checkpoint_name, dry_run, ignore_non_yang_tables, ignore_path, verbose):
+    ```
+
 # 4 Flow Diagrams
 
 # 5 Error Handling
@@ -909,6 +1042,16 @@ N/A
 | 14        | Dynamic port breakout as described [here](https://github.com/sonic-net/SONiC/blob/master/doc/dynamic-port-breakout/sonic-dynamic-port-breakout-HLD.md).|
 | 15        | Remove an item that has a default value. |
 | 16        | Modifying items that rely depends on each other based on a `must` condition rather than direct connection such as `leafref` e.g. /CRM/acl_counter_high_threshold (check [here](https://github.com/sonic-net/sonic-buildimage/blob/master/src/sonic-yang-models/yang-models/sonic-crm.yang)). |
+| 17        | Add a new ASIC config subtree. |
+| 18        | Add a new ASIC with empty config. |
+| 19        | Independent Patch Application: Apply configuration patches independently to each ASIC without any coordination between them. Verify that each ASIC updates according to its patch and that there are no discrepancies in configurations that might affect system operations.|
+| 20        | Simultaneous Patch Application:Apply configuration patches to all ASICs simultaneously to ensure that simultaneous updates do not cause conflicts or failures. This test checks the system’s ability to handle concurrent configuration changes across multiple independent units.|
+| 21        | Sequential Patch Application: Apply configuration patches to ASICs in a controlled sequence, one after the other. This test aims to check if the order of patch application affects the final system configuration, especially when configurations might not directly interact but could have cumulative effects.|
+| 22        |Patch Rollback Capability: After applying patches, initiate a rollback to previous configurations for each ASIC independently. Verify that each ASIC can revert to its previous state accurately and that the rollback process does not introduce new issues.|
+| 23        | Conditional Patch Application: Apply patches based on conditional checks within each ASIC’s configuration (e.g., only apply a patch if the current firmware version is below a certain level). This test ensures that conditions within patches are evaluated correctly and that the patch is applied only when the conditions are met.|
+| 24        | Cross-ASIC Dependency Verification: While each ASIC operates independently, this test involves applying patches that could potentially have indirect impacts on other ASICs through shared resources or network topology changes. Validate that changes in one ASIC do not adversely affect others.|
+| 25        | Patch Compatibility and Conflict Resolution: Apply patches that introduce changes conflicting with existing configurations across ASICs. This test examines how the system identifies and resolves conflicts, ensuring that the most critical settings are preserved and that any issues are clearly reported.|
+| 26        | Performance Impact Assessment: Measure system performance before and after patch application to determine the impact of configuration changes. This includes monitoring processing speed, memory usage, and network latency to ensure that performance remains within acceptable parameters.|
 
 ## 9.2 Unit Tests for Checkpoint
 | Test Case | Description |