Use Service Layer API to Bring your Controller on Cisco IOS XR Router

Bring your protocol or controller on IOS XR router to interact with the network infrastructure layer components using Service Layer API.

For example, you can bring your controller to gain control over the BGP Routing Information Base (RIB) tables and many more use cases.

Get to Know Service Layer API

Service Layer API is a model-driven API over Google-defined remote procedure call (gRPC).

gRPC enables you to bring your applications, routing protocols, controllers in a rich set of languages including C++, Python, GO, and many more.

Service Layer API is available out of the box and no extra packages required.

In IOS XR, routing protocols use RIB, the MPLS label manager, BFD, and other modules, to program the forwarding plane. You can expose these protocols through the service layer API.

Benefits

The Service Layer API gives direct access to the Network Infrastructure Layer (Service-Adaptation Layer). Therefore, you have the following advantages:

  • High Performance: Direct access to the Network Infrastructure Layer, without going through a Network state database, results in higher performance than equivalent Management APIs

    For example, Batch updates straight to the RIB, Label Switch Database (over gRPC)

  • Flexibility: The Service Layer API gives you the flexibility to bring your Protocol or Controller over gRPC.

  • Offload low-level tasks to IOS XR: IOS XR infrastructure layer handles the following. Hence, you can focus on higher-layer protocols and controller logic:

    • Conflict resolution

    • Transactional notifications

    • Data plane abstraction

Components of Service Layer API

The following are the components of the Service Layer API architecture:

  • Functionality Verticals/Domains: The verticals define the broader capability categories supported by the API. The following are the supported verticals. Each vertical supports data structure and RPCs defined in gpb

    • Initialization: Handles global initialization, sets up an event notification channel using GRPC streaming capabilities.

      The initialization RPCs are mandatory. Use the initialization RPCs to connect a client to the gRPC server on the router. Also, to send heartbeats and termination requests from the server to the client.

    • IPv4, IPv6 Route (RIB): Handles route manipulations (add, update, delete) for a certain VRF.

    • MPLS: Handles allocation of label blocks and any incoming MPLS label mapping to a forwarding function.

    • Interface: Handles subscription of the registered clients to the interface state event notifications.

    • IPv4, IPv6 BFD: Manages BFD sessions, and corresponding BFD session state notifications.

  • Protobuf Schema/Model: Use any potential modeling technique to model the service layer API. Currently, we use the GPB protobuf IDL.

  • gRPC: gRPC utilizes GPB protobuf IDL by default to convert the models into bindings in various languages (c++, python, golang, and more). The gRPC server (running on the router) and the gRPC client use the generated bindings to serialize data and encode or decode the request or response between the server and the client.

  • Service Layer gRPC clients: Based on the business needs, the gRPC clients for service layer can exist in one of the following ways:

    • On-box (agents/protocol-stacks running natively or in containers)

    • Off-box (within Controllers or other open-source tools)

Figure 1. Components of Service Layer API
Service Layer API components

Bring your controller

To bring your controller on IOS XR, first, enable the service layer on the router and then write your Service Layer Client API.

  1. Enable Service Layer

  2. Write Your Service Layer Client API.

Enable Service Layer

Procedure

Step 1

Enable the Service Layer.

Example:


Router#configure
Router(config)#grpc
Router(config-grpc)#port 57777
Router(config-grpc)#service-layer
Router(config-grpc)#no-tls
Router(config-grpc)#commit

Step 2

Verify if the Service Layer is operational:

Example:


Router#show running-config grpc
Mon Nov  4 04:19:14.044 UTC
grpc
 port 57777
 no-tls
 service-layer
 !
!

Step 3

Verify the gRPC state.

Example:


Router#show service-layer state
Mon Feb 24 04:18:40.055 UTC
------------service layer state----------
config on:                   YES
standby connected :          NO
idt done:                    NO
blocked on ndt:              NO
connected to RIB for IPv4:   YES
connected to RIB for IPv6:   YES
Initialization state:        estab sync
pending requests:            0
BFD Connection:              UP
MPLS Connection:             UP
Interface Connection:        UP
Objects accepted:            NO
interface registered:        NO
bfd registered for IPv4:     NO
bfd registered for IPv6:     NO

Write Your Service Layer Client API

You can write a Service Layer API based on your business needs. Follow these steps to write a Service Layer API client for a particular functionality vertical.

  • Import Bindings: After generating the bindings, import the binding in your code.

  • Open Notification Channel: Utilize the initialization functionality vertical to create a notification channel to register the client to the gRPC server running on the router.

  • Register against Vertical: Register for a functionality vertical to utilize an RPC using the registration RPC before making calls. The system rejects any calls without prior registration.

  • Use RPCs: Once registered against a vertical, select the RPC of your choice. Then complete the object fields in the gRPC stub.

To know more about creating a Service Layer API, see. Cisco IOS-XR Service Layer.

Figure 2. Service Layer API Workflow