Podtender

Podman REST API 的异步 Rust 客户端库。

使用方法

示例

use tokio;
use podtender::podman_service::PodmanService;

#[tokio::main]
async fn main() {
  let podman_service = PodmanService::new("path/to/podman/socket");
  let podtender_result = podman_service.system().get_info().await.unwrap();
  println!("{podtender_result:?}");
}

集成测试（integration tests）也作为如何使用该库的示例。

Podman 设置

在可以使用该库之前，需要设置 Podman 服务。

# Set up podman service
podman system service unix:///home/`whoami`/podman.sock --log-level=debug --time=50
# Test if the socket is up and running
curl --unix-socket /home/`whoami`/podman.sock http://d/v4.0.0/libpod/info

支持的 Podman 版本

我们旨在仅支持最新版本的 Podman。目前这是 4.5.x。

库功能

通过 derive builder 实现构建器模式

builder 功能为请求类型启用构建器模式。这是通过 builder derive 宏 实现的。由宏创建的代码在 IDE 中的支持可能有限。

// with builder feature
let create_volume_parameter = CreateVolumeParameterBuilder::default()
    .driver("local".to_owned())
    .volume_name("some_volume_name".to_owned())
    .options(some_previously_created_hashmap)
    .build()
    .expect("Error building CreateVolumeParameter");
// without builder feature
let create_volume_parameter = CreateVolumeParameter {
    driver: Some("local".to_owned()),
    labels: None,
    volume_name: Some("some_volume_name".to_owned())
    options: Some(some_previously_created_hashmap),
}

测试中使用的示例参数

examples 功能通过 ExampleValues 特性启用初始化参数。这主要用于测试和展示每个 API 操作的可使用示例参数。

跟踪

tracing 启用由 Tokio 的 tracing crate 提供的日志/跟踪。

要求

Podtender 使用 hyper 和 tokio。需要活动的 Podman 套接字才能与 Podman 通信。

测试

要运行集成测试，需要tracing和examples功能。为了便于测试，测试被定义为Cargo.toml文件中的目标，可以使用以下命令运行：cargo test --test {target-name} --features="examples tracing"其中{target-name}是指定的目标之一（例如：containers-test）。

项目结构

Podman套接字和网络操作由PodmanService结构体内部管理。

Podman API将端点分为多个部分。本库基于该结构。pods模块包含实现的所有pods API端点的API调用函数、参数类型和响应类型。

每个端点类别模块包含以下内容：

• 用于配置请求的参数类型
• 用于发起请求的API调用函数
• 将响应反序列化的响应类型

要启动一个pod，您需要配置podtender::pods::parameter_types::PodStatsParameter，使用它通过podman_service.pods().start(parameter).await并期待podtender::pods::response_types::StartPodResponse。

注意

• 目前仅支持Unix套接字
• 由于tokio仅在Linux上构建对Unix套接字的支持，Podtender目前仅在Linux上构建
• 将Podman（API）视为可信的，并在测试中将它作为真实来源
• 要创建桥接网络模式的容器，以此作为起点

  CreateContainerParameter {
        netns: Some(Namespace {
            nsmode: Some("bridge".to_owned()),
            value: None,
        }),
        ..Default::default()
    };
  

• 以下错误表明Podman套接字不可用。如果测试中出现这种情况，重新运行将重新创建套接字，对于定义的TTL应该可以消除错误。

   HyperError(
       hyper::Error(
           Connect,
           Os {
               code: 2,
               kind: NotFound,
               message: "No such file or directory",
           },
       ),
   )
  

• connect_container_to_network_from_example测试需要机器上执行测试的192.168.123.0/24子网未被使用。
• Podman支持2021-05-26T10:42:00+02:00时间戳，但本库目前仅支持作为字符串的日期。
• Podman仅支持以下格式的查询数组：containers=container1&containers=container2
• 测试将在unix:///home/{user}/{socket_name}.sock创建Podman服务套接字，socket_name可以在tests/utils中进行更改。
• 测试从test_container中的Dockerfile构建镜像。