README
¶
ygnmi
Introduction
ygnmi is a A Go gNMI client library based on ygot-generated code. It includes a generator whose input is a set of YANG modules and output is ygot Go structs and a path library that can be used for making gNMI queries.
The library supports querying telemetry and unmarshaling it into generated structs and setting config. Only gnmi.Subscribe and gnmi.Set RPC are supported by this library.
This project is under active development and does not provide any compatibility or stability guarantees.
Note: This is not an official Google product.
Generation
The ygnmi generator can be installed by running: go install github.com/openconfig/ygnmi/app/ygnmi@latest.
For the most up-to-date documentation of the generator commands and flags: use the built-in help command. ygnmi can be configured using (in order of precedence): flags, environment variables, or a config file.
An example generation script is located at internal/exampleoc/gen.sh.
Not all ygot generator flags are supported by ygnmi. Notably ygnmi makes two important assumptions about the generated code:
- Path compression is enabled.
- PreferOperationState is selected.
Note: the supported flags may evolve over time to include these options.
Output
Calling the generation with --base_import_path=<somepath>/exampleoc flag will output:
- exampleoc
- This package contains the structs, enums, unions, and schema.
- These correspond to values that can be returned or set.
- exampleoc/<module>
- For every YANG module (that defines at least one container) one Go package is generated.
- Each package contains PathStructs: structs that represent a gNMI path that can queried or set.
- Each PathStruct has a State() method that returns Query for path. It may also have a Config() method.
- exampleoc/root
- This package contains a special "fakeroot" struct.
- It is called the fakeroot because there is no YANG container that corresponds to this struct.
- The package also contains a batch struct.
- This package contains a special "fakeroot" struct.
gNMI Client Library
The ygnmi client library uses the generated code to perform schema compliant subscriptions and set gNMI RPCs.
Queries
The ygnmi library uses generic queries to represent a gNMI path, the value type, and schema. Queries should never be constructed directly. Instead, they are returned by calling .Config() or .State() on the generated code. There are several query types that allow type safety when running an operation. The relationship of the query types is:
- Singleton: Lookup, Get, Watch, Await, Collect
- Config: Update, Replace, Delete, BatchUpdate, BatchReplace, BatchDelete
- Wildcard: LookupAll, GetAll, WatchAll, CollectAll
Additional Reference
- See ygot for more information on how YANG is mapped to Go code.
- See gNMI and gNMI Reference for more information on the gNMI protocol and spec.
Directories
¶
| Path | Synopsis |
|---|---|
|
app
|
|
|
ygnmi
command
Package main is the entrypoint for the ygnmi executable.
|
Package main is the entrypoint for the ygnmi executable. |
|
ygnmi/cmd
Package cmd contains root command for the ygnmi executable.
|
Package cmd contains root command for the ygnmi executable. |
|
ygnmi/cmd/generator
Package generator contains the command for generating Go code from YANG modules.
|
Package generator contains the command for generating Go code from YANG modules. |
|
Package exampleoc is a generated package which contains definitions of structs which represent a YANG schema.
|
Package exampleoc is a generated package which contains definitions of structs which represent a YANG schema. |
|
exampleocpath
Package exampleocpath is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
|
Package exampleocpath is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema. |
|
nested
Package nested is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
|
Package nested is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema. |
|
simple
Package simple is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
|
Package simple is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema. |
|
withlistval
Package withlistval is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
|
Package withlistval is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema. |
|
internal
|
|
|
testutil
Package testutil implements a fake GNMI server with the ability to stub responses and fake schema.
|
Package testutil implements a fake GNMI server with the ability to stub responses and fake schema. |
|
Package pathgen contains a library to generate gNMI paths from a YANG model.
|
Package pathgen contains a library to generate gNMI paths from a YANG model. |
|
Package ygnmi contains gNMI client library for use with a ygot Schema.
|
Package ygnmi contains gNMI client library for use with a ygot Schema. |