containerd
/
rust-extensions
mirror of https://github.com/containerd/rust-extensions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #208 from mxpv/docs 

Simplify doc management and update READMEs
This commit is contained in:
Maksym Pavlenko 2023-10-04 11:24:21 -07:00 committed by GitHub
parent fd734b4e7a 7b69bd68c2
commit a0e042a46e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 152 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/ci.yml vendored
View File

@ -30,7 +30,7 @@ jobs:
- run: cargo clippy --all-targets -- -D warnings
- run: cargo clippy --all-targets --all-features -- -D warnings
- run: cargo doc --no-deps
- run: cargo doc --no-deps --features docs
env:
RUSTDOCFLAGS: -Dwarnings

4
crates/client/Cargo.toml
View File

@ -34,9 +34,13 @@ tonic-build.workspace = true
[features]
connect = ["tokio", "tower"]
docs = []
# Technically Tonic doesn't require Tokio and Tower dependencies here.
# However we need them to implement `connect` helper and it's highly unlikely
# that Tonic will be used with any other async runtime (see https://github.com/hyperium/tonic/issues/152)
# So we enable `connect` feature by default (use `--no-default-features` otherwise).
default = ["connect"]
[package.metadata.docs.rs]
features = ["docs"]

8
crates/client/README.md
View File

@ -10,11 +10,15 @@ This crate implements a GRPC client to query containerd APIs.
## Example
```rust
use containerd_client::{connect, services::v1::version_client::VersionClient};
async fn query_version() {
// Launch containerd at /run/containerd/containerd.sock
let channel = connect("/run/containerd/containerd.sock").await?;
let channel = connect("/run/containerd/containerd.sock").await.unwrap();
let mut client = VersionClient::new(channel);
let resp = client.version(()).await?;
let resp = client.version(()).await.unwrap();
println!("Response: {:?}", resp.get_ref());
}
```

3
crates/client/src/lib.rs
View File

@ -14,12 +14,11 @@
limitations under the License.
*/
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
// No way to derive Eq with tonic :(
// See https://github.com/hyperium/tonic/issues/1056
#![allow(clippy::derive_partial_eq_without_eq)]
//! A GRPC client to query containerd's API.
pub use tonic;
/// Generated `containerd.types` types.

8
crates/logging/Cargo.toml
View File

@ -3,7 +3,7 @@ name = "containerd-shim-logging"
version = "0.1.1"
authors = [
"Maksym Pavlenko <pavlenko.maksym@gmail.com>",
"The containerd Authors"
"The containerd Authors",
]
description = "Logger extension for containerd v2 runtime"
keywords = ["containerd", "shim", "containers"]
@ -13,3 +13,9 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true
[features]
docs = []
[package.metadata.docs.rs]
features = ["docs"]

9
crates/logging/src/lib.rs
View File

@ -14,14 +14,7 @@
limitations under the License.
*/
//! Helper library to implement custom shim loggers for containerd.
//!
//! # Runtime
//! containerd shims may support pluggable logging via stdio URIs. Binary logging has the ability to
//! forward a container's STDIO to an external binary for consumption.
//!
//! This crates replicates APIs provided by Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md#logging).
//!
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
use std::{env, fmt, fs, os::unix::io::FromRawFd, process};

9
crates/runc/Cargo.toml
View File

@ -1,10 +1,7 @@
[package]
name = "runc"
version = "0.2.0"
authors = [
"Yuna Tomida <ytomida.mmm@gmail.com>",
"The containerd Authors",
]
authors = ["Yuna Tomida <ytomida.mmm@gmail.com>", "The containerd Authors"]
description = "A crate for consuming the runc binary in your Rust applications"
keywords = ["containerd", "containers", "runc"]
categories = ["api-bindings", "asynchronous"]
@ -16,6 +13,7 @@ homepage.workspace = true
[features]
async = ["tokio", "async-trait", "futures", "tokio-pipe"]
docs = []
[dependencies]
libc.workspace = true
@ -37,3 +35,6 @@ async-trait = { workspace = true, optional = true }
futures = { workspace = true, optional = true }
tokio = { workspace = true, features = ["full"], optional = true }
tokio-pipe = { version = "0.2.10", optional = true }
[package.metadata.docs.rs]
features = ["docs"]

6
crates/runc/README.md
View File

