fussybeaver/bollard

Bollard: an asynchronous rust client library for the Docker/Podman API

Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API containing futures, streams and the async/await paradigm.

This library supports both Docker and Podman as first-class container runtimes, with automatic socket discovery for rootless Podman. It features Windows support through Named Pipes and HTTPS support through optional Rustls bindings. Serialization types for interfacing with Docker and Buildkit are generated through OpenAPI, protobuf and upstream documentation.

Install

Add the following to your Cargo.toml file

[dependencies]
bollard = "*"

API

Documentation

API docs.

Feature flags

Quick Start

Use Case	Cargo.toml
Local Docker (Unix/Windows)	bollard = "*" (defaults work)
Remote Docker over HTTPS	bollard = { version = "*", features = ["ssl"] }
SSH tunnel to remote Docker	bollard = { version = "*", features = ["ssh"] }
BuildKit image builds	bollard = { version = "*", features = ["buildkit", "chrono"] }
WebSocket container attach	bollard = { version = "*", features = ["websocket"] }
Minimal binary size	bollard = { version = "*", default-features = false, features = ["pipe"] }

Default Features

Enabled by default:

• http - TCP connections to remote Docker/Podman (DOCKER_HOST=tcp://...)
• pipe - Unix sockets and Windows named pipes

Transport Features

Feature	Description
http	HTTP/TCP connector for remote Docker/Podman
pipe	Unix socket / Windows named pipe for local Docker/Podman
ssh	SSH tunnel connector

TLS/SSL Features

Choose one crypto provider:

Feature	Description
ssl	Rustls with ring provider (recommended)
aws-lc-rs	Rustls with aws-lc-rs provider (FIPS-compliant)
ssl_providerless	Rustls without crypto provider (bring your own CryptoProvider)
webpki	Use Mozilla's roots for BuildKit registry authentication TLS; Docker daemon TLS trusts only the supplied CA bundle

DateTime Features

For timestamp support in events and logs, choose one:

Feature	Description
chrono	Chrono date/time types
time	Time 0.3 date/time types

Note: chrono and time are mutually exclusive.

BuildKit Features

Feature	Description
buildkit	Full BuildKit support (includes ssl)
buildkit_providerless	BuildKit without bundled crypto provider

Note: BuildKit requires either chrono or time feature to be enabled for timestamp handling.

The transport-free bollard-llb crate constructs synchronous LLB graphs. Direct definition solves support local filesystem export through Docker-container and BuildkitDaemon. The Moby driver provides Moby::build_image to store configured images directly in Docker Engine, initially validated for a single linux/amd64 platform.

WebSocket Features

Feature	Description
websocket	WebSocket support for attach_container_websocket using tokio-tungstenite

Development Features

Feature	Description
json_data_content	Include raw JSON payload in deserialization errors

Version

The Docker API used by Bollard is using the latest 1.52 documentation schema published by the moby project to generate its serialization interface.

This library also supports version negotiation, to allow downgrading to an older API version.

Usage

Connecting with the container runtime

Connect to Docker or Podman according to your architecture and security remit.

Local (recommended)

Auto-detect the best available socket on the local machine.

use bollard::Docker;
Docker::connect_with_local_defaults();

Use the [Docker::connect_with_local] method API to parameterise this interface.

Podman

Explicitly connect to Podman with automatic rootless/system socket discovery (Unix only). Probes $DOCKER_HOST, then rootless Podman sockets, then the system Podman socket, and finally falls back to the Docker socket.

use bollard::Docker;
Docker::connect_with_podman_defaults();

Socket

The client will connect to the standard unix socket location /var/run/docker.sock or Windows named pipe location //./pipe/docker_engine.

use bollard::Docker;
#[cfg(unix)]
Docker::connect_with_socket_defaults();

Use the [Docker::connect_with_socket] method API to parameterise this interface.

HTTP

The client will connect to the location pointed to by DOCKER_HOST environment variable, or localhost:2375 if missing.

use bollard::Docker;
Docker::connect_with_http_defaults();

Use the [Docker::connect_with_http] method API to parameterise the interface.

SSL via Rustls

The client will connect to the location pointed to by DOCKER_HOST environment variable, or localhost:2375 if missing.

The client reads certificates from the directory set by DOCKER_CERT_PATH. The file key.pem contains the private key. The file cert.pem contains the client certificate. The file ca.pem contains the trusted daemon CA certificates. Only the certificates in ca.pem are trusted, even with the webpki feature. The client does not add OS or Mozilla roots. Add other trusted CA certificates to this PEM bundle. The client rejects empty or malformed CA bundles. Certificate-chain and hostname verification remain enabled.

To use OS roots or a custom trust store, use [Docker::connect_with_custom_transport]. Configure TLS in that transport and keep certificate-chain and hostname verification enabled.

use bollard::Docker;
#[cfg(feature = "ssl")]
Docker::connect_with_ssl_defaults();

Use the Docker::connect_with_ssl method API to parameterise the interface.

SSH

The client will connect to the location pointed to by DOCKER_HOST environment variable, or ssh://localhost if missing.

use bollard::Docker;
#[cfg(feature = "ssh")]
Docker::connect_with_ssh_defaults();

Use the [Docker::connect_with_ssh] or [Docker::connect_with_ssh_options] method API to parameterise the interface.

Examples

Note: all these examples need a Tokio Runtime.

Version

First, check that the API is working with your server:

use bollard::Docker;

use futures_util::future::FutureExt;

// Use a connection function described above
// let docker = Docker::connect_...;

async move {
    let version = docker.version().await.unwrap();
    println!("{:?}", version);
};

Listing images

To list docker images available on the Docker server:

use bollard::Docker;
use bollard::query_parameters::ListImagesOptionsBuilder;

use futures_util::future::FutureExt;

// Use a connection function described above
// let docker = Docker::connect_...;

async move {
    let options = ListImagesOptionsBuilder::default()
        .all(true)
        .build();
    let images = &docker.list_images(Some(options)).await.unwrap();

    for image in images {
        println!("-> {:?}", image);
    }
};

Streaming Stats

To receive a stream of stats for a running container.

use bollard::Docker;
use bollard::query_parameters::StatsOptionsBuilder;

use futures_util::stream::TryStreamExt;

use std::default::Default;

// Use a connection function described above
// let docker = Docker::connect_...;

async move {
    let stats = &docker.stats("postgres", Some(
      StatsOptionsBuilder::default().stream(true).build()
    )).try_collect::<Vec<_>>().await.unwrap();

    for stat in stats {
        println!("{} - mem total: {:?} | mem usage: {:?}",
            stat.name.as_ref().unwrap(),
            stat.memory_stats.as_ref().unwrap().max_usage,
            stat.memory_stats.as_ref().unwrap().usage);
    }
};

Examples

Further examples are available in the examples folder, or the integration/unit tests.

Development

Contributions are welcome, please observe the following.

Building the proto models

Serialization models for the buildkit feature are generated through the Tonic library. From the repository root, use:

cargo xtask buildkit update
cargo xtask buildkit check

update resolves the Moby-derived BuildKit version and protobuf sources, updates the provenance lockfile, and regenerates the bindings. check regenerates into a temporary directory using the locked inputs and compares against the checked-in bindings. For more information see the protobuf provenance README.

Building the swagger models

Serialization models are generated through the Swagger library. To generate these files, use the following in the codegen/swagger folder:

mvn -D org.slf4j.simpleLogger.defaultLogLevel=error compiler:compile generate-resources

Integration tests

Running the integration tests by default requires a running docker registry, with images tagged and pushed there. To disable this behaviour, set the DISABLE_REGISTRY environment variable.

docker run -d --restart always --name registry -p 5000:5000 registry:2
docker pull hello-world:linux
docker pull fussybeaver/uhttpd
docker pull alpine
docker tag hello-world:linux localhost:5000/hello-world:linux
docker tag fussybeaver/uhttpd localhost:5000/fussybeaver/uhttpd
docker tag alpine localhost:5000/alpine
docker push localhost:5000/hello-world:linux
docker push localhost:5000/fussybeaver/uhttpd
docker push localhost:5000/alpine
docker swarm init
REGISTRY_HTTP_ADDR=localhost:5000 cargo test -- --test-threads 1

License: Apache-2.0