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 which performs client tasks, such as requestion a session to the specified target.

The following figure shows the gRPC tunnel service concept.

Figure 1. 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.

Figure 2. Internal SR OS architecture

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 (instead of 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:

  1. Configure the destination group.
    1. Configure 1 or 2 destinations using the destination command.
    2. Configure whether transport is secure or unsecure using the allow-secure-connection command.
    3. Configure the router instance using the router-instance command.
    4. Optionally, configure a local source address using the local-source-address command.
    5. Optionally, configure the TCP keepalive interval using the tcp-keepalive command.
  2. Configure the gRPC tunnel.
    1. Assign a destination group using the destination-group command.
    2. Enable the tunnel.
    3. Define the target name using the target-name command.
    4. Configure one or more handlers using the handler command.
  3. 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 CLI
    A: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 used to verify gRPC tunnel operation.

  1. 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
    =============================================================================== 
    
  2. 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
    ===============================================================================