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
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 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.
use 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 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 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 Docker;
use FutureExt;
// Use a connection function described above
// let docker = Docker::connect_...;
async move ;
Listing images
To list docker images available on the Docker server:
use Docker;
use ListImagesOptions;
use FutureExt;
use Default;
// Use a connection function described above
// let docker = Docker::connect_...;
async move ;
Streaming Stats
To receive a stream of stats for a running container.
use Docker;
use StatsOptions;
use TryStreamExt;
use Default;
// Use a connection function described above
// let docker = Docker::connect_...;
async move ;
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:
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.
REGISTRY_HTTP_ADDR=localhost:5000
License: Apache-2.0