Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt

Use this file to discover all available pages before exploring further.

El agente de Certplane puede ejecutar un comando de shell inmediatamente después de escribir un certificado renovado en disco. Úsalo para recargar tu servidor web, proxy o cualquier servicio que lea certificados al inicio o con SIGHUP, sin necesidad de tareas cron ni observadores externos.

​
Cómo funciona

Cada entrada en la lista certificates de agent.yml admite dos campos relacionados con la recarga:
  • reload_command — una cadena con un comando de shell que se ejecuta tras escribir los archivos del certificado. El agente lo pasa directamente a /bin/sh -c, así que puedes usar tuberías, condicionales o cualquier otra sintaxis de shell.
  • reload_timeout — cuánto espera el agente a que el comando termine antes de matarlo y registrar un error de timeout. Acepta cadenas de duración Go como 30s o 2m.
El reload_command se ejecuta como el mismo usuario del sistema operativo que el proceso del agente. Asegúrate de que ese usuario tenga permiso para ejecutar el comando, por ejemplo, añadiendo una entrada en sudoers o concediendo al usuario del agente pertenencia en la política ExecReload adecuada de la unidad systemd.
Si reload_command termina con un código distinto de cero, el agente registra un error pero el certificado se escribe igualmente en disco. Una recarga fallida no revierte el certificado ni bloquea futuras renovaciones.
Si se supera reload_timeout, el agente mata el comando de recarga y registra un error. Define el timeout lo suficientemente largo para que la recarga de tu servicio complete: un valor demasiado corto dejará tu servicio ejecutándose con el certificado antiguo.

​
Ejemplo completo

La siguiente entrada de certificates muestra todos los campos relevantes juntos: 
certificates:
  - name: web-wildcard
    profile: public_wildcard
    dns_names:
      - "*.example.com"
    key: /etc/ssl/private/service.key
    cert: /etc/ssl/certs/service.crt
    chain: /etc/ssl/certs/service.chain.crt
    fullchain: /etc/ssl/certs/service.fullchain.crt
    reload_command: systemctl reload nginx
    reload_timeout: 30s
    renew_before: 720h

​
Ejemplos por servicio

certificates:
  - name: web-wildcard
    profile: public_wildcard
    key: /etc/ssl/private/service.key
    cert: /etc/ssl/certs/service.crt
    fullchain: /etc/ssl/certs/service.fullchain.crt
    reload_command: systemctl reload nginx
    reload_timeout: 30s

​
Usar un script envoltorio para lógica compleja

Si tu lógica de recarga implica varios pasos —por ejemplo, concatenar la clave y el certificado en un bundle PEM, establecer la propiedad y luego recargar HAProxy— pon esa lógica en un script envoltorio y apunta reload_command a él. Esto mantiene agent.yml legible y hace que la lógica de recarga sea probable de forma independiente.
#!/usr/bin/env bash
set -euo pipefail

cat /etc/ssl/private/service.key /etc/ssl/certs/service.fullchain.crt \
  > /etc/haproxy/certs/bundle.pem
chown haproxy:haproxy /etc/haproxy/certs/bundle.pem
chmod 640 /etc/haproxy/certs/bundle.pem
systemctl reload haproxy
Haz el script ejecutable (chmod +x /usr/local/bin/deploy-cert.sh) y asegúrate de que sea propiedad de root o del usuario del agente.