Need help with bollard?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

fussybeaver
256 Stars 54 Forks Apache License 2.0 635 Commits 18 Opened issues

Description

Docker daemon API in Rust

Services available

!
?

Need anything else?

Contributors list

crates.io license circle-ci appveyor docs

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 and HTTPS support through optional rustls bindings.

Install

Add the following to your

Cargo.toml
file
[dependencies]
bollard = "0.11"

API

Documentation

API docs.

Version 0.11 re-enables Windows Named Pipe support.

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.41
. 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.

Socket

The client will connect to the standard unix socket location

/var/run/docker.sock
or windows named pipe location
//./pipe/docker_engine
. Use the
Docker::connect_with_socket
method API to parameterise the interface.
use bollard::Docker;
#[cfg(unix)]
Docker::connect_with_socket_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.
rust
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:: { 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::>().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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.