{"id":21147494,"url":"https://github.com/openconfig/gnmi-gateway","last_synced_at":"2025-07-09T07:33:03.221Z","repository":{"id":39746103,"uuid":"257725519","full_name":"openconfig/gnmi-gateway","owner":"openconfig","description":"A modular, distributed, and highly available service for modern network telemetry via OpenConfig and gNMI","archived":false,"fork":false,"pushed_at":"2024-04-19T10:03:04.000Z","size":497,"stargazers_count":131,"open_issues_count":10,"forks_count":32,"subscribers_count":21,"default_branch":"release","last_synced_at":"2024-06-19T22:15:28.646Z","etag":null,"topics":["gnmi","openconfig","streaming-telemetry"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openconfig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-04-21T21:58:55.000Z","updated_at":"2024-06-02T16:30:49.000Z","dependencies_parsed_at":"2024-04-19T11:25:14.347Z","dependency_job_id":"c26040a6-83b7-4232-8fbe-6437b1f80434","html_url":"https://github.com/openconfig/gnmi-gateway","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openconfig%2Fgnmi-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openconfig%2Fgnmi-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openconfig%2Fgnmi-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openconfig%2Fgnmi-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openconfig","download_url":"https://codeload.github.com/openconfig/gnmi-gateway/tar.gz/refs/heads/release","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225495045,"owners_count":17483140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gnmi","openconfig","streaming-telemetry"],"created_at":"2024-11-20T09:03:19.029Z","updated_at":"2024-11-20T09:03:19.685Z","avatar_url":"https://github.com/openconfig.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Release](https://img.shields.io/github/release/openconfig/gnmi-gateway.svg)](https://github.com/openconfig/gnmi-gateway/releases/latest)\n[![Testing](https://github.com/openconfig/gnmi-gateway/workflows/Testing/badge.svg?branch=release)](https://github.com/openconfig/gnmi-gateway/actions?query=workflow%3ATesting+branch%3Arelease)\n[![Go Report Card](https://goreportcard.com/badge/github.com/openconfig/gnmi-gateway)](https://goreportcard.com/report/github.com/openconfig/gnmi-gateway)\n[![License](https://img.shields.io/github/license/openconfig/gnmi-gateway.svg)](https://github.com/openconfig/gnmi-gateway/blob/release/LICENSE)\n[![GoDoc](https://godoc.org/github.com/openconfig/gnmi-gateway/gateway?status.svg)](https://godoc.org/github.com/openconfig/gnmi-gateway/gateway)\n\n⚠ Experimental. Please take note that this is a pre-release version.\n\n# gNMI Gateway\n\n**gnmi-gateway** is a distributed and highly available service for connecting\nto multiple [gNMI][1] targets. Currently only the [gNMI Subscribe][2] RPC\nis supported.\n\nCommon use-cases are:\n- Provide multiple streams to gNMI clients while maintaining a single\n  connection to gNMI targets.\n- Provide highly available streams to gNMI clients.\n- Distribute gNMI target connections among multiple servers.\n- Export gNMI streams to other data formats and protocols.\n- Dynamically form connections to gNMI targets based on data in other systems\n  (e.g., your NMS, or network inventory, etc).\n  \n  \n## Design\n\n### Overview\n\ngnmi-gateway is written in Golang and is designed to be easily extendable\nfor users and organizations interested in utilizing gNMI data (modeled with\n[OpenConfig][5]). However, if you aren't interested in writing your own code\nthere are a few built-in components to make it easy to use from the\ncommand-line.\n\ngnmi-gateway connects to gNMI targets based on data received from\n**Target Loaders**. gNMI Notification messages are then forwarded to the\ngnmi-gateway cache, gNMI clients with relevant subscriptions, and\n**Exporters** which may forward data to other systems or protocols.\n\n### Target Loaders\n\nTarget Loaders are components that are used to generate target connection\nconfigurations that are sent to the connection manager. Target Loaders\nand the connection manager communicate using the [target.proto][6] model\nfound in the github.com/openconfig/gnmi repository. gnmi-gateway accepts a few\nadditional parameters in the Target.meta field:\n\n    NoTLSVerify: inlcude this field to disable TLS verification. This enables\n                 the use of self-signed certificates. Note that connections\n                 without TLS are not supported per the gNMI specification.\n    \n    NoLock: include this field to disable locking for the associated target even\n            if clustering is enabled. Only include this field if you are\n            handling de-duplication outside of gnmi-gateway.\n               \nThere are a few Target Loaders included with gnmi-gateway that you can use\nright away using the `-TargetLoaders` flag from the command-line. The Target\nLoaders included are:\n\n- [json](./gateway/loaders/json/json.go)\n- [netbox](./gateway/loaders/netbox/netbox.go)\n- [simple](./gateway/loaders/simple/simple.go)\n\nIf you'd like to build your own Target Loader see\n[loaders/loader.go](./gateway/loaders/loader.go) for details on how to\nimplement the TargetLoader interface.\n\n### Exporters\n\nExporters are components of gnmi-gateway that are used to convert gNMI data\ninto other formats and protocols for use by other systems. Some simple\nexamples would be sending gNMI notifications to a Kafka stream or\nstoring gNMI messages in a data store. Exporters will receive each gNMI message\nin the stream as it is received but also have access to [query][7] the local\ngNMI cache.\n\nExporters may be run on the same servers as your gnmi-gateway target\nconnections or you can run exporters on a server acting as clients to another\ngnmi-gateway cluster. This allows for some flexibility in your deployment\ndesign.\n\nSome Exporters have been included with gnmi-gateway and you can start using them\nby providing a comma-separated list of Exporters from the command-line with the\n`-Exporters` flag. The included Exporters are:\n\n- [debug](./gateway/exporters/debug/debug.go) (log to stdout)\n- [kafka](./gateway/exporters/kafka/kafka.go)\n- [prometheus](./gateway/exporters/prometheus/prometheus.go)\n\nTo build a custom Exporter see\n[exporters/exporter.go](./gateway/exporters/exporter.go) for details on how to\nimplement the Exporter interface.\n\n\n## Documentation\n\nMost of the documentation resides in this repo. Please feel welcome to file\na Github issue if you have question.\n\nSee the [godoc pages][8] for documentation and usage examples.\n\n\n## Pre-requisites\n- Golang 1.14 or newer\n- A target that supports gNMI Subscribe. This is usually a network router or switch.\n- A running instance of [Apache Zookeeper][3]. If you only want to run\n  a single instance of gnmi-gateway (i.e. without failover)\n  you don't need Zookeeper. See the development instructions below for how\n  to set up a Zookeeper Docker container.\n  \n  \n## Source Install / Run Instructions\n\nThese are the commands that would be used to start gnmi-gateway on a Linux\ninstall that has `make` installed. If you are not on a platform that is\ncompatible with the Makefile the commands inside the Makefile should translate\nto other platforms that support Golang.\n\n1.  `git clone github.com/openconfig/gnmi-gateway`\n2.  `cd gnmi-gateway`\n3.  `make tls` (If you have your own TLS server certificates\n    you may use them instead. It is recommended that you do not use these\n    generated self-signed certificates in production.)\n4.  Copy `targets-example.json` to `targets.json` and modify it to match your\n    gNMI target. You need to modify the target name, target address, and\n    credentials.\n5.  `make run`\n6.  gnmi-gateway should now be running. If you are unable to get gnmi-gateway\n    running at this point please check the `./gnmi-gateway -help` dialog\n    for tips (assuming the binary built) and then [file an issue on Github][4]\n    if you are still unsuccessful.\n\n  \n## Examples\n\n#### gNMI to Prometheus Exporter\n\ngnmi-gateway ships with an Exporter that allows you to export\nOpenConfig-modeled gNMI data to Prometheus.\n\nSee the [README](./examples/gnmi-prometheus/README.md) in\n`examples/gnmi-prometheus/` for details on how to start the gnmi-gateway Docker\ncontainer and connect it to a Prometheus Docker container.\n\n\n## Production Deployment\n\nIt is recommended that gnmi-gateway be deployed to immutable infrastructure\nsuch as Kubernetes or an AWS EC2 instance (or something else). New version tags\ncan be retrieved from Github and deployed with your configuration.\n\nMost configuration can be done via command-line flags. If you need more complex\noptions for configuring gnmi-gateway or want to configure the gateway at\nruntime you can create a .go file that imports the gateway package and create a\nconfiguration.GatewayConfig instance, passing that to gateway.NewGateway, and \nthen calling StartGateway. For an example of how this is done you can look at\nthe code in Main() in gateway/main.go.\n\nTo enable clustering of gnmi-gateway you will need an instance (or ideally a\ncluster) of Apache Zookeeper accessible to all of the gnmi-gateway instances.\nAdditionally all of the gnmi-gateway instances in the cluster must be able\nto reach each other over the network.\n\nIt is recommended that you limit the deployment of a cluster to a single\ngeographic region or a single geographic area with consistent latency for ideal\nperformance. You may run instances of gnmi-gateway distributed globally but\nmay encounter performance issues. You'll likely encounter timeout issues\nwith Zookeeper as your latency begins to approach the Zookeeper `tickTime`.\n\n\n## Development\nCheck the [to-do](./docs/TODO.md) list for any open known issues or\nnew features.\n\n#### Start Zookeeper for development\n\nThis should ony be used for development and not for production. The\ncontainer will maintain no state; you will have a completely empty\nZookeeper tree when this starts/restarts. To start zookeeper and expose the\nserver on `127.0.0.1:2181` run:\n\n```shell script\ndocker run -d -p 2181:2181 zookeeper\n```\n\n#### Test the code\n\nYou can test the code by running `make test`.\n\nYou can run integration tests by running `make integration`. (Ensure you have\nZookeeper running on `127.0.0.1:2181`.)\n\nYou can run test coverage by running `make cover`.\n\n#### Build the code\n\nYou can build the `gnmi-gateway` binary by running `make build`.\n\n#### Contributions\n\nPlease make any changes in a separate fork and make a PR to the `release`\nbranch when your changes are ready. Tags for new release versions will be cut\nfrom the `release` branch.\n\nYou must also sign a one-time CLA for any pull requests to be accepted. See\n[CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n\n## Troubleshooting\n\n#### \"`context deadline exceeded`\" Error\n\nIf you see a `context deadline exceeded` error from the connection manager it\nmeans there is some underlying issue that is causing the connection to a target\nto fail. This seems to often be a TLS issue (wrong certs, bad config, etc) but\nit could be something else. Try running gnmi-gateway with gRPC connection\nlogging enabled. For example:\n\n```bash\nGRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info ./gnmi-gateway\n```\n\n\n[1]: https://github.com/openconfig/gnmi\n[2]: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md#35-subscribing-to-telemetry-updates\n[3]: https://zookeeper.apache.org/\n[4]: https://github.com/openconfig/gnmi-gateway/issues\n[5]: https://github.com/openconfig/public/tree/master/release\n[6]: https://github.com/openconfig/gnmi/blob/master/proto/target/target.proto\n[7]: https://github.com/openconfig/gnmi/blob/master/cache/cache.go#L143\n[8]: https://godoc.org/github.com/openconfig/gnmi-gateway\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenconfig%2Fgnmi-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenconfig%2Fgnmi-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenconfig%2Fgnmi-gateway/lists"}