Docker Cloud is a well-known platform as a service (PaaS) that offers a registry, testing and build faculties for Docker images. It has a nice, clean web UI, but there may be folks who want to circumvent the Docker Cloud web UI to further automate Docker Cloud from the REST API.
In this piece, we’ll showcase some examples of how to use the Docker Cloud REST API. We’ll walk through obtaining an API key, authorizing access, initiating and monitoring deploys, creating a new container, creating repos, checking deployment zones, registry logs and more using HTTP REST calls. Learning how to operate Docker Cloud over HTTP has some interesting benefits, so let’s dig in.
Getting Started with the Docker Cloud API
For the purpose of this walk-through, we’ll use cURL over HTTP.
To start, you’ll need to obtain API keys, which can be found in User > Account Settings > API keys.
To authenticate with the Docker Cloud API, insert your API key using ‘Basic’ authentication as follows:
The Docker Cloud HTTP REST API is reachable at the https://cloud.docker.com/ endpoint, whereas the Docker Websocket Stream API endpoint is wss://ws.cloud.docker.com/. Both use the same authentication schematic, but ensure to direct calls to the appropriate endpoints as they vary per function.
Lastly, Docker Cloud does have a “full access” role (explained here) that allows any container operations to be performed on the API with a specific authorization token. It’s recommended to enable this to get the full value of using the Docker Cloud API.
Specific Actions Using the Docker Cloud API
So let’s check out some specific functions using the Docker Cloud API. There are many actions, but we’ll pick out a few ones that could direct further automation.
Discover AWS Availability Zones
Say you’re running on AWS, and want to check if a location in a region is available for new deployments. This will list all Availability Zone objects.
JSON results from this response could help direct automated deployments.
Update a Node
The API can list nodes, retrieve information on a node, perform health checks and upgrades, terminate them and more. For example, a PATCH request can be used to update a node, accepting a user-friendly name and tags as JSON parameters:
Start a Container
Using the Docker Cloud API, you can list containers, GET container details and logs, redeploy a container and more. For example, this POST request will start a paused container:
Advanced Container Commands
Using the API, you can even venture inside containers to initiate specific commands. These create bi-directional stream and can be reached using a Web Socket (the Docker Websocket Stream API).
Execute a Trigger
Triggers are easy-to-use URLs that will conveniently trigger a redeployment of a service given a simple POST call. Since they don’t require authorization headers, Docker reminds users to keep these URLs safe!
For example, executing a trigger to REDEPLOY a service can be done over HTTP as such:
The powers in triggers are redeploying or scaling up services by adding additional containers.
Get a Registry
To retrieve information on a specific registry, you can send a simple GET API request as follows.
Add a New External Repository
Repositories in Docker CLoud store Docker images, however, you can add external ones too. To programmatically add a GitHub repo, for example, a POST API call will do the trick:
This is by no means a comprehensive list of API calls, but it demonstrates the power of using the Docker Cloud API to programmatically achieve every container orchestration command you could dream of.
For more advanced operations, see the Docker Cloud API Documentation. The documentation has code samples for Go, Python, HTTP and the CLI derivative.
Benefits of Using Docker Cloud API
You may be thinking, what are the benefits of accessing the HTTP API directly as opposed to the Docker UI?
Sure, the commands above and more can be processed through the Docker Cloud web interface, but using an API over HTTP inherently comes with major benefits:
- Automation: If you want to make Docker more programmable, using API commands improves machine automation.
- HTTP: Using HTTP as a common transport layer means you’re communicating agnostically.
- Workflow: Who knows, cURL API commands could fit better into your workflow, if you prefer to develop and deploy in your favorite CLI.
- More, more automation!: Helps streamline with automation: a cool thing is the build automation that whips up images from source code in your repos.
- Chaining: Tethering API responses to further calls could help automate CI/CD workflows.
Finally, the functionality of the API mirrors the platform experience. Docker explicitly says that the API documentation “contains all API operations currently supported in the platform.” This means you can do anything you want with Docker, but programmatically.
While it may not be necessary for basic users—it is another hurdle to working with Docker—mastering the use of Docker Cloud API has some interesting rewards.
Of course, the Docker Cloud API does match the privileges of your Docker account (Community Edition versus Enterprise Edition products), and there is good value in other container orchestration platforms like Kubernetes.
Nonetheless, getting started with the Docker Cloud API early on can be a time-saving initiative if you do scale Docker usage into the future.