certbot #2
Description
Acquire certificates from Let's Encrypt and manage them for use by related charms.
certbot
Description
Certbot is used to acquire and manage certificates from Let's Encrypt.
Acquiring Certificates
The charm will attempt to acquire a certificate in the start hook, this
will only be successful if the charm has been configured for acquiring
certificates. The configuration parameters agree-tos
, domains
,
email
& plugin
must have all been set for this to work along with
any necessary plugin-specific settings.
DNS-Google Plugin
Certbot's dns-google plugin uses the Google Cloud DNS API to prove
ownership of the requested domain. Documentation for the plugin can be
found at https://certbot-dns-google.readthedocs.io/en/stable/. This
plugin requires API credentials to be supplied either through the
credentials
parameter on the get-certificate
action, or from the
dns-google-credentials
setting in the charm configuration.
To acquire a certificate using this plugin run a command like the following:
$ juju run-action --wait certbot/0 get-certificate \
agree-tos=true \
credentials=`cat cred.json | base64 -w0` \
domains=example.com \
email=webmaster@example.com \
plugin=dns-google
DNS-Route53 Plugin
Certbot's dns-route53 plugin uses the AWS Route53 API to prove
ownership of the requested domain. Documentation for the plugin can be
found at https://certbot-dns-route53.readthedocs.io/en/stable/. This
plugin requires API credentials to be supplied either through the
aws-access-key-id
and aws-secret-access-key
parameters on the
get-certificate
action, or from the dns-route53-aws-access-key-id
and dns-route63-aws-secret-access-key
settings in the charm
configuration.
To acquire a certificate using this plugin run a command like the following:
$ juju run-action --wait certbot/0 get-certificate \
agree-tos=true \
aws-access-key-id=ABCDEFGHIJKLMNOPQRST \
aws-secret-access-key=YcdqUfSGwvmIJAhjWNzGxSifdXr78RRqZrMnPxoz \
domains=example.com \
email=webmaster@example.com \
plugin=dns-route53
Integrating With Web-Servers
HAProxy
HAProxy uses a combined certificate chain and key file for its TLS
confguration. If the combined-path
charm configuration setting is
configured then a suitable file will be created at that path.
The easiest way to use this charm with the haproxy charm is to set the following configuration settings:
combined-path: /ver/lib/haproxy/default.pem
deploy-command: systemctl reload haproxy
In the haproxy charm configuration set services
to something like:
- service_name: app_https
service_host: "0.0.0.0"
service_port: 443
service_options:
- mode http
- option httpchk GET / HTTP/1.0
crts: [DEFAULT]
server_options: check inter 2000 rise 2 fall 5 maxconn 4096
- service_name: api_http
service_host: "0.0.0.0"
service_port: 80
service_options:
- mode http
- http-request redirect scheme https
Notes about Scale Out
The units of a certbot application will make no attempt to communicate with each other, and do not share certificates. This means that the units will have to acquire certificates individually.
If the charm is configured to acquire certificates in the start hook then there is a potential for units to race acquiring certificates. In most cases this is not a problem. If a unit fails to acquire a certificate in the start hook it charm will remain in the blocked state and a certificate will have to be acquired using an action instead.
Developing
Create and activate a virtualenv, and install the development requirements,
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements-dev.txt
Testing
Just run run_tests
:
./run_tests
Configuration
- agree-tos
- (boolean) Agree to the terms-of-service. If using Let's Encrypt these can be found at https://letsencrypt.org/repository/
- cert-path
- (string) Path to which the certificate will be copied. If this path is an existing directory then the certificate will be copied into a file named <domain>.crt in that directory.
- chain-path
- (string) Path to which the certificate chain will be copied. If this path is an existing directory then the certificate chain will be copied into a file named <domain>_chain.pem in that directory.
- combined-path
- (string) Path to which the combined full certificate chain and private key will be copied. If this path is an existing directory then the combined full certificate chain and key will be copied into a file named <domain>.pem in that directory.
- deploy-command
- (string) Command to run to deploy a certificate following a successful acquisition or renewal.
- dns-google-credentials
- (string) Base64 encoded credential file used by the dns-google plugin to access the DNS system. For details of this file please see https://certbot-dns-google.readthedocs.io/en/stable/#credentials
- dns-route53-aws-access-key-id
- (string) AWS_ACCESS_KEY_ID used by dns-route53 plugin to authenticate access to the DNS API. For details please see https://certbot-dns-route53.readthedocs.io/en/stable/#credentials
- dns-route53-aws-secret-access-key
- (string) AWS_ACCESS_SECRET_KEY used by dns-route53 plugin to authenticate access to the DNS API. For details please see https://certbot-dns-route53.readthedocs.io/en/stable/#credentials
- domains
- (string) The domains to create the certificate for. This comma-separated list contains all the domains to add to the certificate. The first domain will be the subject of the certificate. Any additional names will be added to the certificate as alternative names.
- (string) Email address to register the certificates under.
- fullchain-path
- (string) Path to which the full certificate chain will be copied. If this path is an existing directory then the full certificate chain will be copied into a file named <domain>_fullchain.pem in that directory.
- key-path
- (string) Path to which the private key will be copied. If this path is an existing directory then the private key will be copied into a file named <domain>.key in that directory.
- plugin
- (string) The authenticator plugin to use to obtain (and renew) the ceritificate. The currently supported plugins are dns-google & dns-route53.
- propagation-seconds
- (int) The number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record.
- 60