podman-rest-client

Provides an interface for querying the Podman REST API. Most of the interface is generated from the official Podman swagger file. It can connect to the Podman API over ssh to a unix socket and directly to a unix socket. Connections over ssh are commonly necessary on macOs where the container runtime runs in a virtual machine accessible over ssh.

API Compatibility

Use podman --version to determine what version of Podman you are using.

v5 Support

This crate primarily works with version 5 of the Podman API. There are sufficient differences between version 3, 4, and 5 that a lot of calls will not work in an older version.

v4 Support (Not in good shape)

While there is tentative v4 support it's in pretty terrible shape because the official Podman swagger file is missing all kinds of definitions. Some have been manually created, there is a lot more to do.

Podman Socket

Note that podman does not run in a client/server model like docker does so there usually isn't a socket you can connect to by default. You might need to enable the socket for the library to connect to. For example on linux you might need to run something like this:

systemctl --user enable --now podman.socket // Enable the podman unix domain socket

On macOS you might need to invoke something like:

podman machine init // Create your podman virtual machine
podman machine start // Start the machine

Usage

Linux

On linux you might initialize a client like this

#[cfg(feature = "v5")]
use podman_rest_client::PodmanRestClient;
use podman_rest_client::Config;

// Initialize a client
let client = PodmanRestClient::new(Config {
    uri: "unix:///run/user/501/podman/podman.sock".to_string(),
    identity_file: None,
}).await.unwrap();

// Fetch a list of container images
let images = client.v5().images().image_list_libpod(None).await.unwrap();

MacOs

On macOs you might initialize a client like this with an ssh url and identity file

#[cfg(feature = "v5")]
let client = PodmanRestClient::new(Config {
    uri: "ssh://core@127.0.0.1:63169/run/user/501/podman/podman.sock".to_string(),
    identity_file: Some("/path/to/identity_file".into()),
}).await.unwrap();

Config::guess

You can also use Config::guess() which tries to find the default path to the podman socket depending on the platform you are on.

#[cfg(feature = "v5")]
// Setup the default configuration
let config = Config::guess().await.unwrap();

// Initialize a client
let client = PodmanRestClient::new(config).await.unwrap();

// Fetch a list of container images
let images = client.v5().images().image_list_libpod(None).await.unwrap();

Client/API Traits

If you import the podman_rest_client::v5::Client trait you can directly call the api functions from a client:

#[cfg(feature = "v5")]
use podman_rest_client::v5::Client;
client.images().image_list_libpod(None).await;

You can also use various api traits like podman_rest_client::v5::apis::Images and directly call the individual request functions:

#[cfg(feature = "v5")]
use podman_rest_client::v5::apis::Images;
client.image_list_libpod(None).await;

Features

The default feature set is ["v5", "uds", "ssh"].

• ssh: Support for connecting to a podman through an ssh server.
• uds: Support for connecting to podman through a unix domain socket.
• v5: Support for version 5 of the podman API
• v4: Support for version 4 of the podman API. v4 is nowhere near ready for use.

v5 Swagger file modifications

The official swagger file generated by the podman project has a number of issues and needs to be manually massaged. You can see the changes by comparing swagger/swagger-v5.1.0.yaml against swagger/swagger-v5.1.0.modified.yaml

Renamed fields

• definitions/Mount/properties/Target renamed to Destination

Missing type info

• definitions/ListContainer/properties/ExposedPorts type set to object

Nullable fields

It turns out golang is a bit loosey goosey with nils. The following fields were set to nullable:

• definitions/InspectNetworkSettings/properties/Ports/additionalProperties
• definitions/InspectPodInfraConfig/properties/PortBindings/additionalProperties
• definitions/PodRmReport/properties/RemovedCtrs/additionalProperties

I'm not sure, but it might make more sense to make all hashmap values as nullable by default in this project.

Client side defaults

Some requests return extra streaming data with their responses by default. Our client doesn't support this, so we set up some client side overrides to set the quiet parameters on these requests to true

• responses//libpod/images/pull/post/parameters
• responses//libpod/images/scp/{name}/post/parameters

More adjustments likely to come as we run into issues and should be documented here

Changelog

v0.11.0

• Use new api client generator to generate client from swagger file. Big breaking changes
• New feature flag for ssh support
• New feature flag for early v4 support

Breaking Changes

• Query and Header parameters are now provided through structs from the params module
• Body parameters are no longer optional.
• Some i32/u32 fields became i16/u16
• API functions no longer have the _api suffix
• API functions not in scope unless the v5::Client trait is in scope or alternatively they can be invoked via client.v5()

v0.10.2

• Fix issue parsing error on pod deletion (#14)

v0.10.1

• Fix issue creating containers with mounted volumes (#12)

v0.10.0

• Parse error bodies whe encountering API errors (#11)

v0.9.1

• Fix for Config::guess on Linux (#7)

v0.9.0

• Config guessing logic on linux will return an error if a socket is not found
• Config guessing logic will also try to use the system socket if there is no user socket
• README.md documents some notes on initializing the podman socket

Breaking Changes

• guess_configuration is now Config::guess