diff --git a/docs/mgmt/gnoi_sw_upgrade.md b/docs/mgmt/gnoi_sw_upgrade.md new file mode 100644 index 00000000..f1aadcde --- /dev/null +++ b/docs/mgmt/gnoi_sw_upgrade.md @@ -0,0 +1,395 @@ +# Software Upgrade using gNOI + +SR Linux is a modern Network Operating System (NOS), and it should come as no surprise that modern management tools like [gRPC](https://grpc.io) can be used to manage switches or routers running this NOS. + +In this article, we provide a step-by-step guide to perform a software upgrade (or a downgrade) using the gRPC gNOI service. + +gRPC is an HTTP/2-based RPC (Remote Procedure Call) framework that allows for the management and operation of a destination device. gRPC operates using a client-server model. In the networking world, the server is typically a switch or router. + +Within the gRPC framework, the following services are defined for specific functions. Each service has a set of defined RPCs, and each RPC has a set of inputs and output methods. + +- **gNMI** (gRPC-based Network Management Interface): + gNMI RPCs can be used to configure, retrieve state, or stream telemetry from a destination device. This is by far the most popular gRPC service in the networking industry today. + +- **gNOI** (gRPC-based Network Operations Interface): + gNOI RPCs can be used to manage device operations such as ping, traceroute, reboot, and software upgrade. + +- **gNSI** (gRPC-based Network Security Interface): + gNSI RPCs can be used to manage security and accounting-related configuration. + +- **gRIBI** (gRPC-based Routing Information Base Injection): + gRIBI RPCs can be used to inject routes into the device RIB for traffic steering and traffic engineering. + +Refer to the [gNxI](https://gnxi.srlinux.dev) page for details on each RPC. + +## gNOI + +When focusing on gNOI, it has a wide variety of RPCs to operate the device. + +- [System](https://gnxi.srlinux.dev/gnoi/system) RPCs are used for actions like ping, traceroute and device reboot + +- [File](https://gnxi.srlinux.dev/gnoi/file) service RPCs are used to transfer files to or from the device + +- [OS](https://gnxi.srlinux.dev/gnoi/os) service RPCs are used for software image transfer and software upgrade + +- [Healthz](https://gnxi.srlinux.dev/gnoi/healthz) service RPCs are used to obtain the health of hardware components + +- [Factory Reset](https://gnxi.srlinux.dev/gnoi/factory_reset) RPCs are used to perform a factory reset of the device + +- [Packet Link Qualification](https://gnxi.srlinux.dev/gnoi/packet_link_qualification) RPCs are used to check the health of a link + +## gNOI OS Service + +gNOI OS RPCs can be used to manage the software upgrade of a device. + +The OS service supports the following RPCs: + +- [Verify](https://gnxi.srlinux.dev/gnoi/os#VerifyRequest) RPC: to check the current software version running on the device + +- [Install](https://gnxi.srlinux.dev/gnoi/os#InstallRequest) RPC: to transfer a software image to the device + +- [Activate](https://gnxi.srlinux.dev/gnoi/os#ActivateRequest) RPC: to activate a software version on the device and optionally reboot the device to activate the new version + +## Software upgrade procedure + +Now let's use gNOI RPCs to perform a software upgrade of SR Linux. + +### Device and version + +Our device under test (DUT) is a 7220 IXR-H3 running SR Linux version `24.10.5` with a management IP of `10.0.1.204`. + +```srl hl_lines="4 9" +A:admin@srlinux# show version +--------------------------------------------------------- +Hostname : srlinux +Chassis Type : 7220 IXR-H3 +Part Number : 3HE16425AARA01 +Serial Number : NK222511561 +System HW MAC Address: AC:8F:F8:70:0A:52 +OS : SR Linux +Software Version : v24.10.5 +Build Number : 344-g1c1a8d80ff4 +Architecture : x86_64 +Last Booted : 2025-12-03T04:55:56.926Z +Total Memory : 32086031 kB +Free Memory : 29913683 kB +--------------------------------------------------------- +``` + +We will use [gNOIc](https://gnoic.kmrd.dev) as the gNOI client. + +To install the client on a VM, run: + +```bash +bash -c "$(curl -sL https://get-gnoic.kmrd.dev)" +``` + +To verify the gNOIc installation and version, run: + +```bash +gnoic version +``` + +/// warning + +A software upgrade cannot be executed on an SR Linux docker image in Containerlab. A physical device is required for this purpose. +/// + +### Enable gNOI service in SR Linux + +gNOI service configuration is under gRPC. To simplify our process, we will use unencrypted (non-TLS) communication between gNOI client and the switch. + +The gRPC configuration on our DUT is as follows: + +```srl +set / system grpc-server mgmt admin-state enable +set / system grpc-server mgmt network-instance mgmt +set / system grpc-server mgmt services [ gnmi gnoi gnsi ] +``` + +This configuration allows all gNOI RPCs from the client. Optionally, you can also selectively enable specific gNOI services like gnoi.file. + +### Check gNOI communication + +Before we start the software upgrade process, let's verify the gNOI communication between the client and the switch. + +We will use the gNOI System time RPC to get the current timestamp of the switch. + +On the VM where the gnoic client is installed, run: + +///tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure system time +``` + +/// +///tab | Expected output + +```bash ++------------------+-----------------------------------------+---------------------+ +| Target Name | Time | Timestamp | ++------------------+-----------------------------------------+---------------------+ +| 10.0.1.204:57400 | 2025-12-02 19:23:50.356281777 -0600 CST | 1764725030356281777 | ++------------------+-----------------------------------------+---------------------+ +``` + +/// + +We have now verified the communication between the gNOIc client and the switch. + +### Verify current software version + +Now, let's verify the current software version running on the switch. + +We will use the gNOI OS verify RPC for this purpose. + +On the VM, run: + +///tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os verify +``` + +/// +///tab | Expected output + +```bash ++------------------+-------------+---------------------+ +| Target Name | Version | Activation Fail Msg | ++------------------+-------------+---------------------+ +| 10.0.1.204:57400 | 24.10.5-344 | | ++------------------+-------------+---------------------+ +``` + +/// + +We verified that the current version is 24.10.5. + +### Transfer new software image + +Our objective is to upgrade the switch to SR Linux `25.10.1`. + +The software image file is locally available on the VM. + +We will use the gNOI OS Install RPC to transfer the image to the switch. + +The Install RPC is a synchronous RPC that transfers the image in chunks and performs a checksum at the end of the transfer. + +/// admonition + type: info +Starting with SR Linux 25.3, there is a rate limit applied by default for synchronous RPCs. Before attempting an OS Install RPC on versions 25.3 or later, increase the rate limit under `system grpc-server rate-limit`. +/// + +On the VM, run: + +///tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os install --version srlinux_25.10.1-399 --pkg gnoi/srlinux-25.10.1-399.bin +``` + +/// +/// tab | Expected output + +```bash +INFO[0000] starting install RPC +INFO[0000] target "10.0.1.204:57400": starting Install stream +INFO[0000] target "10.0.1.204:57400": TransferProgress bytes_received:5242880 +INFO[0000] target "10.0.1.204:57400": TransferProgress bytes_received:10485760 + +INFO[0029] target "10.0.1.204:57400": TransferProgress bytes_received:1599078400 +INFO[0029] target "10.0.1.204:57400": TransferProgress bytes_received:1604321280 +INFO[0029] target "10.0.1.204:57400": TransferProgress bytes_received:1609564160 +INFO[0029] target "10.0.1.204:57400": TransferProgress bytes_received:1614807040 +INFO[0029] target "10.0.1.204:57400": sending TransferEnd +INFO[0029] target "10.0.1.204:57400": TransferProgress bytes_received:1620049920 +INFO[0029] target "10.0.1.204:57400": TransferContent done... +``` + +/// + +### Taking a configuration backup + +Before we activate the new software version, it is best practice to take a configuration backup and store it outside the switch. + +We will use the gNOI File Get RPC for this purpose. This RPC will transfer the SR Linux configuration file to the VM under the `gnoi/config-24-10-backup` directory. + +On the VM, run: + +/// tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure file get --file /etc/opt/srlinux/config.json --dst gnoi/config-24-10-backup +``` + +/// +/// tab | Expected output + +```bash +INFO[0000] "10.0.1.204:57400" received 64000 bytes +INFO[0000] "10.0.1.204:57400" received 18171 bytes +INFO[0000] "10.0.1.204:57400" file "/etc/opt/srlinux/config.json" saved +``` + +/// +/// tab | Check on VM + +```bash +ls -lrt gnoi/config-24-10-backup/etc/opt/srlinux/config.json +``` + +/// +/// tab | Expected output + +```bash +-rw-r--r-- 1 root root 82171 Dec 9 22:23 gnoi/config-24-10-backup/etc/opt/srlinux/config.json +``` + +/// + +### Activate new software version + +After successfully transferring the software image, we can proceed to activate the software image. + +We will use the gNOI OS Activate RPC for this purpose. + +/// admonition + type: info +By default, the Activate RPC will perform a reboot of the device to activate the new software. To avoid a reboot during activation (and perform reboot at a later time), use the `--no-reboot` flag in the gnoic command. +/// + +Run the following command to activate the new software with a device reboot. + +/// tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os activate --version 25.10.1-399 +``` + +/// +/// tab | Expected output + +```bash +INFO[0004] target "10.0.1.204:57400" activate response "activate_ok:{}" +``` + +/// + +### Verify software version + +After the device boots up successfully, verify the current software version of the device and confirm that the software upgrade was a success. + +///tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os verify +``` + +/// +///tab | Expected output + +```bash ++------------------+-------------+---------------------+ +| Target Name | Version | Activation Fail Msg | ++------------------+-------------+---------------------+ +| 10.0.1.204:57400 | 25.10.1-399 | | ++------------------+-------------+---------------------+ +``` + +/// + +/// admonition + type: success +We have successfully upgraded the device to 25.10 +/// + +## Software downgrade procedure + +The downgrade procedure is similar to the upgrade process using the same gNOI OS RPCs. + +For our example, we will downgrade to our original version `24.10.5`. + +### Restore configuration backup + +Before downgrading the device, it is important to restore the original configuration from `24.10.5`. + +We will use gNOI File Put RPC to transfer the configuration backup available on the VM to the switch. The file will be transferred to the `/tmp` directory. The file can then be copied over to overwrite the `/etc/opt/srlinux/config.json` file. + +/// tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure file put --file gnoi/config-24-10-backup/etc/opt/srlinux/config.json --dst /tmp/config.json +``` + +/// +/// tab | Expected output + +```bash +INFO[0000] "10.0.1.204:57400" sending file="gnoi/config-24-10-backup/etc/opt/srlinux/config.json" hash +INFO[0000] "10.0.1.204:57400" file "gnoi/config-24-10-backup/etc/opt/srlinux/config.json" written successfully +``` + +/// + +Log in to the switch and run the below command to overwrite the default configuration file with the backup. + +```bash +bash cp /tmp/config.json /etc/opt/srlinux/config.json +``` + +### Transfer software image + +If the device is being downgraded to a different software release, transfer the image using the previously mentioned example. + +### Activate the downgrade + +We will use the same gNOI OS Activate RPC. + +On the VM, run: + +/// tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os activate --version 24.10.5-344 +``` + +/// +/// tab | Expected output + +```bash +INFO[0003] target "10.0.1.204:57400" activate response "activate_ok:{}" +``` + +/// + +### Verify the current version + +///tab | gNOIc command + +```bash +gnoic -a 10.0.1.204 -u admin -p admin --insecure os verify +``` + +/// +///tab | Expected output + +```bash ++------------------+-------------+---------------------+ +| Target Name | Version | Activation Fail Msg | ++------------------+-------------+---------------------+ +| 10.0.1.204:57400 | 24.10.5-344 | | ++------------------+-------------+---------------------+ +``` + +/// + +/// admonition + type: success +We have successfully downgraded the device to 24.10.5 +/// + +## Summary + +Software upgrade automation is not an easy task. In this article, we showcased how modern tools like gRPC can be used to simplify and automate a software upgrade process from a remote client. diff --git a/mkdocs.yml b/mkdocs.yml index 259f7d61..c68c4850 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,8 @@ nav: - Wildcards and ranges: blog/posts/2023/cli-ranges.md - SNMP: - SNMP Framework: snmp/snmp_framework.md + - gNOI: + - Software Upgrade: mgmt/gnoi_sw_upgrade.md # - Knowledge Base: # - Hardware types: kb/hwtypes.md