idnits 2.17.1 draft-openconfig-rtgwg-gnmi-spec-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([GNMI-SPEC]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 5, 2018) is 2234 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Shakir 3 Internet-Draft A. Shaikh 4 Intended status: Informational P. Borman 5 Expires: September 6, 2018 M. Hines 6 C. Lebsack 7 C. Morrow 8 Google 9 March 5, 2018 11 gRPC Network Management Interface (gNMI) 12 draft-openconfig-rtgwg-gnmi-spec-01 14 Abstract 16 This document describes the gRPC Network Management Interface (gNMI), 17 a network management protocol based on the gRPC framework. gNMI 18 supports retrieval and manipulation of state from network elements 19 where the data is represented by a tree structure, and addressable by 20 paths. The gNMI service defines operations for configuration 21 management, operational state retrieval, and bulk data collection via 22 streaming telemetry. The authoritative gNMI specification is 23 maintained at [GNMI-SPEC]. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 6, 2018. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Protocol overview . . . . . . . . . . . . . . . . . . . . . . 3 62 3.1. Data payloads and paths . . . . . . . . . . . . . . . . . 3 63 3.2. gNMI RPCs . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3.2.1. Capabilities . . . . . . . . . . . . . . . . . . . . 4 65 3.2.2. Subscribe . . . . . . . . . . . . . . . . . . . . . . 5 66 3.2.3. Set . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3.2.4. Get . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 4. Additional operations . . . . . . . . . . . . . . . . . . . . 5 69 4.1. Error handling . . . . . . . . . . . . . . . . . . . . . 6 70 4.2. gNMI Extensions . . . . . . . . . . . . . . . . . . . . . 6 71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 7.1. Normative references . . . . . . . . . . . . . . . . . . 6 75 7.2. Informative references . . . . . . . . . . . . . . . . . 6 76 Appendix A. Change summary . . . . . . . . . . . . . . . . . . . 7 77 A.1. Changes between revisions -00 and -01 . . . . . . . . . . 7 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 80 1. Introduction 82 This document provides an overview of gNMI, a gRPC-based protocol for 83 state management on network elements [GRPC].The gRPC Network 84 Management Interface (gNMI) supports modification and retrieval of 85 configuration, as well as control and transmission telemetry streams 86 from a network element to a data collection system.This allows a 87 single implementation on the network element, as well as a single NMS 88 element to interact with the device via telemetry and configuration 89 RPCs. 91 All messages within the gRPC service definition are defined as 92 protocol buffers (specifically proto3) [PROTO].gRPC service 93 definitions are described using the relevant features of the protobuf 94 IDL.The authoritative protobuf definition is maintained in 95 [GNMI-PROTO].The current, authoritative version of the gNMI 96 specification is available at [GNMI-SPEC]. 98 gNMI offers an alternative to management protocols such as NETCONF 99 [RFC6241] and RESTCONF [RFC8040] with implementations on devices from 100 multiple vendors.gNMI derives a number of benefits from being built 101 on gRPC and HTTP/2, including modern security mechanisms, 102 bidirectional streaming, binary framing, and a wide variety of 103 language bindings to simplify integration with management 104 applications.With protobuf encoding, it also provides significant 105 efficiency advantages over XML serialization with a 3 to 10 times 106 reduction in data volume (see the "Developer Guide" in [PROTO] for 107 examples).A number of open source tools and reference implementations 108 are available from the OpenConfig working group [GNMI-TOOLS]. 110 2. Terminology 112 Throughout this document the following terminology is used: 114 o Telemetry - refers to streaming data relating to underlying 115 characteristics of the device - either operational state or 116 configuration. 118 o Configuration - elements within the data schema which are read/ 119 write and can be manipulated by the client. 121 o Target - the device within gNMI which acts as the owner of the 122 data that is being manipulated or reported on. Typically this 123 will be a network device. 125 o Client - the device or system using gNMI to query/modify data on 126 the target, or act as a collector for telemetry data. Typically 127 this will be a network management application. 129 3. Protocol overview 131 The sections below provide an overview of the gNMI protocol 132 operations, leaving a detailed discussion to the full specification 133 in [GNMI-SPEC]. 135 3.1. Data payloads and paths 137 gNMI is often used to carry payloads that contain data instances of 138 YANG schemas (for example based on OpenConfig models [OPENCONFIG]), 139 but can be used for any data with the following characteristics: 141 1. structure that can be represented by a tree, where nodes can be 142 uniquely identified by a path consisting of node names, or node 143 names coupled with attributes; 145 2. values can be serialised into a scalar object. 147 Values may be serialised to native protobuf scalar types, structured 148 data types (e.g. as JSON or protobuf object), or a schema language- 149 specific type (e.g., YANG Decimal64). 151 Data in gNMI is addressed by a path, which is represented as a 152 structured list of elements, each with associated attributes if 153 present. For example, the human-readable path 154 "/interfaces/interface[name=eth0]/config/description" is represented 155 as a text-encoded protobuf as: 157 path: < 158 elem: < 159 name: "interfaces" 160 > 161 elem: < 162 name: "interface" 163 key: < 164 key: "name" 165 value: "eth0" 166 > 167 > 168 elem: < 169 name: "config" 170 > 171 elem: < 172 name: "description" 173 > 174 > 176 For more efficient handling of paths, gNMI supports a path prefix 177 that is applied to every path in a message. Paths in gNMI are always 178 absolute, constructed by concatenating the prefix with the path. 180 3.2. gNMI RPCs 182 gNMI is designed with a small number of base remote procedure calls 183 (RPCs) to simplify client and target implementations. This section 184 provides a high-level overview of each RPC. Full details are 185 available in [GNMI-SPEC]. 187 3.2.1. Capabilities 189 The Capabilities RPC allows a client to interrogate a gNMI target to 190 learn about supported features. The primary information returned by 191 a target include the set of models it supports, the data encodings 192 supported, and the version of the gNMI protocol it is using. The 193 model information is expected to be based on a published model 194 catalog [I-D.openconfig-netmod-model-catalog]. 196 3.2.2. Subscribe 198 Subscribe is a bidirectional streaming RPC that allows clients and 199 targets to send independent sequences of telemetry messages. Clients 200 may subscribe to notifications for telemetry data by specifying a 201 path to the desired data and a mode (in addition to other 202 parameters). gNMI supports several modes, but the two common use 203 cases are for periodically sampled data, such as counters, and event- 204 driven data in which a notification is sent only when the 205 corresponding data value changes. In response to a subscription, the 206 target sends a stream of telemetry notifications that contain a 207 timestamp, path, and updated value. Multiple updates may be included 208 in a single RPC message. 210 A streaming RPC for telemetry has the benefit of not requiring the 211 target to collect, stage in memory, and serialize all of the 212 requested data at once. The target is able to send data as soon as 213 it is available, and can manage its resources to avoid becoming 214 overloaded when sending a large volume of data. 216 3.2.3. Set 218 Set is a unary RPC (i.e., single request and single response) that is 219 sent by a client to update the state of the target. Set includes 220 several operation types whereby data may be updated, deleted, or 221 replaced. A Set RPC may include multiple operations -- the target is 222 expected to treat each RPC as a transaction such that if all included 223 operations cannot be completed successfully, the target's state is 224 unchanged. Clients using the gNMI Set RPC pre-stage a set of update 225 operations into a single Set RPC call, which must be either 226 completely applied, or rolled back - eliminating the complex, long- 227 lived candidate changes used in other protocols. 229 3.2.4. Get 231 Get is also a unary RPC that allows clients to request an immediate 232 snapshot of the current state from the target, specified by a path. 233 The target is expected to collect the data when the request is 234 received, and serialize it for immediate transmission to the client. 235 Where supported, gNMI allows the client to specify the type of data 236 that should be returned (e.g., configuration state, operational 237 state, etc.). 239 4. Additional operations 241 The sections below describe additional features and operations in 242 gNMI. 244 4.1. Error handling 246 Rather than defining application-level error messates, gNMI leverages 247 native error handling mechanisms in gRPC in which canonical error 248 codes and context information are part of the Status message in every 249 RPC. The gNMI specification provides guidance on how gNMI error 250 conditions should be mapped to canonical error codes. 252 4.2. gNMI Extensions 254 While the base gNMI protocol is deliberately limited to a set of 255 simple operations, some use cases require additional parameters that 256 may be only applicable in those scenarios. gNMI extensions 257 [GNMI-EXT] define a common way to add new payload to gNMI RPCs for 258 these use cases without requiring changes in the core protocol 259 specification. 261 5. Security Considerations 263 gNMI allows access and manipulation of state on network devices, 264 hence it requires careful consideration of security implications 265 including authentication and authorization of RPCs. The gNMI 266 specification [GNMI-SPEC] and companion document [GNMI-SECURITY] 267 discuss the considerations in more detail. 269 6. IANA Considerations 271 No IANA considerations at this time. In the future there may be a 272 request for a protocol registry entry and well-known port allocation. 274 7. References 276 7.1. Normative references 278 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 279 and A. Bierman, Ed., "Network Configuration Protocol 280 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 281 . 283 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 284 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 285 . 287 7.2. Informative references 289 [GRPC] The gRPC authors, "gRPC", March 2018, . 291 [PROTO] Google, "Protocol buffers", March 2018, 292 . 294 [GNMI-PROTO] 295 OpenConfig operator working group, "gnmi.proto", February 296 2018, 297 . 300 [GNMI-SPEC] 301 OpenConfig operator working group, "gRPC Network 302 Management Interface (gNMI) v0.6.0", January 2018, 303 . 306 [GNMI-TOOLS] 307 OpenConfig operator working group, "gNMI Github 308 repository", March 2018, . 311 [GNMI-EXT] 312 OpenConfig operator working group, "Extensions to gNMI", 313 January 2018, 314 . 317 [GNMI-SECURITY] 318 OpenConfig operator working group, "gNMI Authentication 319 and Encryption", October 2016, 320 . 323 [OPENCONFIG] 324 OpenConfig operator working group, "OpenConfig", March 325 2018, . 327 [I-D.openconfig-netmod-model-catalog] 328 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 329 registry for YANG models", draft-openconfig-netmod-model- 330 catalog-02 (work in progress), March 2017. 332 Appendix A. Change summary 334 A.1. Changes between revisions -00 and -01 336 o Replaced specification content with overview material and 337 reference to normative reference to the gNMI specification 338 document 340 o Updated to reflect changes in the gNMI specification and 341 introduction of gNMI extensions. 343 Authors' Addresses 345 Rob Shakir 346 Google, Inc. 347 1600 Amphitheatre Parkway 348 Mountain View, CA 94043 350 Email: robjs@google.com 352 Anees Shaikh 353 Google 354 1600 Amphitheatre Pkwy 355 Mountain View, CA 94043 356 US 358 Email: aashaikh@google.com 360 Paul Borman 361 Google 362 1600 Amphitheatre Pkwy 363 Mountain View, CA 94043 364 US 366 Email: borman@google.com 368 Marcus Hines 369 Google 370 1600 Amphitheatre Pkwy 371 Mountain View, CA 94043 372 US 374 Email: hines@google.com 376 Carl Lebsack 377 Google 378 1600 Amphitheatre Pkwy 379 Mountain View, CA 94043 380 US 382 Email: csl@google.com 383 Chris Morrow 384 Google 386 Email: christopher.morrow@gmail.com