Programming Device APIs

Transcription

1

2 Programming Device APIs Fabrizio Maccioni Technical Marketing Engineer - Cisco BRKSDN-2119

3 Agenda Introduction Device APIs History WSMA NETCONF 1.0 Model Driven Programmability NETCONF 1.1 RESTCONF grpc REST APIs: APIC-EM Key Takeaways

4 Introduction

5 Programmability, Automation, Orchestration, APIs terminology Orchestration Cloud Integration Policy Orchestration Applications Open Developer Friendly Secure Northbound APIs RESTful GET PUT POST DELETE Automation Automation Abstraction & Policy Control from Core to Edge Analytics Network Data, Contextual Insights Programmability Open & Programmable Standards-Based Secure Flexible Infrastructure Physical & Virtual Infrastructure App Hosting Southbound APIs NETCONF RESTCONF grpc Software Driven Extensible Cloud Enabled Secure

6 Configuration Management Today CLI CLI Physical and Virtual Network Infrastructure

7 Configuration Management Today: CLI Human Friendly Task Oriented Easy To Replay No Special Tools Syntax format changes No Structured output No Error Reporting No Transaction manageme nt

8 SNMP for Device Monitoring Only Lack of Writeable MIBs Security Concerns Hard to Replay / Rollback Requires special application Lousy Models Hard to Scalability Parse Issues... SNMP works reasonably well for Device Monitoring Does not work well for Configuration

9 Configuration Management Today CLIs are for humans Machines CLI need CLI APIs (Open Programmable Interfaces) Physical and Virtual Network Infrastructure

10 APIs (Application Programming Interface) A set of Function Calls that allow talking to a system Programming Building block APIs can have various Properties Transport (i.e. SSH, HTTP) Encoding (i.e. XML, JSON, ProtoBuffer) Data structure (Data Models) Some Examples of APIs Twitter API Java API APIC-EM API

11 A key Ask: Consistency Inconsistency is Death to Automation Not Much Better than CLI CLI NETCONF/ YANG NX-API CLI NX-API REST CLI Parser NETCONF Data Model (YANG) NGNIX NGNIX Data Model (DME) Device Features Device Features Device Features Device Features BGP QoS ACL BGP QoS ACL BGP QoS ACL BGP QoS ACL Catalyst 4K Catalyst 3K Nexus 7K Nexus 9K

12 Encoding Formats & REST APIs RESTful GET PUT POST DELETE

13 Encoding Formats XML, JSON, YAML are Text-file formats used to store structured data for embedded and Web applications

14 XML (extensible Markup Language) Compare to [traditional] HTML HTML to display data, case-insensitive XML to describe data, case-sensitive <tag>value</tag> Readable format for structuring data Transmits data between servers and web apps Comprised of Tags and Value XML is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable

15 JSON (JavaScript Object Notation) Jason Readable format for structuring data key : value Comprised of Key/Value pairs Value: Array, Boolean, Number, String Largely replacing XML JSON is an open-standard format that uses human-readable text to transmit data objects consisting of attribute value pairs. It is the most common data format used for asynchronous browser/server communication,

16 YAML (YAML Ain t Markup Language) No marked blocks (like Python) key: value Simpler than XML/JSON Comprised of Key/Value pairs It is standard (RFC 2822) YAML is a human-readable data serialization language that takes concepts from programming languages such as C, Perl, and Python, and ideas from XML (RFC 2822)

