How to get started with the Docker Engine API

0

Docker Engine exposes a REST API that you can use to control your containers without it. docker CLI. The API exposes equivalent functionality using HTTP network calls. You can script common Docker operations using your favorite programming language or remotely control one of your hosts. The CLI internally relies on the same API to provide its built-in commands.

In this article, we’ll look at the basics of enabling and using the API. If you have a specific use case in mind, refer to the API reference documentation to identify the endpoints you need.

Enable Docker Engine API

The API is integrated with Docker Engine. Any working Docker host is already ready to respond to API interactions. To expose the service, you must bind the Docker daemon to a TCP socket in addition to or instead of the default Unix socket. Begin dockerd with the -H flag to specify the sockets to listen to:

sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

This command exposes the API on port 2375. The default Unix socket is retained so that the Docker CLI continues to work without any reconfiguration. Port 2375 is used for Docker by convention; feel free to modify it to suit your environment.

You can make Docker always start with these settings by changing its systemd service configuration file. Edit or create /etc/systemd/system/docker.service.d/options.conffind it ExecStart line and edit it to include your additional flags:

[Service]
ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

Recharge your systemd configuration to apply the change:

sudo systemctl daemon-reload

You are now ready to interact with the Docker Engine API on 127.0.0.1:2375.

A note on security

The above steps expose the API without any protection. Anyone with access to port 2375 on your host can send arbitrary commands to the Docker daemon, start new containers, fill your disk with images, or destroy existing workloads.

You should configure your firewall to block connections to the port unless you intentionally expose Docker on your network. If you want to enable remote access, you must configure TLS for the daemon socket to limit access to authenticated clients.

When TLS is enabled, you must install your daemon CA on each of your clients. You will need to provide the client certificate and client key with every request you make. The steps to follow depend on the tool you are using. Here is an example for curl:

curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem

You may not need to bind a TCP socket at all depending on your use case. If your client supports Unix sockets, you can use the existing one from Docker to make your connections:

curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers

This may be a safer choice than risking unintentionally exposing a TCP socket.

Using the API

The Uses of the API versioned endpoints so you can pin specific versions of request and response formats. You must indicate the version you are using at the beginning of each endpoint URL. v1.41 is the latest version present in the production versions of Docker at the time of writing.

http://127.0.0.1:2375/v1.41

API endpoints are grouped into REST functional units. These correspond to Docker’s fundamental object types such as containers, images, and volumes. You can usually find the APIs for a specific object type in the base URL that begins with its name:

# APIs related to container operations
http://127.0.0.1:2375/v1.41/containers

The API uses JSON for all data exchange with your HTTP client. Endpoints accept JSON request bodies and issue JSON responses back. This should simplify data management in your applications because you can use the included JSON library in your programming environment. tools like jq can be used to condense, filter and sort responses if you experiment in your terminal.

Common endpoints

As the API replicates the functionality of the Docker CLI, there are too many possible endpoints to cover them all here. Instead, we’ll demonstrate some of the more commonly used options for basic Docker functionality.

List containers

The full list of containers on the host can be obtained from the /containers/json period :

curl http://127.0.0.1:2375/v1.41/containers/json

By default, it only shows running containers. To add all=true to the query string to also include stopped containers. Limit the total number of containers returned with the limit parameter, such as limit=10. Only the 10 most recently created containers will be included.

Several different filters are available to prune the list to containers with particular attributes. These are defined with the following syntax:

curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}

This URL returns the information associated with the demo container. Other filters can be expressed in a similar way, such as {"status":["running","paused"]} to get running and paused containers or {"health=["healthy"]} only for healthy containers.

Start a new container

Starting a container is a two-step process when using the API. You need to create the container first and then start it in a separate API call.

Create your container by making a POST ask the /containers/create period. This requires a JSON body with fields that match the flags accepted by the docker run CLI command.

Here is a minimal example of creating a container:

curl http://127.0.0.1:2375/v1.41/containers/create 
    -X POST 
    -H "Content-Type: application/json" 
    -d '{"Image": "example-image:latest"}'

The JSON response will include the ID of the new container and any warnings resulting from its creation. Send the ID during a call to /containers/:id/start period :

curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST

The container will now run on the Docker host.

Clean containers

Remove stopped containers by issuing a POST ask the /containers/prune period :

curl http://127.0.0.1:2375/v1.41/containers/prune -X POST

You will receive a JSON response with ContainersDeleted and SpaceReclaimed the fields. ContainersDeleted is an array of container IDs that have been successfully deleted. SpaceReclaimed informs you of the total freed storage space in bytes.

This endpoint accepts two query string parameters to limit the operation. The until setting limits deletion to containers created before a given time, such as until=10m Where until=2022-03-01. The label option filters to containers with or without given labels; setting label=demo=example will only remove containers with the demo=example label.

List of images

The /images/json endpoint is used to enumerate the images stored on the Docker host:

curl http://127.0.0.1:2375/v1.41/images/json

You can use filters to modify the content of the response. These are provided as a JSON object in the filters query string parameter, similar to container list API. A remarkable option is reference which selects the image with a given tag: filters={"reference":"hello-world:latest"}.

Images of buildings

You can use the API to create new Docker images from Dockerfiles. The /build endpoint must receive a tar archive. The contents of this archive will be used as the context for building the image. The archive must include Dockerfile containing the instructions for building.

cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST

The above command will send context.tar to the Docker daemon and create an image using Dockerfile in. The image will be labeled as example-image:latest and stored on the Docker host.

This endpoint accepts many additional query string parameters that match the functionality of the docker build CLI. These include dockerfile=path/to/dockerfileto specify the path to the Dockerfile of the build context, rm=truewhich removes intermediate containers created by the build, and pull=true to try to acquire updated versions of the images referenced by the Dockerfile.

The API requires your client to remain logged in until the build is complete. The construction will be canceled if the network drops and the connection is closed.

List of daemon event logs

The /events The API brings up daemon event log data which is also accessible with the docker events CLI command. This endpoint broadcasts events in real time as they occur.

curl http://127.0.0.1:2375/v1.41/events

Several different types of events are exposed, including container creations, image tags, volume mounts, and network changes. You can filter on a specific event type using the type domain of filters query parameter:

# Only get container events
curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}

It is also possible to constrain to events relating to a specific object:

# Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}

Two other query string parameters, since and untilallow you to specify a range of timestamps to display historical events in.

Get system information

The Docker Engine API can be used to get information about the physical host it is running on:

curl http://127.0.0.1:2375/v1.41/info

This endpoint provides detailed details describing the current state and configuration of the host and the Docker daemon. Response fields include the number of containers running, suspended, and stopped, the path to the Docker installation directory, hardware and operating system details, and the Swarm configuration of the server when running in a cluster.

Conclusion

The Docker Engine API allows you to send commands to your host’s Docker daemon over HTTP. This simplifies scripting programmatic interactions without depending on specific Docker CLI behaviors. The API can also be used to remotely manage your Docker servers for improved monitoring and easier maintenance.

Although calling the API is simple, you should be careful about the security protections around your TCP socket. Avoid exposing the socket on your network unless it’s secured with TLS so that only trusted clients can connect. Skipping this extra configuration step could be costly if an intruder discovers your daemon instance and starts issuing commands.

You can make it even easier to use the API in your own applications by adopting one of the SDKs. An official or community-provided option is available for all popular programming languages, including C, C#, C++, Go, Java, NodeJS, PHP, Python, and Ruby. SDKs wrap API endpoints in convenient classes and functions to call from your code, reducing the amount of boilerplate needed to interact with a Docker installation.


Source link

Share.

Comments are closed.