rscni-plugin 0.5.0

CNI plugin library for Rust
Documentation

rscni-plugin

A Rust library for building CNI (Container Network Interface) plugins with trait-based architecture.

crates.io docs.rs License

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 on rscni 0.2.x, change the dependency to rscni-plugin and replace rscni:: with rscni_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, rscni 0.3.0 is a deprecated shim that re-exports rscni-plugin 0.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::ArgsBuilder builds Args directly, without the CNI_* environment or stdin

Installation

Add this to your Cargo.toml:

[dependencies]
rscni-plugin = "0.5"

For async support, you need to enable the async feature and add async-trait and an async runtime (such as tokio):

[dependencies]
rscni-plugin = { version = "0.5", features = ["async"] }
async-trait = "0.1"
tokio = { version = "1", features = ["full"] }

For testing, enable the test-util feature as a dev-dependency to get test_util::ArgsBuilder (see Testing your plugin):

[dev-dependencies]
rscni-plugin = { version = "0.5", features = ["test-util"] }

Quick Start

Basic Plugin (Sync)

Implement the Cni trait to create your CNI plugin:

use rscni_plugin::cni::{Cni, Plugin};
use rscni_plugin::error::Error;
use rscni_plugin::types::{Args, CNIResult};

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<(), Error> {
        // Implement network teardown logic
        Ok(())
    }

    fn check(&self, args: Args) -> Result<(), Error> {
        // Implement network validation logic
        Ok(())
    }

    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");
}

Async Plugin

Enable the async feature and implement the async Cni trait:

use async_trait::async_trait;
use rscni_plugin::async_cni::{Cni, Plugin};
use rscni_plugin::error::Error;
use rscni_plugin::types::{Args, CNIResult};

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<(), Error> {
        // Async network teardown
        Ok(())
    }

    async fn check(&self, args: Args) -> Result<(), Error> {
        // Async network validation
        Ok(())
    }

    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");
}

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:

#[cfg(test)]
mod tests {
    use rscni_plugin::{cni::Cni, error::Error, test_util::ArgsBuilder};

    use super::MyCniPlugin;

    #[test]
    fn add_accepts_a_minimal_config() -> Result<(), Error> {
        let args = ArgsBuilder::new()
            .container_id("test-container")?
            .netns("/run/netns/test")
            .ifname("eth0")?
            .config(r#"{"cniVersion":"1.1.0","name":"test-net","type":"my-plugin"}"#)?
            .build()?;

        MyCniPlugin.add(args)?;
        Ok(())
    }
}

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 stdin
  • types::CNIResult - ADD result: interfaces, IPs, routes, DNS
  • version::PluginInfo - Plugin version information
  • test_util::ArgsBuilder - builds Args for tests, behind the test-util feature

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/:

License

Apache-2.0. See LICENSE.