yumaworks-yp-gnmi

Package gNMI defines a service specification for the gRPC Network Management Interface. This interface is defined to be a standa...

  • Version: 2023-08-04

    yumaworks-yp-gnmi@2023-08-04


    
      module yumaworks-yp-gnmi {
    
        yang-version 1.1;
    
        namespace
          "http://yumaworks.com/ns/yumaworks-yp-gnmi";
    
        prefix ypgnmi;
    
        import ietf-yang-structure-ext {
          prefix sx;
        }
        import yumaworks-ycontrol {
          prefix yctl;
        }
        import yuma-types {
          prefix yt;
        }
    
        organization "YumaWorks, Inc.";
    
        contact
          "Support <support at yumaworks.com>";
    
        description
          "Package gNMI defines a service specification for the gRPC
           Network Management Interface. This interface is defined to
           be a standard interface via which a network management system
           ('client') can subscribe to state values, retrieve snapshots of
           state information, and manipulate the state of a data tree
           supported by a device ('target').
    
           This document references the gNMI Specification which can be
           found at:
           http://github.com/openconfig/reference/blob/master/rpc/gnmi
    
           Licensed under the Apache License, Version 2.0 (the 'License');
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at:
           http://www.apache.org/licenses/LICENSE-2.0
    
    
           YumaPro gNMI message definitions.
           Copyright (c) 2014 - 2023, YumaWorks, Inc. All rights reserved.
    
           Redistribution and use in source and binary forms, with or
           without modification, is permitted pursuant to, and subject
           to the license terms contained in, the BSD 3-Clause License
           http://opensource.org/licenses/BSD-3-Clause
           ";
    
        revision "2023-08-04" {
          description
            "22.10T-11: Change CLI container to sx:structure";
        }
    
        revision "2018-02-05" {
          description
            "Initial version for datastore access.";
        }
    
        sx:augment-structure "/yctl:ycontrol/yctl:message-payload/yctl:payload/yctl:payload";
    
        typedef supported-encoding {
          type enumeration {
            enum "json_val" {
              value 0;
              description
                "A JSON encoded string";
            }
            enum "bytes_val" {
              value 1;
              description
                "An arbitrary sequence of bytes";
            }
            enum "any_val" {
              value 2;
              description
                "A Protobuf encoded message using protobuf.any";
            }
            enum "ascii_val" {
              value 3;
              description
                "An ASCII encoded string representing text
                 formatted according to a target-defined convention";
            }
            enum "json_ietf_val" {
              value 4;
              description
                "A JSON encoded string using JSON encoding compatible
                 with [RFC 7951]";
            }
          }
        }
    
        grouping extension-field {
          description
            "The Extension message is defined within the gnmi_ext.proto
            specification. It is carried as a repeated field within each
            of the top-level request and response gNMI messages.
    
            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.";
          leaf-list extension {
            type union {
              type enumeration {
                enum "EID_UNSET" {
                  value 0;
                }
                enum "EID_EXPERIMENTAL" {
                  value 1;
                  description
                    "An experimental extension that may be used during
                     prototyping of a new extension.";
                }
              }
              type binary;
            }
          }
        }  // grouping extension-field
    
        grouping model-data {
          description
            "The ModelData message describes a specific model that is supported
            by the target and used by the client. The fields of the ModelData
            message identify a data model registered in a model catalog,
            as described in [draft-openconfig-netmod-model-catalog]
            (the schema of the catalog itself - expressed in YANG - is described
            in [openconfig-module-catalog.yang]).
            Each model specified by a ModelData message may refer to a specific
            schema module, a bundle of modules, or an augmentation or deviation,
            as described by the catalog entry.
    
            Each ModelData message contains the following fields:
            - name - name of the model expressed as a string.
            - organization - the organization publishing the model, expressed
              as a string.
            - version - the supported (or requested) version of the model,
              expressed as a string which represents the semantic version of
              the catalog entry.
    
            The combination of name, organization, and version uniquely identifies
            an entry in the model catalog.";
          list supported-modules {
            key "name";
            description
              "A set of ModelData messages describing each of the
               models supported by the target";
            leaf name {
              type string;
              description
                "Name of the model expressed as a string.";
            }
    
            leaf organization {
              type string;
              mandatory true;
              description
                "The organization publishing the model, expressed
                 as a string.";
            }
    
            leaf version {
              type string;
              mandatory true;
              description
                "The supported (or requested) version of the model,
                 expressed as a string which represents the semantic version
                 of the catalog entry.";
            }
          }  // list supported-modules
        }  // grouping model-data
    
        grouping update-list {
          description
            "A re-usable Update message is utilised to indicate changes to
            paths where a new value is required. The Update message contains
            two fields";
          list update {
            key "path";
            description
              "A list of update messages that indicate changes in the underlying
               data of the target. Both modification and creation of data is
               expressed through the update message.";
            leaf path {
              type string;
              description
                "Paths are represented according to gNMI Path Conventions,
                 which defines a structured format for path elements, and any
                 associated key values.";
            }
    
            leaf typed-value {
              type string;
              description
                "The value of a data node (or subtree) is encoded in a
                 TypedValue message as a oneof field to allow selection of
                 the data type by setting exactly one of the member fields.
    
                 TypedValue is used to encode a value being sent between the
                 client and target (originated by either entity).
    
                 message TypedValue {
                  One of the fields within the val oneof is populated with the
                  value of the update. The type of the value being included in
                  the Update determines which field should be populated. In
                  the case that the encoding is a particular form of the base
                  protobuf type, a specific field is used to store the
                  value (e.g., json_val).
    
                  oneof value {
                    string string_val = 1;            // String value.
                    int64 int_val = 2;                // Integer value.
                    uint64 uint_val = 3;              // Unsigned integer value.
                    bool bool_val = 4;                // Bool value.
                    // Arbitrary byte sequence value.
                    bytes bytes_val = 5;
                    float float_val = 6;              // Floating point value.
                    Decimal64 decimal_val = 7;        // Decimal64 encoded value.
                    // Mixed type scalar array value.
                    ScalarArray leaflist_val = 8;
                    // protobuf.Any encoded bytes.
                    google.protobuf.Any any_val = 9;
                    bytes json_val = 10;              // JSON-encoded text.
                    // JSON-encoded text per RFC7951.
                    bytes json_ietf_val = 11;
                    string ascii_val = 12;            // Arbitrary ASCII text.
                  }
                 }
                ";
            }
    
            leaf duplicates {
              type uint32;
              description
                "A counter value that indicates the number of coalesced
                 duplicates. If a client is unable to keep up with the server,
                 coalescion can occur on a per update (i.e., per path) basis
                 such that the server can discard previous values for a given
                 update and return only the latest. In this case the server
                 SHOULD increment a count associated with the update such that
                 a client can detect that transitions in the state of the path
                 have occurred, but were suppressed due to its inability to
                 keep up.";
            }
          }  // list update
        }  // grouping update-list
    
        grouping notifications {
          description
            "When a target wishes to communicate data relating to the state of
            its internal database to an interested client, it does so via means
            of a common Notification message. Notification messages are reused
            in other higher-layer messages for various purposes.
    
            The creator of a Notification message MUST include the timestamp
            field. All other fields are optional.";
          list notification {
            key "timestamp";
            leaf timestamp {
              type string;
              description
                "The time at which the data was collected by the device
                 from the underlying source, or the time that the target generated
                 the Notification message (in the case that the data does not
                 reflect an underlying data source).";
            }
    
            leaf prefix {
              type string;
              description
                "A prefix which is applied to all path fields included in the
                 Notification message. The paths expressed within the message are
                 formed by the concatenation of prefix + path.
                 The prefix always precedes the path elements.";
            }
    
            leaf alias {
              type string;
              description
                "A string providing an alias for the prefix specified within
                 the notification message.";
            }
    
            uses update-list;
    
            leaf-list delete {
              type string;
              description
                "A list of paths that indicate the deletion of data nodes
                 on the target.";
            }
          }  // list notification
        }  // grouping notifications
    
        grouping config-parms {
          leaf-list module {
            type yt:NcModuleSpec;
            description
              "Module libraries to use to generate gNMI datastore.
                Generated datastore package contains definitions of structs
                which represent a YANG schema.
    
                The datastore representation written in go, this
                datastore let us convert/validate/parse YANG to XML/JSON
                to ProtoBuff";
          }
        }  // grouping config-parms
    
        augment /yctl:ycontrol/yctl:message-payload/yctl:payload/yctl:payload {
          container yp-gnmi {
            choice message-type {
              mandatory true;
              leaf config-request {
                type empty;
                description
                  "Message type: subsys-request;
                    Purpose: register the service with the server
                    and request the service configuration from server.
                    Expected Response Message: config-response";
              }
              leaf register-request {
                type empty;
                description
                  "Message type: subsys-request;
                    Purpose: register the YP-gNMI subsystem
                    Expected Response Message: ok or error";
              }
              container config-response {
                description
                  "Message type: server-reply;
                  Purpose: server will send this element containing the
                  requested sub-system configuration.
                  Expected Response Message: none";
                uses config-parms;
              }  // container config-response
              container capability-request {
                description
                  "Message type: subsys-request;
                  Purpose: The CapabilityRequest message is sent to the server
                  to request capability information from the server.
                  The CapabilityRequest message carries a single repeated
                  extension field.
    
                  Expected Response Message: capability-response";
                uses extension-field;
              }  // container capability-request
              container capability-response {
                description
                  "Message type: server-response;
                  Purpose: message that includes its YP-gNMI service version,
                  the versioned data models it supports, and the supported
                  data encodings.
                  This information is used in subsequent RPC messages from
                  the client to indicate the set of models that the client will
                  use (for Get, Subscribe, etc), and the encoding to be used
                  for the data.
    
                  Expected Response Message: none";
                container supported-modules {
                  uses model-data;
                }  // container supported-modules
    
                leaf supported-encodings {
                  type supported-encoding;
                  default 'json_val';
                  description
                    "An enumeration field describing the data encodings supported
                    by the target";
                }
    
                leaf gNMI-version {
                  type string;
                  description
                    "The semantic version of the gNMI service supported by the
                    target, specified as a string.";
                }
    
                uses extension-field;
              }  // container capability-response
              container get-request {
                description
                  "Message type: subsys-request;
                  Purpose: Ask the main server to send the running
                  configuration contents
    
                  Expected Response Message: get-response";
                leaf prefix {
                  type string;
                  description
                    "Paths are represented according to gNMI Path Conventions,
                     which defines a structured format for path elements,
                     and any associated key values.
    
                     In a number of messages, a prefix can be specified to
                     reduce the lengths of path fields within the message.
                     In this case, a prefix field is specified within a
                     message - comprising of a valid path.
                     In the case that a prefix is specified, the absolute
                     path is comprised of the concatenation of the list of
                     path elements representing the prefix and the list of
                     path elements in the path field.";
                }
    
                leaf-list path {
                  type string;
                  description
                    "A set of paths for which the client is requesting a
                     data snapshot from the target.
                     The path specified MAY utilize wildcards.
                     In the case that the path specified is not valid,
                     the target MUST return an RPC response indicating
                     an error code of InvalidArgument and SHOULD provide
                     information about the invalid path in the error message
                     or details.";
                }
    
                leaf type {
                  type enumeration {
                    enum "config" {
                      value 0;
                    }
                    enum "state" {
                      value 1;
                    }
                    enum "oper" {
                      value 2;
                    }
                    enum "all" {
                      value 3;
                    }
                  }
                  default 'all';
                  description
                    "The type of data that is requested from the target.
                     The valid values for type are described below.
    
                     The types of data currently defined are:
                      - CONFIG - specified to be data that the target considers
                        to be read/write.
                        If the data schema is described in YANG, this corresponds
                        to the 'config true' set of leaves on the target.
                      - STATE - specified to be the read-only data on the target.
                        If the data schema is described in YANG, STATE data is
                        the 'config false' set of leaves on the target.
                      - OPERATIONAL - specified to be the read-only data on the
                        target that is related to software processes operating
                        on the device, or external interactions of the device.
    
                      If the type field is not specified, the target MUST return
                      CONFIG, STATE and OPERATIONAL data fields in the tree
                      resulting from the client's query.";
                }
    
                leaf encoding {
                  type supported-encoding;
                  default 'json_val';
                  description
                    "The encoding that the target should utilise to serialise
                     the subtree of the data tree requested.
    
                     If the Capabilities RPC has been utilised, the client SHOULD
                     use an encoding advertised as supported by the target.
    
                     If the encoding is not specified, JSON MUST be used.
                     If the target does not support the specified encoding,
                     the target MUST return an error of Unimplemented.
                     The error message MUST indicate that the specified encoding
                     is unsupported.";
                }
    
                container use-models {
                  description
                    "A set of ModelData messages indicating the schema definition
                     modules that define the data elements that should be returned
                     in response to the Get RPC call.";
                  uses model-data;
                }  // container use-models
    
                uses extension-field;
              }  // container get-request
              container get-response {
                description
                  "Message type: server-response;
                  Purpose: Provide the contents of the
                  configuration contents.
    
                  Expected Response Message: none";
                container notifications {
                  description
                    "A set of Notification messages. The target MUST generate a
                    Notification message for each path specified in the client's
                    GetRequest, and hence MUST NOT collapse data from multiple
                    paths into a single Notification within the response.
    
                    The timestamp field of the Notification message MUST be set
                    to the time at which the target's snapshot of the relevant
                    path was taken.";
                  uses notifications;
                }  // container notifications
    
                uses extension-field;
              }  // container get-response
              container set-request {
                description
                  "Message type: subsys-request;
                  Purpose: Ask the main server to send the running
                  configuration contents
    
                  In response to a SetRequest, the target MUST respond with a
                  SetResponse message. For each operation specified in the
                  SetRequest message, an UpdateResult message MUST be included
                  in the response field of the SetResponse. The order in which
                  the operations are applied MUST be maintained such that
                  UpdateResult messages can be correlated to the SetRequest
                  operations. In the case of a failure of an operation,
                  the status of the UpdateResult message MUST be populated with
                  error information. In addition, the status of the SetResponse
                  message MUST be populated with an error message indicating
                  the success or failure of the set of operations within the
                  SetRequest message.";
                leaf prefix {
                  type string;
                  description
                    "The prefix specified is applied to all paths defined
                     within other fields of the message.";
                }
    
                leaf-list delete {
                  type string;
                  description
                    "A set of paths which are to be removed from the data tree.
                     Where a path is contained within the delete field of the
                     SetRequest message, it should be removed from the target's
                     data tree. In the case that the path specified is to an
                     element that has children, these children MUST be recursively
                     deleted. If a wildcard path is utilised, the wildcards
                     MUST be expanded by the target, and the corresponding
                     elements of the data tree deleted. Such wildcards MUST
                     support paths specifying a subset of attributes required
                     to identify entries within a collection (list, array, or map)
                     of the data schema.
    
                     In the case that a path specifies an element within the data
                     tree that does not exist, these deletes MUST be silently
                     accepted.";
                }
    
                container replace {
                  description
                    "A set of Update messages indicating elements of the
                     data tree whose content is to be replaced.";
                  uses update-list;
                }  // container replace
    
                container update {
                  description
                    "A set of Update messages indicating elements of the data
                     tree whose content is to be updated.";
                  uses update-list;
                }  // container update
    
                uses extension-field;
              }  // container set-request
              container set-response {
                description
                  "A set of Update messages indicating elements of the
                   data tree whose content is to be replaced.
    
                   Expected Response Message: none";
                leaf prefix {
                  type string;
                  description
                    "The prefix specified is applied to all paths defined
                     within other fields of the message.";
                }
    
                leaf timestamp {
                  type string;
                  description
                    "A timestamp at which the set request message was accepted by
                     the system.";
                }
    
                list update-result {
                  key "path op";
                  description
                    "Containing a list of responses, one per operation specified
                     within the SetRequest message. Each response consists of
                     an UpdateResult message with the following fields";
                  leaf path {
                    type string;
                    description
                      "The path specified within the SetRequest. In the case
                       that a common prefix was not used within the SetRequest,
                       the target MAY specify a prefix to reduce repetition of
                       path elements within multiple UpdateResult messages in
                       the request field.";
                  }
    
                  leaf op {
                    type enumeration {
                      enum "invalid" {
                        value 0;
                      }
                      enum "delete" {
                        value 1;
                      }
                      enum "replace" {
                        value 2;
                      }
                      enum "update" {
                        value 3;
                      }
                    }
                    description
                      "The operation corresponding to the path. This value
                       MUST be one of DELETE, REPLACE, or UPDATE.";
                  }
    
                  container status {
                    leaf code {
                      type int32;
                      description
                        "code - a 32-bit integer value corresponding to the
                         canonical gRPC error code. The Netconfd Internal
                         error in this message.";
                    }
    
                    leaf message {
                      type string;
                      description
                        "message - a human-readable string describing the
                         error condition. This string is not expected to
                         be machine-parsable, but rather provide contextual
                         information which may be passed to upstream systems.
                         In our case error-string.";
                    }
    
                    leaf details {
                      type string;
                      description
                        "details - a repeated field of protobuf. Any messages
                         that carry error details. In our case just error-info";
                    }
                  }  // container status
                }  // list update-result
    
                uses extension-field;
              }  // container set-response
            }  // choice message-type
          }  // container yp-gnmi
        }
      }  // module yumaworks-yp-gnmi
    

© 2023 YumaWorks, Inc. All rights reserved.