How to add support for my custom vpp plugin to vpp-agent?

[DreamerKMP]

Hi.
I'm trying to figure out how to add support for my custom vpp plugin to vpp-agent.

I have completed the following tasks so far.
The base version of my custom vpp is 20.01-release.

1. I created * .dep, my custom vpp's Ubuntu package.
2. I created a vpp-base based on that.
3. I created a dev-vpp-agent based on that.

I found that when I did the above, my custom vpp's binapi was compatible with vpp-agent v3 HEAD (vpp-ver 20.01).

I would like to know how you are adding support for plugins for each vpp version.

[ondrej-fabry]

Hello @DreamerKMP,

The proper way to implement support for custom VPP plugin(s) functionality depends on a way you use the VPP Agent project.

Ways to use VPP Agent

The VPP Agent can be used in various different ways:

1. using the official vpp-agent image published by Ligato (unchanged code)
2. using a forked vpp-agent repository with code modifications
3. using the vpp-agent as a library to develop your own agent(s)/app(s)/etc..

1. Using the official vpp-agent

This option is used and recommended only for testing or during development.

This option can be skipped for your use-case, because adding support for custom VPP plugin to VPP Agent is NOT possible without code modifications. However, it might be possible in the future.

2. Using a forked vpp-agent

Fork the vpp-agent repository and modify its code to build customized vpp-agent. This option is NOT a recommend way to use VPP Agent, because it might complicate project maintenance due possible conflicts when updating the fork.

⚠️ NOTE: You might have to use this option, depending on the custom VPP plugin's functionality. For example: if the custom VPP plugin adds a new VPP interface type, then parts of VPP Agent must be modified, specifically:

• the Protobuf definition of VPP Interface in proto/ligato/vpp/interfaces/interface.proto
  • requires change of the vpp_interfaces.Interface_Type enum
• the Go code in plugin plugins/vpp/ifplugin
  • requires handling of interface-type specific code to be added to existing interface descriptors

Here are PRs you can use this as reference for all the changes required to add support of some VPP functionality:

Adding support of new VPP interface types:

• GTP-U tunnel: feat: GTP-U tunnel support #1560
• VxLAN-GPE: API for VxLAN-GPE #1457

Adding support for existing VPP functionality:

• L3 cross-connect: feat: Add L3XC support #1602
• SPAN: API for SPAN #1430

3. Using the vpp-agent as a library

Develop your own Go app/agent/program/.. using dependency on go.ligato.io/vpp-agent/v3 Go module. This option is the recommended way to use VPP Agent.

If you currently do not use the VPP Agent as a library and if its possible in your case (see: 2. option why), I suggest to consider switching to this way of using VPP Agent, because it will allow you to only use parts (plugins) of VPP Agent that you really need without modifying existing code, while also making updates (Go module dependencies) very straight-forward.

[DreamerKMP]

As you say, the 3rd option may apply to me. So I'm going to use vpp-agent as a library.

In this case it sounds like I should make my custom-vpp-agent by referring to cmd/vpp-agent/vpp-agent.go. More specifically, I need all the features of vpp-agent so I will copy all the source files in the cmd/vpp-agent directory and add my code to them to create a custom-vpp-agent.

In fact, I'm not sure where and how to start it. I'm new to vpp-agent. So I wonder if you can give me a very simple example or a supplement to the 3rd option.

[HouJiangtao]

Hi, @DreamerKMP do you know the details for develop a new custom vpp-agent? can you give me some suggestion for this topic ? Thanks!

[DreamerKMP]

Hi, @DreamerKMP do you know the details for develop a new custom vpp-agent? can you give me some suggestion for this topic ? Thanks!

Hi! @HouJiangtao
I eventually gave up using vpp-agent and wrote my own control plane through golang and vpp-bin-api.
So I'm sorry I don't have any suggestions for you.

[HouJiangtao]

Got it!

[ondrej-fabry]

You could start with something like this: https://github.com/ligato/vpp-agent/blob/master/examples/tutorials/101_custom-vppagent/main.go

[ondrej-fabry]

To add support for your VPP plugin, you will need to:

• generate binapi (Go code) for your VPP plugin API
• define VPP handler API (vppcalls) that will be universal across VPP versions (no import of generated binapi)
• implement the VPP handler for the VPP version your work with
• define Protobuf file representing your functionality
• register model from proto and use it in KV descriptors
• implement KV descriptors for the objects/resources of your VPP plugin
• create a new plugin for your custom VPP functionality and add it to your main plugin
• initialize VPP handler and register KV descritpors during Init of your plugin

I think I mentioned most of the required steps, but might have missed something.

[ondrej-fabry]

Example for custom VPP plugin has been added recently: https://github.com/ligato/vpp-agent/blob/master/examples/customize/custom_vpp_plugin/README.md

[HouJiangtao]

Hi, @ondrej-fabry one question from my site, from you example i see the code block:
example := &Example{
VPP: app.DefaultVPP(),
Syslog: syslog.NewSyslogPlugin(),
Orchestrator: &orchestrator.DefaultPlugin,
}
here VPP: app.DefaultVPP(), dose it mean the agent have already contains the full offical vpp plugins? If i want to write custom vpp plugin how could i arrange the code?

[ondrej-fabry]

The example I posted demonstrates this. The Syslog is the custom VPP plugin.

[HouJiangtao]

Ok, thanks!