Utilising the Docker Engine API

Docker has cemented itself as a mainstream technology, not only for the development and deployment of web services, but also the isolation of Linux applications that need to be ran in a controlled or sandboxed environment.

Whilst the docker CLI is brilliant, it can be difficult to expose this to custom utilities, or to present it's output in a user friendly way - such as the way that Docker Swarm Visualizer does. To do this, we need to go a little deeper in to the Docker rabbit-hole...

The Docker Engine API

The docker deamon (dockerd) listens on a Unix Socket - /var/run/docker.sock - and exposes a very simple JSON API. This allows you to manage many aspects of your Docker instance or swarm; in fact, it's this API which powers the docker CLI client - so anything you can do via the CLI can also be done via the API.

Being a JSON API, it becomes trivial to write clients - and these can be implemented in any language that can (a) make HTTP requests, (b) handle JSON objects, and (c) access Unix Sockets. For example, here is a fully fledged client written in PHP:

How about remote Docker instances?

There's obviously a caveat with the above guidance: access to a unix socket requires you to have the relevant privileges and be executing code from the same machine, and by it's very nature, most interactions with docker are remote.

Fortunately, Docker can listen on TCP sockets as well - exposing a HTTP interface with the same endpoints as above. This can be done as simply as passing an extra flag - -H - to dockerd upon startup:

$ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106

Alas, whilst the command above may be relatively safe - after all, it's listening on a local IP address (192.168...) - this would be a very Bad Idea™ to do on a publicly accessible hostname.

To communicate with a remote dockerd host, you really need to pay attention to "Protect the Docker daemon socket"; a document that goes in to lovely certificate management, using terminology like OpenSSL, x509 and TLS. If you're exposing a dockerd instance to the outside world though, you need to grasp this.

How do I use the API?

It's little use being given the keys to the kingdom if you don't have a map! Fortunately for any avid explorers, the Docker Engine API documentation (here's that link again) is pretty extensive.

Example

I've written a basic example of using the Docker API - available on Github - which allows a user to manage Docker Secrets via a nice little web panel. It's written in Golang (yes, it's an API over an API..!) with a front-end using Vuejs.


Fergus

Contract Software Developer and DevOps Consultant, based out of London in England. Interests include information security, current affairs, and photography.