Crate pangu_bollard
source ·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, 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
Latest
Version 0.14
enables a buildkit
feature for builds using public images (check the
buildkit example
for details on how to configure).
Feature flags
ssl
: enable SSL support through Rustlschrono
: enable Chrono forDateTime
types.time
: enable Time 0.3 forDateTime
types.buildkit
: use Buildkit instead of Docker when building images.json_data_content
: Add JSON to errors on serialization failures.ct_logs
: Certificate transparency verification (requiresssl
).
Version
The Docker API used by Bollard is using the latest
1.41
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::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.
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
- Credentials management, for access to the Docker Hub or a custom Registry.
- Container API: run docker containers and manage their lifecycle
- Errors for this module.
- Exec API: Run new commands inside running containers
- Image API: creating, manipulating and pushing docker images
- Network API: Networks are user-defined networks that containers can be attached to.
- Secret API: manage and inspect docker secrets within a swarm
- Service API: manage and inspect docker services within a swarm
- System API: interface for interacting with the Docker server and/or Registry.
- Volume API: Create and manage persistent storage that can be attached to containers.
Structs
- 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.
Constants
- Default Client Version to communicate with the server.