Expand description
Bollard: an asynchronous rust client library for the docker API
Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API containing futures and streams.
The library also features Windows support through Named Pipes and HTTPS support through optional SSL bindings or a native TLS implementation.
Install
Add the following to your Cargo.toml
file
[dependencies]
bollard = "0.1"
API documentation
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();
Windows named pipe
The client will connect to the standard windows pipe location \\.\pipe\docker_engine
. Use the
Docker::connect_with_name_pipe
method API
to parameterise the interface.
use bollard::Docker;
#[cfg(windows)]
Docker::connect_with_named_pipe_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 openssl
Openssl is switched off by default, and can be enabled through the ssl
cargo feature.
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 = "openssl")]
Docker::connect_with_ssl_defaults();
TLS
Native TLS allows you to avoid the SSL bindings.
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 - identity.pfx
for the PKCS #12 archive and ca.pem
for the certificate
authority chain.
Use the Docker::connect_with_ssl
method API
to parameterise the interface.
use bollard::Docker;
Docker::connect_with_tls_defaults();
Examples
Note: all these examples need a Tokio Runtime. A small example about how to use Tokio is below.
Version
First, check that the API is working with your server:
use futures::Future;
use bollard::Docker;
// Use a connection function described above
// let docker = Docker::connect_...;
docker.version()
.map(|version| {
println!("{:?}", version);
});
Listing images
To list docker images available on the Docker server:
use futures::Future;
use bollard::Docker;
use bollard::image::ListImagesOptions;
use std::default::Default;
// Use a connection function described above
// let docker = Docker::connect_...;
docker.list_images(Some(ListImagesOptions::<String> {
all: true,
..Default::default()
}))
.map(|images| {
for i in images {
println!("-> {:?}", i);
}
});
Streaming Stats
To receive a stream of stats for a running container.
use futures::stream::Stream;
use bollard::Docker;
use bollard::container::StatsOptions;
use std::default::Default;
// Use a connection function described above
// let docker = Docker::connect_...;
docker.stats("postgres", Some(StatsOptions {
stream: true,
..Default::default()
}))
.map(|stat| {
println!("{} - mem total: {:?} | mem usage: {:?}",
stat.name,
stat.memory_stats.max_usage,
stat.memory_stats.usage);
});
Chaining docker commands
It’s sometimes more convenient to chain a string of Docker API calls. The DockerChain
API
will return an instance of itself in the return call.
use bollard::Docker;
use bollard::image::CreateImageOptions;
use bollard::container::CreateContainerOptions;
use bollard::container::Config;
use tokio::prelude::Future;
use std::default::Default;
// Use a connection function described above
// let docker = Docker::connect_...;
docker.chain().create_image(Some(CreateImageOptions{
from_image: "hello-world",
..Default::default()
})).and_then(|(docker, _)|
docker.create_container(
None::<CreateContainerOptions<String>>,
Config {
image: Some("hello-world"),
cmd: Some(vec!["/hello"]),
..Default::default()
}));
Examples
Further examples are available in the examples folder, or the integration/unit tests.
A Primer on the Tokio Runtime
In order to use the API effectively, you will need to be familiar with the Tokio Runtime.
Create a Tokio Runtime:
use tokio::runtime::Runtime;
let mut rt = Runtime::new().unwrap();
Subsequently, use the docker API:
// Use a connection function described above
// let docker = Docker::connect_...;
let future = docker.list_images(None::<ListImagesOptions<String>>);
Execute the future aynchronously:
rt.spawn(future);
Or, to execute and receive the result:
let result = rt.block_on(future);
Finally, to shut down the executor:
rt.shutdown_now().wait().unwrap();
History
This library stems from the boondock rust library, which in turn originates from the rust-docker library, but most parts were rewritten to adobt the new functionality provided by tokio. 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 fnichol/uhttpd
docker tag hello-world:linux localhost:5000/hello-world:linux
docker tag fnichol/uhttpd localhost:5000/fnichol/uhttpd
docker push localhost:5000/hello-world:linux
docker push localhost:5000/fnichol/uhttpd
REGISTRY_HTTP_ADDR=localhost:5000 cargo test --test-threads 1