gRPC tunnels
A gRPC tunnel is a client-server protocol like any other gRPC-based service. The gRPC tunnel concept is defined by OpenConfig (https://github.com/openconfig/grpctunnel) and is based on three entities:
- target
The target represents the network element.
- tunnel server
The tunnel server represents the software entity that tracks all registered targets, along with information about supported target types, all registered tunnel clients and the target type they subscribe to.
- tunnel clients
The tunnel client is a software entity that performs client tasks, such as requestion a session to the specified target.
The following figure shows the gRPC tunnel service concept.
After the registration process is complete, the tunnel server informs the tunnel client about all available targets supporting the target type that it is subscribed to. The tunnel client can then request a tunnel session toward a specific target. When a request is made, the tunnel server establishes a TCP tunnel between itself and the target (if one is not already open for another session) and establishes a tunnel session between the target and the tunnel client. After this session is established, the tunnel client can open any supported application session (gNMI or gNOI) toward applications on the target.
The following RPCs are defined to facilitate gRPC tunnels.
- RegisterRPC
The RegisterRPC is used to perform the following tasks:
- sent from a target to a tunnel server to register the network element after a reboot or the configuration of a gRPC tunnel on the network element
- sent from a tunnel client to a tunnel server to subscribe to a specific target type
- sent from a tunnel client to a tunnel server to request a session to a specified target with a specific target type
- TunnelRPC
The TunnelRPC is used for the actual exchange of data (in the form of TCP datagrams tagged with a tag ID agreed upon during the session registration phase of the RegisterRPC). The exchange of data on a TunnelRPC is initiated by the service used by the tunnel; for example, in a gNOI service, the controller opens a gNOI RPC that is tunneled through the gRPC tunnel. The network element handles this request like any other request received from the gNOI client directly.
Using a gRPC tunnel instead of a direct gRPC connection provides the following advantages:
-
Using a gRPC tunnel avoids firewall issues by initiating the TCP connection from the network element.
-
The network element registers itself, which provides active network element discovery.
-
The common gRPC tunnel interface on the network element does not require any adaptations to use different management interfaces, such as gNMI, gNOI, SSH, or NETCONF.
gRPC tunnels in SR OS
This section describes how to configure and use gRPC tunnels within SR OS.
gRPC tunnel architecture in SR OS
The main function of a gRPC tunnel is to allow tunneling of TCP datagrams between SR OS nodes and third-party software entities. To minimize the impact on existing services, the internal cross-connect sends the decapsulated packets on a preconfigured TCP port using the local host as the destination. In this way, all internal applications receive the same data as they would from an external TCP connection.
The simplified view of the internal SR OS implementation is shown in the following figure.
gRPC tunnel security
The OpenConfig gRPC tunnel specification requires TLS encryption at the tunnel and gRPC server level.
TLS encryption at tunnel level is configured by assigning the TLS client profile at the destination group level. It operates similarly to dial-out telemetry, as described in Dial-out telemetry.
When an external gRPC client connects to an SR OS gRPC server through a tunnel (rather than through direct TCP connection), the source address of the tunnel is used as the IP address to generate certificates. The TLS server profile assigned to the gRPC server must point to certificates that were generated using this IP address.
Configuring a gRPC tunnel in SR OS
To configure use gRPC tunnel, perform the following steps:
-
Configure the destination group.
- Configure 1 or 2 destinations using the destination command.
- Configure whether transport is secure or unsecure using the allow-secure-connection command.
- Configure the router instance using the router-instance command.
- Optionally, configure a local source address using the local-source-address command.
- Optionally, configure the TCP keepalive interval using the tcp-keepalive command.
-
Configure the gRPC tunnel.
- Assign a destination group using the destination-group command.
- Enable the tunnel.
- Define the target name using the target-name command.
- Configure one or more handlers using the handler command.
-
Configure the internal application server.
MD-CLI
[ex:/configure system] A:admin@node-2# info grpc-tunnel { destination-group "ba-server" { allow-unsecure-connection destination 1.1.1.1 port 33333 { router-instance "management" } } tunnel “test” { admin-state enable destination-group “ba-server” target-name { node-name} handler “my-grpc” { admin-state enable target-type { grpc-server } port 57400 } handler “ssh” { admin-state enable target-type { ssh-server } port 22 } } } grpc { admin-state enable allow-unsecure-connection gnmi { admin-state enable } }Classic CLIA:node-2>config>system# info grpc-tunnel destination-group "ba-server" create allow-unsecure-connection tcp-keepalive shutdown exit destination 1.1.1.1 port 33333 create router-instance "management" exit exit tunnel "test" create destination-group "ba-server" target-name node-name handler "ssh" create port 22 target-type ssh-server no shutdown exit handler "my-grpc" create port 57400 target-type grpc-server no shutdown exit no shutdown exit exit grpc allow-unsecure-connection no shutdown gnmi no shutdown exit exit
Verifying gRPC tunnel operation
This procedure describes the commands to use to verify gRPC tunnel operation.
-
Use the following command to view the state
of a GRPC tunnel.
show system grpc-tunnel tunnel tunnel-name===================================================================== gRPC-Tunnel tunnel =============================================================================== Name : test Administrative State : Enabled Operational State : Up Description : (Not Specified) Destination Group : ba-server Operational Target Name : DUT-A =============================================================================== -
Use the following command to view
destinations for a GRPC tunnel.
show system grpc-tunnel tunnel tunnel-name destinations====================================================================== gRPC-Tunnel tunnel ================================================================================ Name : test Administrative State : Enabled Operational State : Up Description : (Not Specified) Destination Group : ba-server Operational Target Name : DUT-A ------------------------------------------------------------------------------- Destinations ------------------------------------------------------------------------------- Destination : 1.1.1.1 Port : 33333 Operational State : Up Last Oper Down Reason : MINOR: GMI #2452: RPC refused by peer - error code 14 (UNAVAILABLE), error message: Connect Failed Oper Router Instance : management Last Oper Change : 2022/01/13 14:59:06 Connection Attempts : 11469 ------------------------------------------------------------------------------- No. of destinations : 1 ===============================================================================