A Rust library for building CNI (Container Network Interface) plugins with trait-based architecture.
RsCNI provides a type-safe API for implementing CNI plugins in Rust, following the CNI specification v1.3.0.
Breaking Changes in v0.1.0
The API has been completely redesigned from v0.0.4 with a new trait-based architecture.
- Idiomatic Rust: Trait-based design with type safety and zero-cost abstractions
- Async Support: Optional async/await support for high-performance plugins
- CNI Spec Compliant: Supports CNI specification v0.3.1, v0.4.0, v1.0.0, v1.1.0 and v1.3.0
- Well-tested: Comprehensive unit tests and integration tests
Add this to your Cargo.toml:
[dependencies]
rscni = "0.2"For async support, you need to enable the async feature and add async-trait and an async runtime (such as tokio):
[dependencies]
rscni = { version = "0.2", features = ["async"] }
async-trait = "0.1"
tokio = { version = "1", features = ["full"] }Implement the Cni trait to create your CNI plugin:
use rscni::cni::{Cni, Plugin};
use rscni::{Args, CNIResult, Error};
struct MyCniPlugin;
impl Cni for MyCniPlugin {
fn add(&self, args: Args) -> Result<CNIResult, Error> {
// Implement network setup logic
Ok(CNIResult::default())
}
fn del(&self, args: Args) -> Result<CNIResult, Error> {
// Implement network teardown logic
Ok(CNIResult::default())
}
fn check(&self, args: Args) -> Result<CNIResult, Error> {
// Implement network validation logic
Ok(CNIResult::default())
}
fn status(&self, args: Args) -> Result<(), Error> {
// Implement status check
Ok(())
}
fn gc(&self, args: Args) -> Result<(), Error> {
// Implement gc logic
Ok(())
}
}
fn main() {
let my_cni = MyCniPlugin;
let plugin = Plugin::default().msg("My CNI Plugin v0.1.0");
plugin.run(&my_cni).expect("Failed to execute CNI command");
}Enable the async feature and implement the async Cni trait:
use async_trait::async_trait;
use rscni::async_cni::{Cni, Plugin};
use rscni::{Args, CNIResult, Error};
struct MyAsyncCniPlugin;
#[async_trait]
impl Cni for MyAsyncCniPlugin {
async fn add(&self, args: Args) -> Result<CNIResult, Error> {
// Async network setup
Ok(CNIResult::default())
}
async fn del(&self, args: Args) -> Result<CNIResult, Error> {
// Async network teardown
Ok(CNIResult::default())
}
async fn check(&self, args: Args) -> Result<CNIResult, Error> {
// Async network validation
Ok(CNIResult::default())
}
async fn status(&self, args: Args) -> Result<(), Error> {
// Implement status check
Ok(())
}
async fn gc(&self, args: Args) -> Result<(), Error> {
// Implement gc logic
Ok(())
}
}
#[tokio::main]
async fn main() {
let my_cni = MyAsyncCniPlugin;
let plugin = Plugin::default().msg("My Async CNI Plugin v0.1.0");
plugin.run(&my_cni).await.expect("Failed to execute CNI command");
}Complete working examples are available in the examples/ directory:
- rscni-debug - Synchronous CNI plugin for debugging
- async-rscni-debug - Asynchronous CNI plugin for debugging
Run examples:
# Build the debug plugin
cargo build --package rscni-debug
# Test with CNI environment
CNI_COMMAND=VERSION ./target/debug/rscni-debugRsCNI provides strongly-typed structures for CNI configurations:
Args- CNI command arguments (container ID, netns, ifname, etc.)NetConf- Network configuration from stdinCNIResult- Plugin execution result with IPs, routes, DNSPluginInfo- Plugin version information
See the API documentation for complete type definitions.
RsCNI includes comprehensive test coverage:
# Run unit tests only
cargo test --lib
# Run with async feature
cargo test --features async
# Run integration tests
cargo test --test plugin_integration_testRsCNI is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.