Back
Lesson 4 of 6

gNOI for Network Operations

Objective

In this lesson you will learn how to use gNOI (gRPC Network Operations Interface) for two common operational tasks: certificate management (install/provision) and OS lifecycle (install → activate → verify). These gNOI services let automation tools push operational actions (not just configuration) to network devices over secure gRPC/gNMI channels. In production, gNOI is used when you need programmatic, auditable, and repeatable node operations such as automated certificate rotation, scheduled OS upgrades, or verification during maintenance windows.

Real-world scenario: An operations team needs to provision TLS certificates to a fleet of switches and then stage/activate an IOS XE image on one device during a maintenance window — doing both tasks from an automation host instead of manual CLI sessions.

Quick Recap

This lesson builds on the topology introduced earlier. No new devices are added for this lesson; we interact from an automation client (gNOI/gNMI tooling) to existing network devices. The two target management IPs used in examples below are taken from the reference:

ASCII topology (management plane view — exact IPs shown):

[gNOI Client / Automation Host]
    |
    | gNOI target_addr: 10.85.134.92:9339   (target_name: c9300)
    |
    | gNOI target_addr: 10.1.1.5:9339      (target_name: c9300)

Device table

Device nameRoleManagement IP / gNOI target_addr
c9300-1gNOI target (switch/router)10.85.134.92:9339
c9300-2gNOI target (switch/router)10.1.1.5:9339

Tip: gNOI operations are executed over the gNMI transport; tools on the client use the device management IP and the gNOI port (9339) as shown.

Key Concepts

  • gNOI vs gNMI: gNOI defines a set of gRPC-based operational microservices (OS install, certificate management, reset, etc.). These services are accessed via the gNMI API transport on devices that implement the gNMI server. Think of gNMI as the tunnel carrying both telemetry (gNMI) and operational RPCs (gNOI) — like a highway that carries many types of vehicles.

  • Cert.proto: The gNOI certificate management API (cert.proto) supports operations such as provision, install, rotate, revoke, get and check. When you provision a certificate with gNOI, the device applies the certificate and the gNMI/gNOI server may restart to pick up the new identity certificate — this is why automation workflows must handle transient restarts.

  • OS.proto: The OS service implements install, activate, and verify RPCs for the network OS image. The workflow is: provide the binary to the device (install), switch the active image (activate), then confirm the running version (verify). Automation tools call these RPCs in sequence with timeout controls.

  • NACM (Model-based authorization): NACM (NETCONF Access Control Model) is used to restrict gNMI/gNOI CRUD/exec operations. You can populate a read-only rule set for telemetry users (privilege mapping). In IOS XE this is managed via YANG DMI commands such as request platform software yang-management nacm populate -read-rules privilege 1.

  • Security & Authentication: gNOI/gNMI use TLS certificates (mutual TLS) or user/password combos depending on deployment. In production you must plan authentication (certs vs password), login authorization (TACACS/Radius), NACM policies, and ACLs to restrict gNMI service endpoints.

Step-by-step configuration

Step 1: Populate NACM read-only rules for telemetry (enable safe read-only access)

What we are doing: Configure the device's YANG NACM policy so telemetry/gNMI clients mapped to privilege 1 get read-only access. This prevents accidental create/update/delete/exec operations by those telemetry users.

request platform software yang-management nacm populate -read-rules privilege 1

What just happened: This command invokes the YANG DMI helper on IOS XE to populate NACM rules that set the default access for the specified privilege level to read-only. Internally the device stores NACM rules in the YANG datastore (persistent across reloads) and ties them to the ietf-netconf-acm model so that gNMI/gNOI operations will be subject to this read-only enforcement.

Real-world note: Use this in production when you want your telemetry collectors to only read state — never allow them to change configuration or execute device actions.

Verify:

request platform software yang-management nacm populate -read-rules privilege 1
NACM populate operation completed: read-only rules added for privilege 1

(Expect a confirmation indicating the populate operation completed. The NACM rules themselves can be inspected via a management system performing a GET against the NACM YANG path.)

Step 2: Provision a TLS certificate to a device using gNOI (cert.proto)

What we are doing: Use the gNOI certificate management tool to provision a certificate to the target at 10.1.1.5:9339. This replaces (or adds) a certificate identity used by gNMI/gNOI, and the gNMI service will restart to apply the new certificate.

gnoi_cert -insecure -target_addr 10.1.1.5:9339 -op provision -target_name c9300 -alsologtostderr -organization "jcohoe org" -ip_address 10.1.1.5 -time_out=10s -min_key_size=2048 -cert_id gnxi-cert -state BC -country CA -ca ./rootCA.pem -ca_key ./rootCA.key

What just happened: The gNOI cert client created a CSR (or used provided key material) and sent the provisioning RPC to the device at 10.1.1.5:9339. The device applied the certificate (as per cert.proto semantics) and restarted the gNMI/gNOI service so the new certificate becomes active. Certificate provisioning via gNOI is an automation-friendly substitute for manual crypto pki steps or YANG-based certificate RPCs.

Real-world note: Certificate provisioning often causes the gNMI service to restart; your automation should detect and retry the subsequent gNOI/gNMI calls until the service is back.

Verify:

gnoi_cert -insecure -target_addr 10.1.1.5:9339 -op get -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key
Installed certificates:
- cert_id: gnxi-cert
  subject: CN=10.1.1.5, O="jcohoe org", ST=BC, C=CA
