marathon-acme 0.1.0

How it works

There is one big requirement for deploying marathon-acme: there must be shared persistent storage between marathon-acme and all marathon-lb instances. This will be used to store the certificates.

1. marathon-acme watches Marathon for changes to app definitions.

2. It collects the values of all MARATHON_ACME_{n}_DOMAIN labels on apps. This will form the set of domains to fetch certificates for.

3. It generates, verifies and stores certificates for any new domains using the configured ACME certificate authority.

4. It tells marathon-lb to reload using the marathon-lb HTTP API.

5. It issues new certificates for soon-to-expire certificates once a day.

marathon-acme is written in Python using Twisted. The certificate issuing functionality is possible thanks to the `txacme <https://github.com/mithrandi/txacme>`__ library.

The ACME provider that most people are likely to use is Let’s Encrypt. Before using marathon-acme with Let’s Encrypt, make sure you are aware of their rate limits.

Usage

marathon-acme will eventually be available as a pip-installable Python package on PyPi. For now, a development Docker image is available here.

> $ docker run --rm praekeltfoundation/marathon-acme:develop marathon-acme --help
usage: marathon-acme [-h] [-a ACME] [-e EMAIL] [-m MARATHON[,MARATHON,...]]
                     [-l LB[,LB,...]] [-g GROUP] [--listen LISTEN]
                     [--log-level {debug,info,warn,error,critical}]
                     storage-dir

Automatically manage ACME certificates for Marathon apps

positional arguments:
  storage-dir           Path to directory for storing certificates

optional arguments:
  -h, --help            show this help message and exit
  -a ACME, --acme ACME  The address for the ACME Directory Resource (default:
                        https://acme-v01.api.letsencrypt.org/directory)
  -e EMAIL, --email EMAIL
                        An email address to register with the ACME service
                        (optional)
  -m MARATHON[,MARATHON,...], --marathon MARATHON[,MARATHON,...]
                        The addresses for the Marathon HTTP API (default:
                        http://marathon.mesos:8080)
  -l LB[,LB,...], --lb LB[,LB,...]
                        The addresses for the marathon-lb HTTP API (default:
                        http://marathon-lb.marathon.mesos:9090)
  -g GROUP, --group GROUP
                        The marathon-lb group to issue certificates for
                        (default: external)
  --listen LISTEN       The address for the port to listen on (default: :8000)
  --log-level {debug,info,warn,error,critical}
                        The minimum severity level to log messages at
                        (default: info)

{
  "id": "/marathon-acme",
  "cpus": 0.01,
  "mem": 128.0,
  "labels": {
    "HAPROXY_GROUP": "external",
    "HAPROXY_0_VHOST": "example.com",
    "HAPROXY_0_BACKEND_WEIGHT": "1",
    "HAPROXY_0_PATH": "/.well-known/acme-challenge/",
    "HAPROXY_0_HTTP_FRONTEND_ACL_WITH_PATH": "  acl path_{backend} path_beg {path}\n  use_backend {backend} if path_{backend}\n",
    "HAPROXY_0_HTTPS_FRONTEND_ACL_WITH_PATH": "  use_backend {backend} if path_{backend}\n"
  },
  "container": {
    "type": "DOCKER",
    "docker": {
      "image": "praekeltfoundation/marathon-acme:develop",
      "network": "BRIDGE",
      "portMappings": [
        { "containerPort": 8000, "hostPort": 0 }
      ],
      "parameters": [
        {
          "value": "xylem",
          "key": "volume-driver"
        },
        {
          "value": "marathon-acme-certs:/var/lib/marathon-acme",
          "key": "volume"
        }
      ],
    }
  }
}

--ssl-certs <storage-dir>/certs,<storage-dir>/default.pem

Limitations

The current biggest limitation with marathon-acme is that it will only issue one certificate for one domain per app port. This is to limit the number of certificates issued so as to prevent hitting Let’s Encrypt rate limits.

The library used for ACME certificate management, txacme, is currently quite limited in its functionality. The two biggest limitations are: * Only anonymous ACME registrations are supported (#72). This means you will not receive reminder emails from Let’s Encrypt when your certificates are about to expire. * There is no Subject Alternative Name (SAN) support yet (#37). Each certificate will correspond to exactly one domain name. This limitation makes it easier to hit Let’s Encrypt’s rate limits.

For a more complete list of issues, see the issues page for this repo.