podtender logo

Podtender

An async rust client library for the Podman REST API.

Crates.io Documentation

Usage

Example

```ignore use tokio; use podtender::podman_service::PodmanService;

[tokio::main]

async fn main() { let podmanservice = PodmanService::new("path/to/podman/socket"); let podtenderresult = podmanservice.system().getinfo().await.unwrap(); println!("{podtender_result:?}"); } ``` The integration tests also act as examples for how to use the crate.

Podman setup

The Podman service needs to be set up before the crate can be used. ```shell

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 ```

Supported Podman version

We aim to support the latest Podman version only. Currently, this is 4.5.x.

Crate features

Builder pattern via derive builder

The builder feature enables the builder pattern for request types. This is implemented with the builder derive macro. IDE support for code created by macros may be limited. ignore // 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), }

Example parameters used in tests

The examples feature enables initialized parameters via the ExampleValues trait. This is mostly intended for tests and to showcase a usable example parameter per API operation.

Tracing

tracing enables logs/tracing powered by Tokio's tracing crate.

Requirements

Podtender uses hyper and requires tokio. An active Podman socket is needed to communicate with Podman.

Tests

To run the integration tests, the tracing and examples features are required. To allow easy testing, the tests are defined as target in the Cargo.toml file and can be run with cargo test --test {target-name} --features="examples tracing" where {target-name} is one of the specified targets (e.g. containers-test).

Project structure

The Podman socket and network operations are internally managed by the PodmanService struct.

The Podman API categorizes endpoints into multiple sections. This crate is based on that structure. The pods module contains all api call functions, parameter types and response types for the implemented pods API endpoints.

Every endpoint category module contains: * the parameter types, used to configure the request * the api call functions used to make the request * the response types into which the response gets deserialized

To start a pod, you would configure podtender::pods::parameter_types::PodStatsParameter use it with podman_service.pods().start(parameter).await and expect podtender::pods::response_types::StartPodResponse.

Notes

Acknowledgments

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in podtender by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Current State

Currently supported API endpoints:

Planned features