17 XML vs JSON vs YAML <interfaces xmlns:= [ ]yang:ietf-interfaces > <interface> <name>eth0</name> <type>ethernetcsmacd</type> <location>0</location> <enabled>true</enabled> <if-index>2</if-index> </interface> </interfaces> { } "ietf-interfaces:interfaces": { "interface": [ { "name": "eth0, "type": "ethernetcsmacd, "location": "0, "enabled": true, "if-index": 2 } ] } --- ietf-interfaces:interfaces: interface: name: eth0 type: ethernetcsmacd location: 0 enabled: true if-index: 2 Elements <> Parsers and Validation Key-Value Pairs Readable Simpler

18 REST RESTful GET PUT POST DELETE API GET POST PUT DELETE A framework not a standard Architectural constraints Client server Stateless Cacheable Layered system Uniform interface

19 Device APIs History (Application Programming Interface)

20 History of Device API in Cisco NETCONF 1.0 WSMA onepk NETCONF API: Application Programming Interface

21 WSMA Web Services Management Agent

22 WSMA show ip interface brief <request xmlns="urn:cisco:wsma-exec" correlator="show int gig1"> <execcli maxwait="pt100s" xsd="false" format="builtin"> <cmd>show ip int br</cmd> </execcli> </request> WSMA HTTP / HTTPS <Interface>GigabitEthernet1</Interface> <IP-Address> </IP-Address> <OK>YES</OK> <Method>manual</Method> <Status>up</Status> <Protocol>up</Protocol>

23 Configuration ip http authentication local ip http secure-server wsma agent exec profile httpslistener wsma agent config profile httpslistener wsma agent filesys profile httpslistener wsma agent notify profile httpslistener! wsma profile listener httpslistener transport https

24 Unformatted Data is Hard to Parse csr# show ip interface brief Interface IP-Address OK? Method Status Protocol GigabitEthernet YES manual up up csr# show ip interface brief format <?xml version="1.0" encoding="utf-8"?> <ShowIpInterfaceBrief xmlns="odm://built-in//show_ip_interface_brief"> <SpecVersion>built-in</SpecVersion> <IPInterfaces> <entry> <Interface>GigabitEthernet1</Interface> <IP-Address> </IP-Address> <OK>YES</OK> <Method>manual</Method> <Status>up</Status> <Protocol>up</Protocol> </entry> </IPInterfaces> </ShowIpInterfaceBrief>

25 Now via API <?xml version="1.0" encoding="utf-8"?> <SOAP:Envelope xmlns:soap=" xmlns:soap-enc=" xmlns:xsd=" xmlns:xsi=" <SOAP:Header> <wsse:security xmlns:wsse=" SOAP:mustUnderstand="false"> <wsse:usernametoken> <wsse:username>cisco</wsse:username> <wsse:password>cisco</wsse:password> </wsse:usernametoken> </wsse:security> </SOAP:Header> <SOAP:Body> <request xmlns="urn:cisco:wsma-exec" correlator="show int gig1"> <execcli maxwait="pt100s" xsd="false" format="builtin"> <cmd>show ip int br</cmd> </execcli> </request> </SOAP:Body> </SOAP:Envelope> > POST

26 WSMA Demo

27 Demos Topology Demo GitHub Repo

28 NETCONF

29 NETCONF roots June of 2002, the Internet Architecture Board (IAB) held invitational workshop on Network Management to Identify a list of technologies relevant for network management with their strengths and weaknesses Identify the most important operator needs 29

30 NETCONF definition NETCONF is a protocol defined by the IETF to install, manipulate, and delete the configuration of network devices V 1.0 RFC Base NETCONF Protocol RFC 4742 NETCONF over SSH Protocol Stack Content Operations Messages XML get, get-config, edit-config, etc. rpc, rpc-reply Transport SSH 2006 Designed to address the shortcomings documented in RFC 3535

31 NETCONF Operations Main Operations Description <get> (close to show? ) Retrieve running configuration and device state information <get-config> (close to show run ) Retrieve all or part of specified configuration datastore <edit-config> (close to conf t ) Loads all or part of a configuration to the specified configuration datastore Other Operations Description <copy-config> Replace an entire configuration datastore with another <delete-config> Delete a configuration datastore <commit> Copy candidate datastore to running datastore (ex: XR) <lock> / <unlock> Lock or unlock the entire configuration datastore system <close-session> Graceful termination of NETCONF session <kill-session> Forced termination of NETCONF session

32 NETCONF Datastores Target of Operations A Datastore holds a copy of the configuration data that is required to get a device from its initial default state into a desired operational state Running running-config Start-up startup-config Available on IOS-XR Candidate work place for creating and manipulating configuration data Running is the only mandatory Datastore

33 NETCONF Transaction and Error management Transaction Management Either all configuration is applied or nothing Avoids inconsistent state Both at Single Device and Network-wide level Error Management All operations return OK or error code

34 NETCONF Capabilities and Models Download Capability Exchange defined by the RFC ssh -p 830 -s netconf Models Download from a Device <get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"> </get-schema> This is great for integration

35 NETCONF Operation Example <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get> <filter> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"> <interface> <name>gigabitethernet1/0/1</name> </interface> </interfaces> </filter> </get> </rpc> Message - RPC Operation Content 35

36 Model Driven APIs

37 Open Programmable Interface Simplified View NETCONF RESTCONF grpc CLI Parser NETCONF RESTconf grpc Protocols Data Model Models Device Features Interface BGP QoS ACL

38 Data Models Protocol Data-Model Interface Model definition A Data-Model Explicitly and precisely defines Data Structure, Syntax and Semantics

39 YANG A Data Modeling Language

40 YANG definition YANG - A Data Modeling Language for NETCONF Data The Data is NOT defined by NETCONF RFC! Protocol Data-Model YANG used to describe how to structure the Data to send/receive Standard defined in RFC 6020 YANG IETF

41 YANG example Interface Model definition Interface Model Instances in XML interface: list, key = name name: string speed: string duplex: string YANG Models à Data Models defined using the YANG language

42 Data Models NETCONF RESTCONF grpc NETCONF RESTconf grpc Data Model Open Models (YANG) Data Model Native Models Open Models Native Models Models Device Features Configuration Operation Data Interface BGP QoS ACL

43 Automation: Data is king Config-data Operational-data What the device is told to do It is (currently) the way you express intent What the box is actually doing It is (currently) what you get out of SNMP and most show commands Examples: switch> show run interface Loopback0 switch(config)# interface Loopback0 Examples: switch> show interface Loopback0 snmpget results

44 Data Models: Open vs Native Open Models Industry definition Compliant with standard (IETF, ITU, OpenConfig, etc) Native Models Cisco definition Unique to a Cisco operating system Example: ietf-diffserv-policy.yang (IETF Diffserv data model) Example: Cisco-IOS-XR-ipv4-bgp-cfg.yang (IOS-XR BGP data model) Open Models are a subset of the Native Models

45 Native and Open Models Benefits: Use open models where available Use native models for functionality not yet in open models Open Models (i.e. OpenConfig) Map Platform Native Models Device Features Interface BGP QoS ACL

46 Who Defines YANG Models? Model IEEE IETF Vendors OpenConfig URL

47 YANG Open Models Operators-led YANG models: lead by Google!

48 Protocols NETCONF, RESTCONF, grpc

49 Protocols NETCONF RESTCONF grpc NETCONF RESTconf grpc Protocols NETCONF RESTconf grpc XML JSON (XML) GPB (XML/JSON) Encoding Data Model Device Features SSH HTTP HTTP/2 Transport Interface BGP QoS ACL

50 NETCONF V1.1 NETCONF is a protocol defined by the IETF to install, manipulate, and delete the configuration of network devices V 1.0 V 1.1 Extensions Protocol Stack RFC Base NETCONF Protocol RFC 4742 NETCONF over SSH RFC Base NETCONF Protocol RFC 6242 NETCONF over SSH RFC 5277 Notifications RFC 5717 Partial Locking RFC 6243 With defaults RFC 6020 YANG Content Operations Messages XML get, get-config, edit-config, etc. rpc, rpc-reply Transport SSH IETF

51 NETCONF Demo

52 RESTCONF definition REST-like protocol running over HTTP for accessing data defined in YANG using Datastores defined in NETCONF It defines how a YANG model is mapped to a RESTful interface Supports OPTIONS, GET, PUT, POST, DELETE operations Request and response in XML or JSON format HTTP transport Now an IETF Standard: RFC 8040 IETF

53 RESTCONF vs NETCONF Operations RESTCONF GET As compared to NETCONF <get-config>, <get> POST <edit-config> (operation= create ) PUT <edit-config> (operation= create/replace ) DELETE <edit-config> (operation= delete ) 53

54 RESTCONF Demo

55 grpc definition grpc is an open source RPC (Remote Procedure Call) system developed at Google Google ecosystem with automatic GPB integration cross-platform client and server bindings for many languages: C, C++, C#, Go, Java, Node.js, Objective-C, PHP, Python, Ruby Feature rich: authentication, bidirectional streaming and flow control, blocking/nonblocking bindings, cancellation and timeouts HTTP/2 transport Not a standard! grpc GPB (Google Protocol Buffers )

56 GPB (Google Protocol Buffers ) Method of serializing structured data Data structures (messages) defined in a definition file (.proto) Smaller, Faster than XML/JSON/YAML Origin: Google's internal data interchange The sender uses the.proto to serialize the data, the receiver uses the.proto to de-serialize the data.

57 Streaming Telemetry

58 Telemetry Collector Subscription Periodic or on-change Transport NETCONF RESTCONF grpc Encoding XML JSON GPB Data Model Open Models (YANG) Data Model Native Models Open Models Native Models Models Device Features Configuration Operation Data Interface BGP QoS ACL Operational Data only

59 Pub Sub vs OpenConfig Telemetry? Same concepts: Pub Sub is standardized at the IETF (by Cisco) Telemetry Some differences: OpenConfig-telemetry is a subset of IETF effort IETF PUB/SUB OC Telemetry 59

60 Tools

61 Tools 3 rd Party Cisco NSO Custom NETCONF RESTconf grpc Protocols Data Model Device Features Interface BGP QoS ACL

62 YangExplorer

63 YangExplorer Overview A GUI driven tool to test NETCONF and RESTCONF interfaces defined by YANG models Load YANG models from device Browse YANG models Execute NETCONF or RESTCONF Operations Generate self-contained Python scripts Open Source!! YangExplorer

64 YangExplorer Demo

65 Ytool/YangExplorer (3) Define Operations (1) Select a Profile Python Scripts (2) Browse Models Check Capabilities (4) Create RPC (5) Run RPC

66 RESTful APIs RESTful GET PUT POST DELETE

67 Programmability, Automation, Orchestration, APIs terminology Orchestration Cloud Integration Policy Orchestration Applications Open Developer Friendly Secure Northbound APIs RESTful GET PUT POST DELETE Automation Automation Abstraction & Policy Control from Core to Edge Analytics Network Data, Contextual Insights Programmability Open & Programmable Standards-Based Secure Flexible Infrastructure Physical & Virtual Infrastructure App Hosting Southbound APIs NETCONF RESTCONF grpc Software Driven Extensible Cloud Enabled Secure

68 APIC-EM App GUI vs APIs APIC-EM APP GUI APIC-EM APIs Turn-key Solution Build Your Own vs Controller

69 APIC-EM App GUI Path Trace

70 APIC-EM REST APIs Path Trace POST { "sourceip" : " ", "destip» : " ", "sourceport" : "1000", "destport» : "2000", "protocol» : "tcp", "inclusions» : ["QOS-STATS","INTERFACE-STATS","DEVICE-STATS","PERFORMANCE-STATS","ACL-TRACE"], "periodicrefresh» : true } API Response: { "response": { "flowanalysisid": "5755deb8-e a b1ea4a2", "taskid": "57d77c04-9aa8-49f6-aed9-a6f ", "url": "/api/v1/flow-analysis/5755deb8-e a b1ea4a2" }, "version": "1.0" } Step 1: 5-Tuple Input Using API and TaskID

71 APIC-EM REST APIs Path Trace GET API Response: { "response": { "request": { "sourceip": " ", "sourceport": "1000", "destip": " ", "destport": "2000", "protocol": "tcp", "periodicrefresh": true, "inclusions": [ "ACL-TRACE", "PERFORMANCE-STATS", "DEVICE-STATS", "INTERFACE-STATS", "QOS-STATS" ], "id": "5755deb8-e a b1ea4a2", "status": "COMPLETED", "createtime": , "lastupdatetime": }, "lastupdate": "Mon Jun 06 06:33:36 UTC 2016", "networkelementsinfo": [ { "id": "1aaa159e a eb4b6", "type": "wireless", "ip": " ", "linkinformationsource": "Switched" }, { "id": " c3-b267-4fade5f794a9", "name": "AP f.19ca", "type": "Unified AP", "ip": " ", "role": "ACCESS", "linkinformationsource": "Switched", "tunnels": [ "CAPWAP Tunnel" ] }, { "id": "24ac6aa d5-90a3-00c83e96583d", "name": "CAMPUS-Access1", "type": "Switches and Hubs", "ip": " ",... Step 2: Path Trace Output using an API (Continued) hop 1 hop 2 hop 3

72 APIC-EM REST APIs Documentation APIC-EM GUI DevNet

73 Key Takeaways

74 Device APIs Key Takeaways CLIs for Humans APIs for Machines Open/Standard WSMA NETCONF/RESTCONF, grpc RFC6241, OpenConfig For legacy platforms

75 Additional Resources

76 Python Tutorials Beginners: Code Academy (interactive) Coursera (online) TutorialsPoint (online) Python.org (online) The Hard Way (ebook) Dive into Python 3 (online) Intermediate: Google (ebook) Crash Course (online)

77 DevNet Sandboxes, Learning Labs 77

78 DevNet Sandboxes, Learning Labs cisco.com/labs with NETCONF and YANG tags 78

79 Learning NETCONF/YANG The tail-f education page is an excellent source View the 3 recordings under NETCONF and YANG Tutorial Series Here is a short reference Tail-f training video collection In-depth NETCONF/YANG Tutorial deck NETCONF Central: Model-Based Management Jive Page:

80 Tooling Exploring and using NETCONF/YANG Editor plug-ins emacs (yang-mode.el) vim (yang.vim) sublime text (sublime-yang-syntax) pyang an extensible YANG validator written in Python. (Video trainining: pyang) can be used standalone as a validator of YANG modules, or to generate YIN, YANG, DSDL and XSD from YANG and YIN. libsmi A library allowing the generation of YANG models from SMI/SMIv2 compliant MIBs 80

81 Tooling Exploring and using NETCONF/YANG ncclient a Python library that facilitates client-side scripting and application development around the NETCONF protocol (only supports NETCONF 1.0) Postman a Chrome plugin for RESTCONF, allowing for customized sets of REST snippets to be easily built, maintain and shared. Useful for NETCONF via RESTCONF, for example Open Daylight OpenDaylight enables auto-generation of RESTconf APIs from YANG models, with NETCONF client support APIdocs feature provides a way to explore both local and mounted YANG models 81

82 Tooling YDK Starting point: GitHub YDK Python API YDK-Py ( YDK-Py sample apps ( YDK Generator YDK-gen ( YANG Explorer ( DevNet YDK at DevNet ( - Live by Apr 25 Cisco IOS XR 6.0 at DevNet (

83 Ansible Ansible Network Automation: ansible.com/network-automation IOS Modules: docs.ansible.com/ansible/list_of_network_modules.html#ios Ansible and Cisco: ansible.com/ansible-cisco

84 Telemetry IOS-XR, NX-OS Tools on GitHub Demos and Labs (dcloud telemetry lab)

85 Q & A

86 Cisco Spark Ask Questions, Get Answers, Continue the Experience Use Cisco Spark to communicate with the Speaker and fellow participants after the session Download the Cisco Spark app from itunes or Google Play 1. Go to the Cisco Live Melbourne 2017 Mobile app 2. Find this session 3. Click the Spark button under Speakers in the session description 4. Enter the room, room name = BRKSDN Join the conversation! The Spark Room will be open for 2 weeks after Cisco Live 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 86

87 Complete Your Online Session Evaluation Give us your feedback and receive a Cisco Live 2017 Cap by completing the overall event evaluation and 5 session evaluations. All evaluations can be completed via the Cisco Live Mobile App. Caps can be collected Friday 10 March at Registration. Learn online with Cisco Live! Visit us online after the conference for full access to session videos and presentations. BRKSDN Cisco and/or its affiliates. All rights reserved. Cisco Public 87

88 Thank you

89