autocert #19

Supports: xenial bionic trusty
Add to new model

Description

This charm installs and configures the Autocert X.509 certificate/key renewal
service client, and automatically restarts relevant services when new
certificates and/or keys are installed.


Overview

AutoCert provides automated certificate renewal. For more information about
AutoCert itself, see the Launchpad project page.

This charm is a subordinate that can be configured to connect to an AutoCert
server to retrieve certificates.

Usage

Deploy an apache2 charm with a relation to autocert:

juju deploy cs:apache2
juju deploy cs:nrpe
juju deploy cs:~autocert-charmers/autocert
# Configure to connect to your autocert server
juju config autocert autocert_host=autocert.example.com
# Configure for apache2
juju config autocert chain_required=true
juju config autocert service_action=restart
juju config autocert service_name=apache2
juju config autocert service_test_cmd="/usr/sbin/apache2ctl configtest"
# Configure your certificates (these should be considered secrets)
juju config autocert cert_auth_pairs="${CN}=${CN_TOKEN}"
# For services with multiple SSL certificates
juju config autocert cert_auth_pairs="${CN1}=${CN1_TOKEN},${CN2}=${CN2_TOKEN},${CN3}=${CN3_TOKEN}"
# Finally add relations to enable autocert for apache2, and create
# nagios check for autocert.
juju add-relation apache2 autocert
juju add-relation nrpe autocert

You would then configure apache2 to use the certificates that AutoCert manages
renewals for. This typically means having a stanza in your https vhost
template as follows (where the locations match the name of the certificate
AutoCert is managing):

SSLEngine On
SSLCertificateFile /etc/ssl/certs/{{ ssl_certlocation }}
SSLCertificateKeyFile /etc/ssl/private/{{ ssl_keylocation }}
SSLCertificateChainFile /etc/ssl/certs/{{ ssl_chainlocation }}

Configuration

autocert_ca_cert
(string) X.509 CA certificate for the above, if running without a root-trusted certificate. Copy and paste a PEM-encoded CA certificate into this field.
autocert_host
(string) IP address or hostname of service to contact
cert_additional_names
(string) A list of comma-separated, key=value pairs specifiying additional names for certificates to be mapped to via symbolic links. The value is a colon separated list of supplementary names, e.g. "test1.example.com=default:example.com, test2.example.com=mail.example.com" Alternatively, multiple key=value pairs can be specified as a YAML list.
cert_auth_pairs
(string) A list of comma-separated, key=value pairs representing the certificates to be managed, along with their respective auth tokens, e.g. "test1.example.com=DEADBEEF, test2.example.com=FEEDFACE, test3.example.com=BAADF00D" Alternatively, multiple key=value pairs can be specified as a YAML list.
cert_kubernetes_names
(string) A list of comma-separated, key=value pairs specifying certificate to kubernetes secret mappings. The value is a slash separated kubernetes namespace and secret name, e.g. "test1.example.com=production/test1-tls, test2.example.com=staging/test2-tls" Alternatively, multiple key=value pairs can be specified as a YAML list.
chain_required
(boolean) Whether an intermediate chain is required for this service
True
dir_certs
(string) Directory to save certs (and chain certs) to (will be created if it does not exist)
/etc/ssl/certs
dir_keys
(string) Directory to save private keys to (will be created if it does not exist)
/etc/ssl/private
extra_packages
(string) Space separated list of extra deb packages to install.
filename_prefix
(string) Prefix for saved cert/key files, e.g. "autocert" for "autocert_<foo.example.com>.crt"
install_keys
(string) List of signing keys for install_sources package sources, per charmhelpers standard format (a yaml list of strings encoded as a string). The keys should be the full ASCII armoured GPG public keys. While GPG key ids are also supported and looked up on a keyserver, operators should be aware that this mechanism is insecure. null can be used if a standard package signing key is used that will already be installed on the machine, and for PPA sources where the package signing key is securely retrieved from Launchpad.
install_sources
(string) List of extra apt sources, per charm-helpers standard format (a yaml list of strings encoded as a string). Each source may be either a line that can be added directly to sources.list(5), or in the form ppa:<user>/<ppa-name> for adding Personal Package Archives, or a distribution component to enable.
ppa:autocert-devs/stable
nagios_context
(string) Used by the nrpe subordinate charms. A string that will be prepended to instance name to set the host name in nagios. So for instance the hostname would be something like: juju-myservice-0 If you're running multiple environments with the same services in them this allows you to differentiate between them.
juju
nagios_servicegroups
(string) A comma-separated list of nagios servicegroups. If left empty, the nagios_context will be used as the servicegroup
package_status
(string) The status of service-affecting packages will be set to this value in the dpkg database. Valid values are "install" and "hold".
install
service_action
(string) Action to run in "service <service_name> <service_action>", e.g. "reload" when certificate changes (one of service_action or service_action_cmd must be specified).
service_action_cmd
(string) Command to run when certificate changes (one of service_action or service_action_cmd must be specified).
service_name
(string) Service name - this will be used for the /etc/autocert/<service_name> config directory, as well as in "service <service_name> <service_action", if service_action is set.
service_test_cmd
(string) Optional command to parse and verify the existing config before restarting/reloading the service, e.g. "/usr/sbin/apachectl configtest". If the return code is 0, then "service <service_name> <service_action>" will be run automatically. If not, then an error will be raised.
suffix_cert
(string) Suffix for cert files, e.g. ".crt" for "<foo.example.com>.crt"
.crt
suffix_chain
(string) Suffix for CA chain files, e.g. "_chain.crt" for "<foo.example.com>_chain.crt"
_chain.crt
suffix_key
(string) Suffix for key files, e.g. ".key" for "<foo.example.com>.key"
.key