To secure a Docker API on ubuntu we need openSSL installed. Use this openssl version command to check if openSSL is installed and return its version. We can also list all cipher algorithms available using this openssl ciphers -v command. The output of these commands is shown below. Build an Nginx Docker Image With Alpine And Secure It With A Self-Signed SSL Certificate With OpenSSL.edit
This article provides examples that can be used as a starting point when configuring SSL certificates.
Docker Secrets are a preferable way of managing SSL certificates. If you think secrets are a good fit for your use case, feel free to skip other methods and just straight into Adding Certificates As Docker Secrets.
The examples that follow assume that you are using Docker v1.13+, Docker Compose v1.10+, and Docker Machine v0.9+.
If you are a Windows user, please run all the examples from Git Bash (installed through Docker Toolbox). Also, make sure that your Git client is configured to check out the code AS-IS. Otherwise, Windows might change carriage returns to the Windows format.
Please note that Docker Flow Proxy is not limited to Docker Machine. We're using it as an easy way to create a cluster.
To setup an example Swarm cluster using Docker Machine, please run the commands that follow.
Feel free to skip this section if you already have a working Swarm cluster.
Now we're ready to deploy the services that form the proxy stack and the demo services.
Please consult Using Docker Stack To Run Docker Flow Proxy In Swarm Mode for a more detailed set of examples of deployment with Docker stack.
Before proceeding towards the SSL examples we should wait until all the services are running.
Even though we published the proxy port
443 and it is configured to forward traffic to our services,
SSL communication still does not work. We can confirm that by sending an HTTPS request to our demo service.
The output is as follows.
The error means that there is no certificate that should be used with HTTPS traffic.
There are two ways we can add certificates to the proxy. One is to create your own Docker image based on
Dockerfile could be as follows.
When the image is built, it will be based on
dockerflow/docker-flow-proxy and include
my-cert.pem file. The
my-cert.pem would be your certificate. Docker Flow proxy will load all certificates located in the
If your certificate is static (almost never changes) and you are willing to create your own
docker-flow-proxy image, this might be a good option. An alternative would be to mount a network volume with certificates.
Certificates can be added to the proxy dynamically through an HTTP request.
We'll start by creating a certificate we'll use throughout the examples.
For production, you should create your certificate through one of the trusted services. For demo purposes, we'll create a self-signed certificate with
openssl. Before proceeding, please make sure that
openssl is installed on your host OS.
We'll store a certificate in
tmp directory, so let us create it.
The certificate will be tied to the
*.xip.io domain, which is handy for demonstration purposes. It'll let us use the same certificate even if our server IP addresses might change while testing locally. With xip.io don't need to re-create the self-signed certificate when, for example, our Docker machine changes IP.
I use the xip.io service as it allows me to use a hostname rather than directly accessing the servers via an IP address. It saves me from editing me computers' host file.
To create a certificate, first we need a key.
With the newly created key, we can proceed and create a certificate signing request (CSR). The command is as follows.
You will be asked quite a few question. It is important that when 'Common Name (e.g. server FQDN or YOUR name)' comes, you answer it with
*.xip.io. Feel free to answer the rest of the question as you like.
Finally, with the key and the CSR, we can create the certificate. The command is as follows.
As a result, we have the
key files in the
Next, after the certificates are created, we need to create a
pem file. A pem file is essentially just the certificate, the key and optionally certificate authorities concatenated into one file. In our example, we'll simply concatenate the certificate and key files together (in that order) to create a
To demonstrate how
xip.io works, we can, for example, send the request that follows.
Our laptop thinks that we are dealing with the domain
xip.io. When your computer looks up the xip.io domain, the xip.io DNS server extracts the IP address from the domain and sends it back in the response. The xip.io service is useful for testing purposes.
Now we have the PEM file and a domain we'll use to test it. The only thing missing is to add it to the proxy.
We'll send the proxy service the PEM file we just created. Before we do that, we should publish the port
8080. It is proxy's internal port we can use to send it commands. If you already have the port
8080 published, there is no need to run the command that follows.
Please wait a few moments until the proxy is updated. You can check the status by executing the
docker service ps proxy command.
Now we can tell the proxy to use the certificate we created. The command is as follows.
PUT request to the proxy passed the certificate in its body (
--data-binary @tmp/xip.io.pem). The request URL has the certification name (
certName) as one of the parameters. The second parameter (
distribute) sends the proxy the signal to distribute the certificate to all the replicas. The result of the request is that the certificate has been added to all the replicas of the proxy. We can confirm that by inspecting the proxy config.
The relevant part of the output is as follows.
xip.io.pem has been added as an entry in /cfg/crt-list.txt to the
*:443 binding. The proxy is ready to serve HTTPS requests.
Let's confirm that HTTPS works.
Please note that you are not limited to a single certificate. You can send multiple
PUT requests with different certificates and they will all be added to the proxy.
Now you can secure your proxy communication with SSL certificates. Unless you already have a certificate, purchase it or get it for free from Let's Encrypt. The only thing left is for you to send a request to the proxy to include the certificate and try it out with your domain.
Now that we have a way to add certificates to the proxy, we might explore a more secure way to accomplish the same result.
Keeping certificates inside Docker images or mounted volumes is fairly insecure. To tighten the security, we can add a certificate as a Docker secret.
Once a secret is safely stored inside Swarm managers, the only thing missing is to add it to the proxy.
Normally, we would include certificates when creating the service. However, since the
proxy service is already running, we'll update it instead.
Docker stored the secret certificate inside all the containers that form the
Let's confirm that the certificate indeed works.
We got the
200 response confirming that the certificate is stored in the proxy as a Docker secret and that the configuration was updated accordingly.
Since many other types of information can be stored as secrets, Docker Flow Proxy assumes that secrets that should be used as certificates are prefixed with
cert_. Secrets with any other naming convention will not be loaded as certificates.
We explored a few ways to store certificates inside the proxy. We can build a new image that already includes the certificates or we can mount a network volume. Certificates can be added after the service was created through the PUT certificate request. Finally, we explored how we can leverage Docker secrets that provide a more secure way to transmit certificates to the proxy.
The recommended way to manage proxy certificates is through Docker secrets.