@ -14,12 +14,10 @@ You can build runc client with `RuncConfig` in method chaining style.
Call `build()` or `build_async()` to get client.
Note that async client depends on [tokio](https://github.com/tokio-rs/tokio), then please use it on tokio runtime.
```rust
use runc;
```rust,ignore
#[tokio::main]
async fn main() {
let config = runc::Config::new()
let config = runc::GlobalOpts::new()
.root("./new_root")
.debug(false)
.log("/path/to/logfile.json")

2
crates/runc/src/lib.rs
View File

@ -33,6 +33,8 @@
* limitations under the License.
*/
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
//! A crate for consuming the runc binary in your Rust applications, similar to
//! [go-runc](https://github.com/containerd/go-runc) for Go.
use std::{

8
crates/shim-protos/Cargo.toml
View File

@ -18,6 +18,7 @@ homepage.workspace = true
default = []
async = ["ttrpc/async", "async-trait"]
sandbox = []
docs = []
[[example]]
name = "shim-proto-server"
@ -61,5 +62,10 @@ ttrpc-codegen = "0.4"
[dev-dependencies]
ctrlc = { version = "3.0", features = ["termination"] }
log.workspace = true
simple_logger = { version = "4.0", default-features = false, features = ["stderr"]}
simple_logger = { version = "4.0", default-features = false, features = [
"stderr",
] }
tokio = { workspace = true, features = ["full"] }
[package.metadata.docs.rs]
features = ["docs"]

31
crates/shim-protos/README.md
View File

@ -5,13 +5,28 @@
[![Crates.io](https://img.shields.io/crates/l/containerd-shim-protos)](https://github.com/containerd/rust-extensions/blob/main/LICENSE)
[![CI](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml)
TTRPC bindings for containerd's shim events and interfaces.
`containerd-shim-protos` contains TTRPC bindings and client/server code to interact with containerd's runtime v2 shims.
## Runtime
This crate is mainly expected to be useful to interact with containerd's shim runtime.
Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
The shim API is minimal and scoped to the execution lifecycle of a container.
To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md).
## Design
The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message
and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the
[Containerd shim v2](https://github.com/containerd/containerd/blob/main/api/runtime/task/v2/shim.proto) protocol.
[Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol.
The message and service definitions are auto-generated from protobuf source files under `vendor/`
by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not
edit those auto-generated source files.
If upgrading/modification is needed, please follow the steps:
- Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'.
- Re-generate the source files by `cargo build --features=generate_bindings`.
- Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization.
## Usage
Add `containerd-shim-client` as a dependency in your `Cargo.toml`
@ -23,18 +38,20 @@ containerd-shim-protos = "0.4"
Basic client code looks as follows:
```rust
let client = client::Client::connect(socket_path)?;
```rust,no_run
use containerd_shim_protos as client;
let client = client::Client::connect("unix:///containerd-shim/shim.sock").expect("Failed to connect to shim");
let task_client = client::TaskClient::new(client);
let context = client::ttrpc::context::with_timeout(0);
let req = client::api::ConnectRequest {
id: pid,
id: String::from("1"),
..Default::default()
};
let resp = task_client.connect(context, &req)?;
let resp = task_client.connect(context, &req).expect("Connect request failed");
```
## Example

47
crates/shim-protos/src/lib.rs
View File

@ -14,52 +14,7 @@
limitations under the License.
*/
//! `containerd-shim-protos` contains TTRPC bindings and client/server code to interact with
//! containerd's runtime v2 shims.
//!
//! # Runtime
//! This crate is mainly expected to be useful to interact with containerd's shim runtime.
//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
//! The shim API is minimal and scoped to the execution lifecycle of a container.
//!
//! To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md).
//!
//! # Design
//! The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message
//! and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the
//! [Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol.
//!
//! The message and service definitions are auto-generated from protobuf source files under `vendor/`
//! by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not
//! edit those auto-generated source files.
//!
//! If upgrading/modification is needed, please follow the steps:
//! - Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'.
//! - Re-generate the source files by `cargo build --features=generate_bindings`.
//! - Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization.
//!
//! # Examples
//!
//! Here is a quick example how to use the crate:
//! ```no_run
//! use containerd_shim_protos as client;
//!
//! use client::api;
//! use client::ttrpc::context::Context;
//!
//! // Create TTRPC client
//! let client = client::Client::connect("unix:///socket.sock").unwrap();
//!
//! // Get task client
//! let task_client = client::TaskClient::new(client);
//! let context = Context::default();
//!
//! // Send request and receive response
//! let request = api::ConnectRequest::default();
//! let response = task_client.connect(Context::default(), &request);
//! ```
//!
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
#![allow(warnings)]
pub use protobuf;

8
crates/shim/Cargo.toml
View File

@ -22,6 +22,7 @@ async = [
"signal-hook-tokio",
"tokio",
]
docs = []
[[example]]
name = "skeleton_async"
@ -50,7 +51,9 @@ time.workspace = true
# Async dependencies
async-trait = { workspace = true, optional = true }
futures = { workspace = true, optional = true }
signal-hook-tokio = { version = "0.3.1", optional = true, features = ["futures-v0_3"]}
signal-hook-tokio = { version = "0.3.1", optional = true, features = [
"futures-v0_3",
] }
tokio = { workspace = true, features = ["full"], optional = true }
[target.'cfg(target_os = "linux")'.dependencies]
@ -74,3 +77,6 @@ windows-sys = {version = "0.48.0", features = [
[dev-dependencies]
tempfile = "3.6"
[package.metadata.docs.rs]
features = ["docs"]

82
crates/shim/README.md
View File

@ -10,48 +10,77 @@ Rust crate to ease runtime v2 shim implementation.
It replicates same [shim.Run](https://github.com/containerd/containerd/blob/dbef1d56d7ebc05bc4553d72c419ed5ce025b05d/runtime/v2/example/cmd/main.go)
API offered by containerd's shim v2 runtime implementation written in Go.
## Runtime
Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
The shim API is minimal and scoped to the execution lifecycle of a container.
This crate simplifies shim v2 runtime development for containerd. It handles common tasks such
as command line parsing, setting up shim's TTRPC server, logging, events, etc.
Clients are expected to implement [Shim] and [Task] traits with task handling routines.
This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go).
Once implemented, shim's bootstrap code is as easy as:
```text
shim::run::<Service>("io.containerd.empty.v1")
```
## Look and feel
The API is very similar to the one offered by Go version:
```rust
```rust,no_run
use std::sync::Arc;
use async_trait::async_trait;
use containerd_shim::{
asynchronous::{run, spawn, ExitSignal, Shim},
publisher::RemotePublisher,
Config, Error, Flags, StartOpts, TtrpcResult,
};
use containerd_shim_protos::{
api, api::DeleteResponse, shim_async::Task, ttrpc::r#async::TtrpcContext,
};
use log::info;
#[derive(Clone)]
struct Service {
exit: ExitSignal,
exit: Arc<ExitSignal>,
}
impl shim::Shim for Service {
type Error = shim::Error;
#[async_trait]
impl Shim for Service {
type T = Service;
fn new(
_runtime_id: &str,
_id: &str,
_namespace: &str,
_publisher: shim::RemotePublisher,
_config: &mut shim::Config,
) -> Self {
async fn new(_runtime_id: &str, _args: &Flags, _config: &mut Config) -> Self {
Service {
exit: ExitSignal::default(),
exit: Arc::new(ExitSignal::default()),
}
}
fn start_shim(&mut self, opts: shim::StartOpts) -> Result<String, shim::Error> {
let address = shim::spawn(opts, Vec::new())?;
async fn start_shim(&mut self, opts: StartOpts) -> Result<String, Error> {
let grouping = opts.id.clone();
let address = spawn(opts, &grouping, Vec::new()).await?;
Ok(address)
}
fn wait(&mut self) {
self.exit.wait();
async fn delete_shim(&mut self) -> Result<DeleteResponse, Error> {
Ok(DeleteResponse::new())
}
fn get_task_service(&self) -> Self::T {
async fn wait(&mut self) {
self.exit.wait().await;
}
async fn create_task_service(&self, _publisher: RemotePublisher) -> Self::T {
self.clone()
}
}
impl shim::Task for Service {
fn connect(
#[async_trait]
impl Task for Service {
async fn connect(
&self,
_ctx: &TtrpcContext,
_req: api::ConnectRequest,
@ -63,15 +92,20 @@ impl shim::Task for Service {
})
}
fn shutdown(&self, _ctx: &TtrpcContext, _req: api::ShutdownRequest) -> TtrpcResult<api::Empty> {
async fn shutdown(
&self,
_ctx: &TtrpcContext,
_req: api::ShutdownRequest,
) -> TtrpcResult<api::Empty> {
info!("Shutdown request");
self.exit.signal(); // Signal to shutdown shim server
self.exit.signal();
Ok(api::Empty::default())
}
}
fn main() {
shim::run::<Service>("io.containerd.empty.v1")
#[tokio::main]
async fn main() {
run::<Service>("io.containerd.empty.v1", None).await;
}
```
@ -97,7 +131,7 @@ $ sudo ctr run --rm --runtime ./target/debug/examples/skeleton docker.io/library
Or manually:
```
```bash
$ touch log
# Run containerd in background

18
crates/shim/src/lib.rs
View File

@ -14,23 +14,7 @@
limitations under the License.
*/
//! A library to implement custom runtime v2 shims for containerd.
//!
//! # Runtime
//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
//! The shim API is minimal and scoped to the execution lifecycle of a container.
//!
//! This crate simplifies shim v2 runtime development for containerd. It handles common tasks such
//! as command line parsing, setting up shim's TTRPC server, logging, events, etc.
//!
//! Clients are expected to implement [Shim] and [Task] traits with task handling routines.
//! This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go).
//!
//! Once implemented, shim's bootstrap code is as easy as:
//! ```text
//! shim::run::<Service>("io.containerd.empty.v1")
//! ```
//!
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
use std::{collections::hash_map::DefaultHasher, fs::File, hash::Hasher, path::PathBuf};
#[cfg(unix)]

6
crates/snapshots/Cargo.toml
View File

@ -14,6 +14,9 @@ license.workspace = true
repository.workspace = true
homepage.workspace = true
[features]
docs = []
[dependencies]
async-stream = "0.3.3"
futures.workspace = true
@ -34,3 +37,6 @@ simple_logger = { version = "4.0", default-features = false }
[build-dependencies]
tonic-build.workspace = true
[package.metadata.docs.rs]
features = ["docs"]

13
crates/snapshots/README.md
View File

@ -43,13 +43,19 @@ $ ctr i pull --snapshotter custom docker.io/library/hello-world:latest
Snapshotters are required to implement `Snapshotter` trait (which is very similar to containerd's
[Snapshotter](https://github.com/containerd/containerd/blob/main/snapshots/snapshotter.go) interface).
```rust
```rust,ignore
use std::collections::HashMap;
use containerd_snapshots as snapshots;
use containerd_snapshots::{api, Info, Usage};
use log::info;
#[derive(Default)]
struct Example;
#[snapshots::tonic::async_trait]
impl snapshots::Snapshotter for Example {
type Error = ();
type Error = snapshots::tonic::Status;
async fn stat(&self, key: String) -> Result<Info, Self::Error> {
info!("Stat: {}", key);
@ -73,8 +79,7 @@ impl snapshots::Snapshotter for Example {
The library provides `snapshots::server` for convenience to wrap the implementation into a GRPC server, so it can
be used with `tonic` like this:
```rust
```rust,ignore
use snapshots::tonic::transport::Server;
Server::builder()

36
crates/snapshots/src/lib.rs
View File

@ -14,41 +14,7 @@
limitations under the License.
*/
//! Remote snapshotter extension for containerd.
//!
//! Snapshots crate implements containerd's proxy plugin for snapshotting. It aims hide the underlying
//! complexity of GRPC interfaces, streaming and request/response conversions and provide one
//! [crate::Snapshotter] trait to implement.
//!
//! # Proxy plugins
//! A proxy plugin is configured using containerd's config file and will be loaded alongside the
//! internal plugins when containerd is started. These plugins are connected to containerd using a
//! local socket serving one of containerd's GRPC API services. Each plugin is configured with a
//! type and name just as internal plugins are.
//!
//! # How to use from containerd
//! Add the following to containerd's configuration file:
//! ```toml
//! [proxy_plugins]
//! [proxy_plugins.custom]
//! type = "snapshot"
//! address = "/tmp/snap2.sock"
//! ```
//! Start containerd daemon:
//! ```bash
//! containerd --config /path/config.toml
//! ```
//!
//! Run remote snapshotter instance:
//! ```bash
//! $ cargo run --example snapshotter /tmp/snap2.sock
//! ```
//! Now specify `custom` snapshotter when pulling an image with `ctr`:
//! ```bash
//! $ ctr i pull --snapshotter custom docker.io/library/hello-world:latest
//! ```
//!
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
// No way to derive Eq with tonic :(
// See https://github.com/hyperium/tonic/issues/1056
#![allow(clippy::derive_partial_eq_without_eq)]