mfyuce / tutorials

Set of tutorials that use PINS

Introduction

Welcome to the PINS-ONOS tutorial! P4 Integrated Network Stack (PINS) is a project that provides components and modifications to SONiC, allowing P4 and P4Runtime (P4RT) to control the network stack remotely. The Open Compute Project (OCP) summit in November 2021 launched PINS (talk video (34:09), talk slides, complete demonstration video (10:49), and demonstration slides).

This tutorial targets students and practitioners who want to run a functional SDN stack on SONiC. This document describes the required components, configuration, and commands to observe the interactions between a PINS switch and the SDN control plane.

Background

Highlights

The highlights of the PINS/SONiC project are:

• Opt-In Path Towards SDN: incrementally implement new SDN functions in SONiC
• Hybrid Control Plane Support: choose the network control plane and assign which parts run locally or remotely
• Familiar Interface: model the SAI pipeline in P4 to control bridging, routing, ACLs, tunnels, and more
• Rapid Innovation: develop new data plane features in P4 and expose them to control plane applications
• Automated Validation: test and validate packet paths in the forwarding pipeline with P4Runtime

Why would you want to add SDN functionality to SONiC?

When you add SDN functionality to SONiC, you can enable hitless route sequencing and inline network functions such as load balancers and firewalls. But more importantly, you can optimize data center utilization by analyzing In-band Network Telemetry (INT) and implementing Weighted Cost MultiPath (WCMP, aka UCMP).

What SDN functionality does PINS add to SONiC?

SONiC is based on a Switch Abstraction Interface (SAI), a standardized interface to allow programming and managing switch ASICs in a vendor-independent fashion. PINS works on all existing SONiC targets using SAI features, including fixed functions (e.g., routing) and configurable ones (e.g., ACLs). PINS programs the SAI pipeline in P4, bringing SDN capabilities to SONiC.

What components does PINS add to SONiC?

SONiC is structured into various containers that communicate via a shared Redis instance through multiple logical databases. The PINS project adds capabilities to SONiC as described in the PINS high-level design document. P4Runtime (P4RT) (code: Azure/sonic-pins) is a new application running in its own container that receives P4 programming requests from an SDN controller and writes intents to new P4 tables. In Azure/sonic-swss, P4Orch and P4RT tables were added to process database entries, create SAI objects, and add them to the ASIC database. PINS also introduces modifications to Azure/sonic-swss-common and Azure/sonic-buildimage.

Tutorial Outline

The tutorial and hands-on exercises familiarize users with PINS (webpage, Working Group Github repositories, wiki). Activities assume a basic knowledge of SONiC (webpage, Github repository, wiki) and SDN, including the P4 language and ONOS (webpage, wiki). We provide participants with configuration files and scripts.

The exercises provide step-by-step instructions and validation as follows:

1. Exercise 1 - Deploy SONiC/PINS Target Image: deploy target images on your switches
2. Exercise 2 - Configure Tutorial Network: configure host and switch interfaces
3. Exercise 3 - Set Up Pipeline and Routes: set up connections using a simple command-line interface for P4Runtime. This exercise uses only one route between two switches.
4. Exercise 4 - Deploy and Configure ONOS: deploy ONOS on your server and push the network configuration using flow objectives instead of the p4rt-client in the previous exercise. This exercise enables ECMP with two routes between the two switches.
5. Exercise 5 - PINS Fabric Demonstration: This exercise explores the demonstration environment at the OCP summit. ONF implemented PINS on a 2x2 leaf-spine fabric and demonstrated WCMP using ONOS and SD-Fabric.
6. Appendix - References: Other Examples and Tutorials are provided for particular areas of interest (i.e., P4, P4Runtime, gNMI, OpenConfig, ONOS, SONiC).
7. Appendix - Build it Yourself: instructions to build a SONiC/PINS target image and build ONOS with PINS.

Software Used in Tutorial

To complete the exercises in this tutorial, you will use a variety of Linux and SONiC commands either directly or in the scripts we provide. Because there may be more than one way to view the same information, you may use alternate commands. Some of the software you’ll use include docker, redis-cli, and curl.

For exercises 1 and 2, you will need to get the SONiC target images with PINS for your switches (.swi and/or .bin). If your switches do not have a previous version of SONiC installed, you will need to use the ONIE or Aboot installation software on your switch.

Exercise 3 provides instructions to get p4rt-client and macToIpv6. Exercise 4 provides instructions to get an ONOS image with the PINS driver and pipeline installed. The PINS tutorials repository contains sample configuration files for the exercises.

Download the configuration file examples from GitHub or clone the repository using one of the following:

• HTTPS: git clone https://github.com/pins/tutorials.git
• SSH: git clone [e-mail]:pins/tutorials.git
• GitHub CLI: gh repo clone pins/tutorials