certbot-docker-swarm - Certbot plugin for Docker Swarm Secrets
certbot-docker-swarm is a certbot installer plugin that can be used to automatically deploy TLS certificates as Docker Swarm Secrets. certbot-docker-swarm also automatically updates Swarm services to use the new secrets after renewal.
Usage
Install certbot-docker-swarm by running the following commands:
git clone git@github.com:eerotal/certbot-docker-swarm.git
cd certbot-docker-swarm
python3 setup.py install
After running these commands, you can verify that the installation
was successful by running certbot plugins
. This should print a list
of all plugins certbot is able to find. One of the plugins listed
should be docker-swarm. You can tell certbot to use the installer
plugin by passing -i docker-swarm
when invoking certbot. See the
certbot man page
for more info.
certbot-docker-swarm also has Docker images on Docker Hub. See the docker/ subdirectory for more info.
Swarm Secrets
When certificates are renewed certbot-docker-swarm creates Docker Swarm Secrets named with the format
{domain}_{name}_v{version}
where
{domain}
= The domain the certificate authenticates.{name}
= The name of the secret. One of: cert, key, chain, fullchain.{version}
= The Unix Epoch timestamp of the certificate in seconds.
All generated secrets have a set of labels:
certbot.managed
= Always "true".certbot.domain
= The domain the certificate authenticates.certbot.name
= The name of the secret. One of: cert, key, chain, fullchain.certbot.version
= The Unix Epoch timestamp of the certificate in seconds.
These labels are used by certbot-docker-swarm for identifying services which need to be updated after certificate renewal.
Configuring Swarm Services
If your domain is example.com, you can create an nginx Swarm service that uses a certificate managed by certbot-docker-swarm by running
docker service create \
--secret source=example.com_cert_v{version},target=example.com_cert \
--secret source=example.com_key_v{version},target=example.com_key \
--secret source=example.com_chain_v{version},target=example.com_chain \
--secret source=example.com_fullchain_v{version},target=example.com_fullchain \
--name nginx \
nginx:alpine
If your service doesn't need all of the secrets you can omit the ones that aren't required. Secrets will still be generated from those files aswell but they won't be attached to your services.
If you deploy your Docker Swarm Services using docker-compose files, you can use a configuration similar to the one below:
...
...
version: '3.9'
services:
nginx
image: nginx:alpine
...
...
secrets:
- example.com_cert
- example.com_key
- example.com_chain
- example.com_fullchain
secrets:
example.com_cert:
name: example.com_cert_v{version}
external: true
example.com_key:
name: example.com_key_v{version}
external: true
example.com_chain:
name: example.com_chain_v{version}
external: true
example.com_fullchain:
name: example.com_fullchain_v{version}
external: true
...
...
Dependencies
In addition to Docker with Swarm mode enabled you'll need the following dependencies from PyPI:
- docker >= 4.4
- certbot >= 1.10
These are, however, automatically installed by the setup.py
script.
Development
Building development Docker images
All Docker related configuration and source files are in docker/
. You can
run the docker/build.sh
script to build a development Docker image tagged
with :dev
. Note that the included Dockerfile clones the
certbot-docker-swarm sources from the remote git repository, which means
your local changes won't be included in the built images by default.
Running tests
certbot-docker-swarm uses tox to automate linting, unit tests etc. Install tox with
pip install tox
By default tox tries to use all the environments defined in tox.ini
, ie.
lint, py27, py35, py36, py37, py38, py39
. If you only want to lint the
codebase against PEP-8 you can run
python3 -m tox -e lint
To run unit tests using the Python binary in your path run
python3 -m tox -e py
You can also use python
in place of python3
if both are in your PATH.
CI/CD pipeline
certbot-docker-swarm uses GitHub Actions for its CI/CD pipeline. The pipeline includes linting and running tests against all commits as well as deploying released Docker images to Docker Hub.
License
certbot-docker-swarm is licensed under the BSD 3-clause license. See
the file LICENSE
for more information.
Copyright Eero Talus 2021