Rol de Ansible: Certbot (para Let's Encrypt)

Instala y configura Certbot (para Let's Encrypt).

Requisitos

Si se instala desde el código fuente, se requiere Git. Puedes instalar Git usando el rol geerlingguy.git.

Generalmente, instalar desde el código fuente (ver la sección Instalación desde Git) ofrece una mejor experiencia usando Certbot y Let's Encrypt, especialmente si utilizas una versión antigua del sistema operativo.

Variables del Rol

certbot_install_method: package

Controla cómo se instala Certbot. Las opciones disponibles son 'package', 'snap' y 'source'.

certbot_auto_renew: true
certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}"
certbot_auto_renew_hour: "3"
certbot_auto_renew_minute: "30"
certbot_auto_renew_options: "--quiet --no-self-upgrade"

Por defecto, este rol configura un trabajo en cron para ejecutarse bajo la cuenta de usuario proporcionada a la hora y minuto indicados, todos los días. Los valores predeterminados ejecutan certbot renew (o certbot-auto renew) a través de cron todos los días a las 03:30:00, por el usuario que utilices en tu libro de jugadas de Ansible. Se recomienda que establezcas un usuario/hora/minuto personalizado para que la renovación se realice durante un período de poco tráfico y sea ejecutada por una cuenta de usuario no root.

Generación Automática de Certificados

Actualmente se soportan los métodos standalone y webroot para generar nuevos certificados utilizando este rol.

Para un ejemplo completo: consulta el libro de jugadas funcional en molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Establece certbot_create_if_missing a yes o True para permitir que este rol genere certificados.

certbot_create_method: standalone

Establece el método utilizado para generar certificados con la variable certbot_create_method — los valores actuales permitidos son: standalone o webroot.

certbot_testmode: false

Habilita el modo de prueba para ejecutar solo una solicitud de prueba sin crear realmente certificados.

certbot_hsts: false

Habilita (HTTP Strict Transport Security) para la generación de certificados.

certbot_admin_email: email@example.com

La dirección de correo electrónico utilizada para aceptar los TOS de Let's Encrypt y suscribirse a notificaciones relacionadas con certificados. Esto debe ser personalizado y establecido en una dirección de correo electrónico que tú o tu organización monitoreen regularmente.

certbot_certs: []
  # - email: [email protected]
  #   webroot: "/var/www/html"
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

Una lista de dominios (y otros datos) para los cuales deben generarse certificados. Puedes agregar una clave email a cualquier elemento de la lista para anular el certbot_admin_email. Al utilizar el método de creación webroot, debe proporcionarse un elemento webroot, especificando qué directorio utilizar para la autenticación. Asegúrate de que tu servidor web entregue correctamente los contenidos de este directorio.

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

El certbot_create_command define el comando utilizado para generar el certificado.

Generación de Certificados Standalone

certbot_create_standalone_stop_services:
  - nginx

Servicios que deben detenerse mientras certbot ejecuta su propio servidor independiente en los puertos 80 y 443. Si estás utilizando Apache, establece esto como apache2 (Ubuntu) o httpd (RHEL), o si tienes Nginx en el puerto 443 y algo más en el puerto 80 (por ejemplo, Varnish, una aplicación Java, o algo más), agrégalo a la lista para que se detenga cuando se genere el certificado.

Estos servicios solo se detendrán la primera vez que se genere un nuevo certificado.

Instalación Snap

A partir de diciembre de 2020, los mantenedores de Certbot decidieron recomendar la instalación de Certbot desde Snap en lugar de mantener scripts como certbot-auto.

Establecer certbot_install_method: snap configura este rol para instalar Certbot a través de Snap.

Este método de instalación es actualmente experimental y puede o no funcionar en todas las distribuciones de Linux.

Generación de Certificados Webroot

Al utilizar el método de creación webroot, debe proporcionarse un elemento webroot para cada elemento de certbot_certs, especificando qué directorio utilizar para la autenticación. Además, asegúrate de que tu servidor web entregue correctamente los contenidos de este directorio.

Instalación desde Git

Puedes instalar Certbot desde su repositorio de código fuente en Git si lo deseas con certbot_install_method: source. Esto puede ser útil en varios casos, pero especialmente cuando las distribuciones antiguas no tienen paquetes de Certbot disponibles (por ejemplo, CentOS < 7, Ubuntu < 16.10 y Debian < 8).

certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

Opciones del repositorio Git de Certbot. Si se instala desde el código fuente, el repositorio certbot_repo configurado se clona, respetando la configuración certbot_version. Si certbot_keep_updated se establece en yes, el repositorio se actualiza cada vez que se ejecuta este rol.

certbot_dir: /opt/certbot

El directorio dentro del cual se clonará Certbot.

Certificados Wildcard

Let's Encrypt soporta generar certificados wildcard, pero el proceso para generarlos y utilizarlos es algo más complicado. Consulta los comentarios en esta solicitud de extracción para un ejemplo de cómo usar este rol para mantener certificados wildcard.

Michael Porter también tiene una guía sobre Cómo crear un certificado wildcard de Let's Encrypt con Ansible, específicamente con Cloudflare.

Dependencias

Ninguna.

Ejemplo de Libro de Jugadas

- hosts: servers

  vars:
    certbot_auto_renew_user: tu_nombre_de_usuario_aqui
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Consulta otros ejemplos en el directorio tests/.

Creación manual de certificados con certbot

Nota: Puedes hacer que este rol genere certificados automáticamente; consulta la documentación de "Generación Automática de Certificados" arriba.

Puedes crear certificados manualmente usando el script certbot (o certbot-auto) (usa letsencrypt en Ubuntu 16.04, o usa /opt/certbot/certbot-auto si lo instalaste desde el código fuente/Git. Aquí hay algunos comandos de ejemplo para configurar certificados con Certbot:

# Agrega automáticamente certificados para todos los virtualhosts de Apache (utiliza con precaución).
certbot --apache

# Genera certificados, pero no modifica la configuración de Apache (más seguro).
certbot --apache certonly

Si deseas automatizar completamente el proceso de agregar un nuevo certificado, pero no deseas usar la funcionalidad incorporada de este rol, puedes hacerlo utilizando las opciones de línea de comandos para registrarte, aceptar los términos del servicio y luego generar un certificado usando el servidor independiente:

1. Asegúrate de que cualquier servicio que esté escuchando en los puertos 80 y 443 (Apache, Nginx, Varnish, etc.) esté detenido.
2. Regístrate con algo como certbot register --agree-tos --email [[email protected]] - Nota: No necesitarás hacer este paso en el futuro, al generar certificados adicionales en el mismo servidor.
3. Genera un certificado para un dominio cuyo DNS apunte a este servidor: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Reinicia lo que estaba escuchando en los puertos 80 y 443 antes.
5. Actualiza la configuración TLS de tu virtualhost en el servidor web para apuntar al nuevo certificado (fullchain.pem) y a la clave privada (privkey.pem) que Certbot acaba de generar para el dominio que proporcionaste en el comando certbot.
6. Recarga o reinicia tu servidor web para que utilice la nueva configuración de virtualhost HTTPS.

Auto-renovación de certificados de Certbot

Por defecto, este rol agrega un trabajo en cron que renovará todos los certificados instalados una vez al día a la hora y minuto que elijas.

Puedes probar la auto-renovación (sin renovar realmente el certificado) con el comando:

/opt/certbot/certbot-auto renew --dry-run

Consulta la documentación completa y opciones en el sitio web de Certbot.

Licencia

MIT / BSD

Información del Autor

Este rol fue creado en 2016 por Jeff Geerling, autor de Ansible for DevOps.