Enhance documentation beyond just CNI examples

[nickheyer]

Without reading the name of the repo, one might think this project is a go wrapper for CNI plugins, meant to be used as a plugin to some other Firecracker SDK. There is an unreasonable amount of investigation required to get something working. There are also no examples of standard implementations beyond configuring static network interfaces or CNI network interfaces.

Regarding CNI/Network: It's unjustly implied that developers come stock with CNI plugins properly built / installed on their host systems, or even know where to find them. When they do eventually locate the CNI plugin repo, they will quickly discover that the standard make commands produce un-versioned plugins that are not actually accepted by firecracker/sdk (for those looking, check out the .github workflow in the actual CNI repo and use the commands there though you will only get a few of the plugin files).

So even with the disproportional focus on the networking setup in the sdk readme, it's clearly still very premature and undocumented. Obviously the firecracker official repo is well documented (though lacking structure as it's just a flat folder of markdown files), so at minimum the sdk docs could contain their Go wrappers for the functionality described in the official firecracker docs.

Finally, code comments do not constitute sufficient documentation for large open source projects, outside of an org.

[swagatbora90]

Hi @nickheyer, thanks for raising the issue. You make a fair point regarding the lack of comprehensive documentation. It's important to note that the firecracker-go-sdk project was primarily developed to be used in conjunction with the firecracker-containerd project. As a result, the focus was more on ensuring the SDK worked seamlessly within the firecracker-containerd project, and less emphasis was placed on improving the user-facing documentation for the SDK itself.

We do welcome contributions from the community to improve the documentation. If you have specific areas you would like to contribute to or have suggestions for improving the documentation, please feel free to submit pull requests to the repository.

To address some of your concerns, you can look into the firecracker-containerd project for reference implementation of the SDK. Also, the go bindings used in the SDK are generated from as swagger.yaml file, which can be found at https://github.com/firecracker-microvm/firecracker-go-sdk/blob/main/client/swagger.yaml.

Reference Implementation:

1. The firecracker-containerd project, available at https://github.com/firecracker-microvm/firecracker-containerd, serves as a reference implementation for integrating the Firecracker Go SDK. You can find examples of how to use the SDK in the runtime/service.go file, specifically around line 521.
2. The snapshotting example demo is also a good place to look at how the sdk can be used to create/interact with the firecracker VM.