rscni-plugin
A Rust library for building CNI (Container Network Interface) plugins with trait-based architecture.
rscni-plugin provides a type-safe API for implementing CNI plugins in Rust, following the CNI specification v1.1.0.
This is the plugin side of CNI: the process a container runtime invokes. To invoke plugins instead, see rscni-runtime (planned).
[!IMPORTANT] Renamed from
rscni. If you depend onrscni0.2.x, change the dependency torscni-pluginand replacerscni::withrscni_plugin::. The module paths and feature names are the same, but several signatures changed in 0.4; the release notes list them. If you want the rename without the API changes,rscni0.3.0 is a deprecated shim that re-exportsrscni-plugin0.3.x.
Features
- 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.0, v0.3.1, v0.4.0, v1.0.0 and v1.1.0
- Well-tested: Comprehensive unit tests and integration tests
- Testable plugins:
test_util::ArgsBuilderbuildsArgsdirectly, without theCNI_*environment or stdin
Installation
Add this to your Cargo.toml:
[]
= "0.5"
For async support, you need to enable the async feature and add async-trait and an async runtime (such as tokio):
[]
= { = "0.5", = ["async"] }
= "0.1"
= { = "1", = ["full"] }
For testing, enable the test-util feature as a dev-dependency to get test_util::ArgsBuilder (see Testing your plugin):
[]
= { = "0.5", = ["test-util"] }
Quick Start
Basic Plugin (Sync)
Implement the Cni trait to create your CNI plugin:
use ;
use Error;
use ;
;
Async Plugin
Enable the async feature and implement the async Cni trait:
use async_trait;
use ;
use Error;
use ;
;
async
Testing your plugin
Args is normally built by Plugin::run from the CNI_* environment and stdin, which a unit test cannot easily control. With the test-util feature enabled, test_util::ArgsBuilder builds one directly, so you can call your Cni methods without setting environment variables:
Unset fields (container_id, netns, ifname, args, path) default the same way an absent environment variable does, so a test only needs to set what its command requires — see the CNI spec's parameter table for which fields each command needs.
CNI Data Types
types::Args- CNI command arguments (container ID, netns, ifname, etc.)types::NetConf- Network configuration from stdintypes::CNIResult- ADD result: interfaces, IPs, routes, DNSversion::PluginInfo- Plugin version informationtest_util::ArgsBuilder- buildsArgsfor tests, behind thetest-utilfeature
Everything except Args is re-exported from rscni-types, so rscni_plugin::types::NetConf and rscni_types::types::NetConf are the same type. Args is specific to being invoked as a plugin, which is why it lives here.
See the API documentation for complete type definitions.
Examples
Complete working examples live in examples/:
- rscni-debug - Synchronous CNI plugin for debugging
- async-rscni-debug - Asynchronous CNI plugin for debugging
License
Apache-2.0. See LICENSE.