gNMI service: restarted to apply new certificate

(Expect output enumerating the installed certificates and confirmation the service restarted. The exact textual output may vary by client/tool but should list the newly provisioned cert_id.)

Step 3: Verify current OS version via gNOI OS verify RPC

What we are doing: Use the gNOI OS client to ask the device for its currently running OS version. This helps you confirm current baseline before performing an install/activation.

gnoi_os -insecure -target_addr 10.85.134.92:9339 -op verify -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key

What just happened: The gNOI OS verify RPC queried the target at 10.85.134.92 and returned the running image version. The verify RPC is read-only and useful for pre/post-upgrade checks.

Real-world note: Always verify the running version before activation to avoid accidental reboots or mismatched images.

Verify:

Running OS version: 17.05.01.0.144.1617180620

(Expect the gNOI client output to list the running image version text as shown above.)

Step 4: Install an OS image on the device via gNOI OS install RPC

What we are doing: Initiate a remote OS install by pointing the device to the OS bundle (for example, a TFTP path). This stage tells the device to stage the image and prepare it for activation. We use the install RPC with a desired version and file location.

gnoi_os -insecure -target_addr 10.85.134.92:9339 -op install -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key -version 17.06.01.0.135639.1618187331 -time_out 999s -os/tftpboot /cat9k_iosxe.17.06.01-20210411.bin

What just happened: The gNOI client sent the install RPC with the target version and the path where the image binary is accessible on the device (for example, a TFTP-mounted file). The device will copy/verify the image and stage it into the install repository. This is the long-running step and therefore includes a large timeout.

Real-world note: Large device images can take many minutes to transfer and verify — always increase timeouts and consider using out-of-band image staging (e.g., pre-place the image on the device) for predictable maintenance windows.

Verify:

gnoi_os -insecure -target_addr 10.85.134.92:9339 -op install -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key -version 17.06.01.0.135639.1618187331 -time_out 999s -os/tftpboot /cat9k_iosxe.17.06.01-20210411.bin
Installation status: success
Staged version: 17.06.01.0.135639.1618187331

(Expect confirmation that the install completed and that the requested version is now staged. If the image staging is still in progress, the client will report progress or require a longer timeout.)

Step 5: Activate the staged image and verify running version via gNOI

What we are doing: Activate the previously staged image so the device will boot into the new version on next reload (or immediately, depending on device behavior). After activation, run the verify RPC to confirm the running OS version.

gnoi_os -insecure -target_addr 10.85.134.92:9339 -op activate -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key -version 17.06.01.0.135639.1618187331 -time_out 999s -os/tftpboot /cat9k_iosxe.17.06.01-20210411.bin

What just happened: The activate RPC told the device to make the staged image the active boot image. Depending on platform semantics, activation may schedule a reload; the OS proto is explicit about activation semantics so automation can handle a reload if required. After activation and device reload, use verify to confirm the running image.

Real-world note: Coordinate activation with change windows — activating an image commonly leads to a reboot or switchover depending on platform.

Verify (post-activation):

gnoi_os -insecure -target_addr 10.85.134.92:9339 -op verify -target_name c9300 -alsologtostderr -cert ./client.crt -ca ./rootCA.pem -key ./rootCA.key
Running OS version: 17.06.01.0.135639.1618187331

(Expect the verify RPC to now show the new running version, confirming successful activation.)

Verification Checklist

  • Check 1: NACM read-only rules populated — run the populate command and expect confirmation that read-only rules have been added for privilege 1.
  • Check 2: Certificate provisioned — run the gNOI cert get or get/list command and expect to see the cert_id (gnxi-cert) and subject including IP 10.1.1.5.
  • Check 3: OS staged and activated — run gNOI OS verify before and after install/activate; expect the running OS version to change from 17.05.01.0... to 17.06.01.0...

Common Mistakes

SymptomCauseFix
gNOI client times out during installImage transfer or staging is large and timeout too shortIncrease -time_out and ensure image file is accessible from device (TFTP/HTTP path)
gNOI cert provision returns connection errorTLS mismatch or client certs not accepted by deviceVerify CA trust chain and client cert/key used by gnoi_cert; ensure device is reachable at listed IP and port
After provisioning, gNMI client reports certificate errorgNMI service restarted; client connected with old TLS sessionRe-establish gNMI/gNOI connections after provisioning; handle transient service restart in automation
Read-only behavior not enforced for telemetry usersNACM not populated or privilege mapping wrongRe-run request platform software yang-management nacm populate -read-rules privilege 1 and confirm NACM is present; use device management tooling to inspect NACM YANG data

Key Takeaways

  • gNOI provides automation-friendly RPCs for operational tasks such as certificate provisioning (cert.proto) and OS lifecycle (os.proto). Use these to standardize and automate device operations.
  • Always plan for service restarts: provisioning a new TLS certificate will typically restart the gNMI/gNOI service; automation must tolerate transient disconnects.
  • Use NACM to restrict gNMI/gNOI access: populate read-only rules for telemetry roles so collectors cannot perform write or exec operations.
  • Verify at every stage: run gNOI OS verify before and after installs/activations and list installed certificates after provisioning to ensure the expected state.

Important: Automation workflows should incorporate retries, timeouts appropriate for large binaries, and checks for service restarts when performing gNOI operations in production.

Practice with Hands-On Labs

30 step-by-step labs for CCNA, CCNP Enterprise & Security