gnmi-extensions.md

# Extensions to gNMI

**Contributors**: Rob Shakir (robjs@google.com), Carl Lebsack (csl@google.com),
Nick Ethier (nethier@jive.com), Anees Shaikh (aashaikh@google.com)

**Updated**: January 25th, 2018

**Version**: 0.1.0

## Extending gNMI

gNMI defines a standard set of RPCs which form the core protocol functionality.
In some implementations additional data is required within RPC payloads that is
not currently within the core protobuf definition. Extensions to gNMI define a
means to add new payload to gNMI RPCs for these use cases without requiring
changes in the core protocol specification.

An extension that is defined to a gNMI RPC MUST NOT modify the base behaviour of
the RPC. That is to say fields MUST NOT be interpreted in a manner which does
not match the base specification. The success or failure of an RPC MAY be
impacted by the extension. If the base specification's behaviour is to be
modified, an implementation MUST define a new service which specifies the
modified RPCs. A target MAY support both gNMI and such extension services as
different service endpoints on a common gRPC server.

gNMI extensions are defined to be carried within the `extension` field of each
top-level message of the gNMI RPCs. Extensions can added to both RPC request and
response messages, such that a client and target can both communicate extended
information. gNMI extensions are implemented directly within the request and
response messages to allow logging, debugging, or tracing frameworks to capture
their contents, and avoid the fragility of carrying extension information in
metadata.

## The Extension Message

The `Extension` message is defined within the `gnmi_ext.proto` specification. As
mentioned above, it is carried as a `repeated` field within each of the
top-level request and response gNMI messages.

## Well-Known and Registered Extensions

Well-known extensions are defined directly within the `gnmi_ext.proto` protocol
buffer. A well known extension is defined as one that is expected to be
supported by multiple implementations - for example, to support proxying, or
master arbitration between different writers.

Registered extensions are those that are more esoteric, or applicable to a
smaller set of use cases. In this case, the definition of the extension is
defined outside of the `gnmi.proto` or `gnmi_ext.proto` files. A registered
extension is given a unique identifier - which must be centrally registered in
the `gnmi_ext.proto` file. Registered extensions SHOULD provide a link to a
specification as to their operation. The gNMI `Extension` message is made
transparent to the definition of the protobuf message which defines the
extension by utilising a `bytes` field, which contains the binary marshalled
protobuf used to carry extension options.

Registered extensions MAY be promoted to well known extensions in the case that
their adoption becomes widespread.

## Extension Message Definition

The `Extension` message consists of a single `oneof` which may contain:

 * A well-known extension. Each well known extension defined in the
   `gnmi_ext.proto` file will be added to the `oneof` and assigned a unique
   field tag.
 * A registered extension, expressed as a `RegisteredExtension` message. The
   subfields of this message are:
   * An enumerated `id` field used to store the unique ID assigned to the
     registered extension.
   * A `bytes` field which stores the binary-marshalled protobuf for the
     extension.