Bollard: an asynchronous rust client library for the docker API
Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API containing futures, streams and the async/await paradigm.
The library also features Windows support through Named Pipes (disabled in 0.10, see below) and HTTPS support through optional rustls bindings.
Install
Add the following to your Cargo.toml file
[dependencies]
bollard = "0.9"
API
Documentation
Version 0.10 disables Named Pipe Windows support until the upstream Tokio project re-adds support for Named Pipes. Please follow the tracking issue for updates on this.
As of version 0.6, this project now generates API stubs from the upstream Docker-maintained Swagger OpenAPI specification. The generated models are committed to this repository, but packaged in a separate crate bollard-stubs.
Version
The Docker API is pegged at version 1.40. The library also supports version negotiation, to allow downgrading to an older API version.
Usage
Connecting with the docker daemon
Connect to the docker server according to your architecture and security remit.
Unix socket
The client will connect to the standard unix socket location /var/run/docker.sock. Use the Docker::connect_with_unix method API to parameterise the interface.
use bollard::Docker;
#[cfg(unix)]
Docker::connect_with_unix_defaults();
Local
The client will connect to the OS specific handler it is compiled for. This is a convenience for localhost environment that should run on multiple operating systems. Use the Docker::connect_with_local method API to parameterise the interface.
use bollard::Docker;
Docker::connect_with_local_defaults();
HTTP
The client will connect to the location pointed to by DOCKER_HOST environment variable, or localhost:2375 if missing. Use the Docker::connect_with_http method API to parameterise the interface.
use bollard::Docker;
Docker::connect_with_http_defaults();
SSL via Rustls
The client will connect to the location pointed to by DOCKER_HOST environment variable, or localhost:2375 if missing.
The location pointed to by the DOCKER_CERT_PATH environment variable is searched for certificates - key.pem for the private key, cert.pem for the server certificate and ca.pem for the certificate authority chain.
Use the Docker::connect_with_ssl method API to parameterise the interface.
use bollard::Docker;
#[cfg(feature = "ssl")]
Docker::connect_with_ssl_defaults();
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::image::ListImagesOptions;
use futures_util::future::FutureExt;
use std::default::Default;
// Use a connection function described above
// let docker = Docker::connect_...;
async move {
let images = &docker.list_images(Some(ListImagesOptions::<String> {
all: true,
..Default::default()
})).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::container::StatsOptions;
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(StatsOptions {
stream: true,
..Default::default()
})).try_collect::<Vec<_>>().await.unwrap();
for stat in stats {
println!("{} - mem total: {:?} | mem usage: {:?}",
stat.name,
stat.memory_stats.max_usage,
stat.memory_stats.usage);
}
};
Examples
Further examples are available in the examples folder, or the integration/unit tests.
Development
Contributions are welcome, please observe the following advice.
Building the stubs
Serialization stubs are generated through the Swagger library. To generate these files, use the following in the codegen folder:
mvn -D org.slf4j.simpleLogger.defaultLogLevel=debug clean compiler:compile generate-resources
History
This library was originally forked from the boondock rust library. Many thanks to the original authors for the initial code and inspiration.
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
![[WIP] example of attach output stream not closing](https://avatars.githubusercontent.com/u/901363?v=4)
2 Dec 30, 2022
58 Dec 15, 2022
39 Dec 21, 2022
26 Jun 15, 2023
5 Oct 3, 2023
20 Dec 8, 2022
101 Dec 19, 2022
3 Dec 6, 2023
2.7k Jan 7, 2023
6 Jun 3, 2022
741 Dec 26, 2022
43 Dec 29, 2022
10 Dec 15, 2022
3 Apr 24, 2023
4 May 7, 2023
4 Oct 29, 2023
327 Dec 20, 2022
5 May 24, 2022
246 Dec 20, 2022