go.ligato.io/vpp-agent/v3@v3.5.0/README.md (about) 1 <h1 align="center">VPP Agent</h1> 2 3 The VPP Agent is a Go implementation of a control/management plane for [VPP][vpp] based 4 cloud-native [Virtual Network Functions][vnf] (VNFs). The VPP Agent is built on top of 5 [CN Infra][cn-infra], a framework for developing cloud-native VNFs (CNFs). 6 7 The VPP Agent can be used as-is as a management/control agent for VNFs based on off-the-shelf 8 VPP (e.g. a VPP-based vswitch), or as a framework for developing management agents for VPP-based 9 CNFs. An example of a custom VPP-based CNF is the [Contiv-VPP][contiv-vpp] vswitch. 10 11 > Please note that the content of this repository is currently **WORK IN PROGRESS**! 12 13 ## Status 14 15 [](https://github.com/ligato/vpp-agent/actions?query=workflow%3A%22CI%22) 16 [](https://github.com/ligato/vpp-agent/actions?query=workflow%3A%22Docker%22) 17 [](https://coveralls.io/github/ligato/vpp-agent?branch=master) 18 <!--[](https://goreportcard.com/report/github.com/ligato/vpp-agent)--> 19 20 ### Releases 21 22 |Release|Release Date|Info| 23 |---|:---:|---| 24 |[](https://github.com/ligato/vpp-agent/releases/latest)||latest release| 25 26 Have a look at the [release notes](CHANGELOG.md) for a complete list of changes. 27 28 ### Branches 29 30 |Branch|Info|Last Commit| 31 |---|---|:---:| 32 |[](https://github.com/ligato/vpp-agent/tree/master)| **has switched to [v3](https://github.com/ligato/vpp-agent/blob/master/CHANGELOG.md#v300)** :warning:|| 33 |[](https://github.com/ligato/vpp-agent/tree/dev)| has been **DEPRECATED** || 34 |[](https://github.com/ligato/vpp-agent/tree/v2)| provides **legacy v2** || 35 36 All development is done against **master** branch. 37 38 ### Images 39 40 |Image|Image Size/Layers||Info| 41 |---|:---:|:---:|---| 42 |[](https://cloud.docker.com/u/ligato/repository/docker/ligato/vpp-agent)| ||with minimal footprint| 43 |[](https://cloud.docker.com/u/ligato/repository/docker/ligato/dev-vpp-agent)| ||prepared for developers| 44 45 ## Quickstart 46 47 For a quick start with the VPP Agent, you can use the pre-built Docker images on DockerHub 48 that contain the VPP Agent and VPP: [ligato/vpp-agent][vpp-agent] (or for ARM64: [ligato/vpp-agent-arm64][vpp-agent-arm64]). 49 50 0. Start ETCD on your host (e.g. in Docker as described [here][etcd-local]). 51 52 Note: for ARM64 see the information for [etcd][etcd-arm64]. 53 54 1. Run VPP + VPP Agent in a Docker container: 55 ``` 56 docker run -it --rm --name agent1 --privileged ligato/vpp-agent 57 ``` 58 59 2. Manage VPP agent using agentctl: 60 ``` 61 docker exec -it agent1 agentctl --help 62 docker exec -it agent1 agentctl status 63 ``` 64 65 3. Check the configuration (via agentctl or in VPP console): 66 ``` 67 docker exec -it agent1 agentctl dump all 68 docker exec -it agent1 vppctl show interface 69 ``` 70 71 **Next Steps** 72 73 See [README][docker-image] of development docker image for more details. 74 75 ## Documentation 76 [](https://pkg.go.dev/go.ligato.io/vpp-agent/v3) 77 78 Extensive documentation for the VPP Agent can be found at [docs.ligato.io](https://docs.ligato.io). 79 80 ## Architecture 81 82 The VPP Agent is basically a set of VPP-specific plugins that use the 83 CN-Infra framework to interact with other services/microservices in the 84 cloud (e.g. a KV data store, messaging, log warehouse, etc.). The VPP Agent 85 exposes VPP functionality to client apps via a higher-level model-driven 86 API. Clients that consume this API may be either external (connecting to 87 the VPP Agent via REST, gRPC API, Etcd or message bus transport), or local 88 Apps and/or Extension plugins running on the same CN-Infra framework in the 89 same Linux process. 90 91 The VNF Agent architecture is shown in the following figure: 92 93  94 95 Each (northbound) VPP API - L2, L3, ACL, ... - is implemented by a specific 96 VNF Agent plugin, which translates northbound API calls/operations into 97 (southbound) low level VPP Binary API calls. Northbound APIs are defined 98 using [protobufs][protobufs], which allow for the same functionality to be accessible 99 over multiple transport protocols (HTTP, gRPC, Etcd, ...). Plugins use the 100 [GoVPP library][govpp] to interact with the VPP. 101 102 The following figure shows the VPP Agent in context of a cloud-native VNF, 103 where the VNF's data plane is implemented using VPP/DPDK and 104 its management/control planes are implemented using the VNF agent: 105 106  107 108 ## Contributing 109 110  111 112 If you are interested in contributing, please see the [contribution guidelines][contribution]. 113 114 ## License 115 116 [](https://github.com/ligato/vpp-agent/blob/master/LICENSE) 117 118 ## Modified 3rd party tools included 119 120 - [protoc-gen-jsonschema][tool-included-jsonchema] ([code location in this repository][local-place-for-jsonchema]) 121 122 [agentctl]: cmd/agentctl 123 [cn-infra]: https://github.com/ligato/cn-infra 124 [contiv-vpp]: https://github.com/contiv/vpp 125 [contribution]: CONTRIBUTING.md 126 [docker]: docker 127 [docker-image]: https://docs.ligato.io/en/latest/user-guide/get-vpp-agent/#local-image-build 128 [etcd-arm64]: https://docs.ligato.io/en/latest/user-guide/arm64/#arm64-and-etcd-server 129 [etcd-local]: https://docs.ligato.io/en/latest/user-guide/get-vpp-agent/#connect-vpp-agent-to-the-key-value-data-store 130 [govpp]: https://wiki.fd.io/view/GoVPP 131 [ligato-docs]: http://docs.ligato.io/ 132 [protobufs]: https://developers.google.com/protocol-buffers/ 133 [vnf]: https://docs.ligato.io/en/latest/intro/glossary/#cnf 134 [vpp]: https://fd.io/vppproject/vpptech/ 135 [vpp-agent]: https://hub.docker.com/r/ligato/vpp-agent 136 [vpp-agent-arm64]: https://hub.docker.com/r/ligato/vpp-agent-arm64 137 [tool-included-jsonchema]: https://github.com/chrusty/protoc-gen-jsonschema/tree/de75f1b59c4e0f5d5edf7be2a18d1c8e4d81b17a 138 [local-place-for-jsonchema]: plugins/restapi/jsonschema