Network Working Group R. Shakir Internet-Draft A. Shaikh Intended status: Informational P. Borman Expires: September 6, 2018 M. Hines C. Lebsack C. Morrow Google March 5, 2018 gRPC Network Management Interface (gNMI) draft-openconfig-rtgwg-gnmi-spec-01 Abstract This document describes the gRPC Network Management Interface (gNMI), a network management protocol based on the gRPC framework. gNMI supports retrieval and manipulation of state from network elements where the data is represented by a tree structure, and addressable by paths. The gNMI service defines operations for configuration management, operational state retrieval, and bulk data collection via streaming telemetry. The authoritative gNMI specification is maintained at [GNMI-SPEC]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 6, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents Shakir, et al. Expires September 6, 2018 [Page 1] Internet-Draft gNMI specification March 2018 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Protocol overview . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Data payloads and paths . . . . . . . . . . . . . . . . . 3 3.2. gNMI RPCs . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2.1. Capabilities . . . . . . . . . . . . . . . . . . . . 4 3.2.2. Subscribe . . . . . . . . . . . . . . . . . . . . . . 5 3.2.3. Set . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2.4. Get . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Additional operations . . . . . . . . . . . . . . . . . . . . 5 4.1. Error handling . . . . . . . . . . . . . . . . . . . . . 6 4.2. gNMI Extensions . . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 7.1. Normative references . . . . . . . . . . . . . . . . . . 6 7.2. Informative references . . . . . . . . . . . . . . . . . 6 Appendix A. Change summary . . . . . . . . . . . . . . . . . . . 7 A.1. Changes between revisions -00 and -01 . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction This document provides an overview of gNMI, a gRPC-based protocol for state management on network elements [GRPC].The gRPC Network Management Interface (gNMI) supports modification and retrieval of configuration, as well as control and transmission telemetry streams from a network element to a data collection system.This allows a single implementation on the network element, as well as a single NMS element to interact with the device via telemetry and configuration RPCs. All messages within the gRPC service definition are defined as protocol buffers (specifically proto3) [PROTO].gRPC service definitions are described using the relevant features of the protobuf IDL.The authoritative protobuf definition is maintained in [GNMI-PROTO].The current, authoritative version of the gNMI specification is available at [GNMI-SPEC]. Shakir, et al. Expires September 6, 2018 [Page 2] Internet-Draft gNMI specification March 2018 gNMI offers an alternative to management protocols such as NETCONF [RFC6241] and RESTCONF [RFC8040] with implementations on devices from multiple vendors.gNMI derives a number of benefits from being built on gRPC and HTTP/2, including modern security mechanisms, bidirectional streaming, binary framing, and a wide variety of language bindings to simplify integration with management applications.With protobuf encoding, it also provides significant efficiency advantages over XML serialization with a 3 to 10 times reduction in data volume (see the "Developer Guide" in [PROTO] for examples).A number of open source tools and reference implementations are available from the OpenConfig working group [GNMI-TOOLS]. 2. Terminology Throughout this document the following terminology is used: o Telemetry - refers to streaming data relating to underlying characteristics of the device - either operational state or configuration. o Configuration - elements within the data schema which are read/ write and can be manipulated by the client. o Target - the device within gNMI which acts as the owner of the data that is being manipulated or reported on. Typically this will be a network device. o Client - the device or system using gNMI to query/modify data on the target, or act as a collector for telemetry data. Typically this will be a network management application. 3. Protocol overview The sections below provide an overview of the gNMI protocol operations, leaving a detailed discussion to the full specification in [GNMI-SPEC]. 3.1. Data payloads and paths gNMI is often used to carry payloads that contain data instances of YANG schemas (for example based on OpenConfig models [OPENCONFIG]), but can be used for any data with the following characteristics: 1. structure that can be represented by a tree, where nodes can be uniquely identified by a path consisting of node names, or node names coupled with attributes; 2. values can be serialised into a scalar object. Shakir, et al. Expires September 6, 2018 [Page 3] Internet-Draft gNMI specification March 2018 Values may be serialised to native protobuf scalar types, structured data types (e.g. as JSON or protobuf object), or a schema language- specific type (e.g., YANG Decimal64). Data in gNMI is addressed by a path, which is represented as a structured list of elements, each with associated attributes if present. For example, the human-readable path "/interfaces/interface[name=eth0]/config/description" is represented as a text-encoded protobuf as: path: < elem: < name: "interfaces" > elem: < name: "interface" key: < key: "name" value: "eth0" > > elem: < name: "config" > elem: < name: "description" > > For more efficient handling of paths, gNMI supports a path prefix that is applied to every path in a message. Paths in gNMI are always absolute, constructed by concatenating the prefix with the path. 3.2. gNMI RPCs gNMI is designed with a small number of base remote procedure calls (RPCs) to simplify client and target implementations. This section provides a high-level overview of each RPC. Full details are available in [GNMI-SPEC]. 3.2.1. Capabilities The Capabilities RPC allows a client to interrogate a gNMI target to learn about supported features. The primary information returned by a target include the set of models it supports, the data encodings supported, and the version of the gNMI protocol it is using. The model information is expected to be based on a published model catalog [I-D.openconfig-netmod-model-catalog]. Shakir, et al. Expires September 6, 2018 [Page 4] Internet-Draft gNMI specification March 2018 3.2.2. Subscribe Subscribe is a bidirectional streaming RPC that allows clients and targets to send independent sequences of telemetry messages. Clients may subscribe to notifications for telemetry data by specifying a path to the desired data and a mode (in addition to other parameters). gNMI supports several modes, but the two common use cases are for periodically sampled data, such as counters, and event- driven data in which a notification is sent only when the corresponding data value changes. In response to a subscription, the target sends a stream of telemetry notifications that contain a timestamp, path, and updated value. Multiple updates may be included in a single RPC message. A streaming RPC for telemetry has the benefit of not requiring the target to collect, stage in memory, and serialize all of the requested data at once. The target is able to send data as soon as it is available, and can manage its resources to avoid becoming overloaded when sending a large volume of data. 3.2.3. Set Set is a unary RPC (i.e., single request and single response) that is sent by a client to update the state of the target. Set includes several operation types whereby data may be updated, deleted, or replaced. A Set RPC may include multiple operations -- the target is expected to treat each RPC as a transaction such that if all included operations cannot be completed successfully, the target's state is unchanged. Clients using the gNMI Set RPC pre-stage a set of update operations into a single Set RPC call, which must be either completely applied, or rolled back - eliminating the complex, long- lived candidate changes used in other protocols. 3.2.4. Get Get is also a unary RPC that allows clients to request an immediate snapshot of the current state from the target, specified by a path. The target is expected to collect the data when the request is received, and serialize it for immediate transmission to the client. Where supported, gNMI allows the client to specify the type of data that should be returned (e.g., configuration state, operational state, etc.). 4. Additional operations The sections below describe additional features and operations in gNMI. Shakir, et al. Expires September 6, 2018 [Page 5] Internet-Draft gNMI specification March 2018 4.1. Error handling Rather than defining application-level error messates, gNMI leverages native error handling mechanisms in gRPC in which canonical error codes and context information are part of the Status message in every RPC. The gNMI specification provides guidance on how gNMI error conditions should be mapped to canonical error codes. 4.2. gNMI Extensions While the base gNMI protocol is deliberately limited to a set of simple operations, some use cases require additional parameters that may be only applicable in those scenarios. gNMI extensions [GNMI-EXT] define a common way to add new payload to gNMI RPCs for these use cases without requiring changes in the core protocol specification. 5. Security Considerations gNMI allows access and manipulation of state on network devices, hence it requires careful consideration of security implications including authentication and authorization of RPCs. The gNMI specification [GNMI-SPEC] and companion document [GNMI-SECURITY] discuss the considerations in more detail. 6. IANA Considerations No IANA considerations at this time. In the future there may be a request for a protocol registry entry and well-known port allocation. 7. References 7.1. Normative references [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . 7.2. Informative references [GRPC] The gRPC authors, "gRPC", March 2018, . Shakir, et al. Expires September 6, 2018 [Page 6] Internet-Draft gNMI specification March 2018 [PROTO] Google, "Protocol buffers", March 2018, . [GNMI-PROTO] OpenConfig operator working group, "gnmi.proto", February 2018, . [GNMI-SPEC] OpenConfig operator working group, "gRPC Network Management Interface (gNMI) v0.6.0", January 2018, . [GNMI-TOOLS] OpenConfig operator working group, "gNMI Github repository", March 2018, . [GNMI-EXT] OpenConfig operator working group, "Extensions to gNMI", January 2018, . [GNMI-SECURITY] OpenConfig operator working group, "gNMI Authentication and Encryption", October 2016, . [OPENCONFIG] OpenConfig operator working group, "OpenConfig", March 2018, . [I-D.openconfig-netmod-model-catalog] Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and registry for YANG models", draft-openconfig-netmod-model- catalog-02 (work in progress), March 2017. Appendix A. Change summary A.1. Changes between revisions -00 and -01 o Replaced specification content with overview material and reference to normative reference to the gNMI specification document Shakir, et al. Expires September 6, 2018 [Page 7] Internet-Draft gNMI specification March 2018 o Updated to reflect changes in the gNMI specification and introduction of gNMI extensions. Authors' Addresses Rob Shakir Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 Email: robjs@google.com Anees Shaikh Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 US Email: aashaikh@google.com Paul Borman Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 US Email: borman@google.com Marcus Hines Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 US Email: hines@google.com Carl Lebsack Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 US Email: csl@google.com Shakir, et al. Expires September 6, 2018 [Page 8] Internet-Draft gNMI specification March 2018 Chris Morrow Google Email: christopher.morrow@gmail.com Shakir, et al. Expires September 6, 2018 [Page 9]