letsencrypt-formula

Travis CI Build Status Semantic Release

Creates certificates and manages renewal using the letsencrypt service.

1. General notes

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

If you need (non-default) configuration, please pay attention to the pillar.example file and/or Special notes section.

2. Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute for more details.

3. Special notes

None

4. Available states

4.1. letsencrypt

This is a shortcut for letsencrypt.install letsencrypt.config and letsencrypt.domains.

If use_package is True (the default), the formula will try to install the certbot package from your Distro’s repo. Keep in mind that most distros don’t have a package available by default: Ie, current Debian (Stretch) requires a backports repo installed. Centos 7 requires EPEL, etc. This formula DOES NOT manage these repositories. Use the apt-formula or the epel-formula to manage them.

If use_package is False it installs and configures the letsencrypt cli from git, creates the requested certificates and installs renewal cron job.

  • WARNING ** If you set use_package to True, it will:

    • Default to Python3’s certbot package (where possible), with Apache as the default Webserver to manage.

    • Delete all certbot’s crons if they exist from a previous git-based installation (as the package uses a systemd’s timer unit to renew all the certs)

    • Delete git-based installation’s scripts (usually installed under /usr/local/bin) if they still exist declared in letsencrypt's pillar.

    • As a safety measure, if there’s an /opt/letsencrypt directory from a git-based installation, it will be left untouched, but unused.

To check dependencies to use the package for your distro, check https://certbot.eff.org/all-instructions.

4.2. letsencrypt.install

Only installs the letsencrypt client (see above).

4.3. letsencrypt.config

Manages /etc/letsencrypt/cli.ini config file.

4.4. letsencrypt.domains

Creates a certificate with the domains in each domain set (letsencrypt:domainsets in pillar). Letsencrypt uses a relatively short validity of 90 days. Therefore, a cron job for automatic renewal every 60 days is installed for each domain set as well.

5. Testing

Linux testing is done with kitchen-salt.

5.1. Requirements

  • Ruby

  • Docker

$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

5.2. bin/kitchen converge

Creates the docker instance and runs the template main state, ready for testing.

5.3. bin/kitchen verify

Runs the inspec tests on the actual instance.

5.4. bin/kitchen destroy

Removes the docker instance.

5.5. bin/kitchen test

Runs all of the stages above in one go: i.e. destroy + converge
verify + destroy.

5.6. bin/kitchen login

Gives you SSH access to the instance for manual testing.