Crate bollard

Crate bollard 

Source
Expand description

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.

This library 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

  • ssl: enable SSL support through Rustls with the ring provider.
  • aws-lc-rs: enable SSL support through Rustls with the aws-lc-rs provider.
  • ssl_providerless: enable SSL support through Rustls without installing a CryptoProvider. You are responsible to do so.
  • chrono: enable Chrono for DateTime types.
  • time: enable Time 0.3 for DateTime types.
  • buildkit: use Buildkit instead of Docker when building images.
  • buildkit_providerless: enable Buildkit support without installing a CryptoProvider.
  • json_data_content: Add JSON to errors on serialization failures.
  • webpki: Use mozilla’s root certificates instead of native root certs provided by the OS.

§Version

The Docker API used by Bollard is using the latest 1.49 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 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 bollard::Docker;
#[cfg(unix)]
Docker::connect_with_socket_defaults();

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

§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 bollard::Docker;
Docker::connect_with_local_defaults();

Use the Docker::connect_with_local 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 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 bollard::Docker;
#[cfg(feature = "ssl")]
Docker::connect_with_ssl_defaults();

Use the Docker::connect_with_ssl 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::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::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. To generate these files, use the following in the codegen/proto folder:

cargo run --bin gen --features build

§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

Modules§

auth
Credentials management, for access to the Docker Hub or a custom Registry.
container
Container API: run docker containers and manage their lifecycle
errors
Errors for this module.
exec
Exec API: Run new commands inside running containers
image
Image API: creating, manipulating and pushing docker images
models
network
Network API: Networks are user-defined networks that containers can be attached to.
node
Node API: Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
query_parameters
Method, error and parameter types for the endpoint.
secret
Secret API: manage and inspect docker secrets within a swarm
service
Service API: manage and inspect docker services within a swarm
swarm
Swarm API: Docker swarm is a container orchestration tool, meaning that it allows the user to manage multiple containers deployed across multiple host machines.
system
System API: interface for interacting with the Docker server and/or Registry.
task
Tasks API: A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.
volume
Volume API: Create and manage persistent storage that can be attached to containers.

Structs§

ClientVersion
Advisory version stub to use for communicating with the Server. The docker server will error if a higher client version is used than is compatible with the server. Beware also, that the docker server will return stubs for a higher version than the version set when communicating.
Docker

Constants§

API_DEFAULT_VERSION
Default Client Version to communicate with the server.

Functions§

body_full
Convenience method to wrap bytes into a bollard BodyType
body_stream
Convenience method to wrap a stream of bytes into frames for a bollard BodyType
body_try_stream
Convenience method to wrap a stream of failable bytes into frames for a bollard BodyType

Type Aliases§

BollardRequest
Request from bollard used with CustomTransport