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.

certplane-agent run inicia el bucle de renovación de larga duración del agente. En cada iteración, el agente comprueba si algún certificado gestionado se acerca a su umbral renew_before. Si toca renovar, el agente genera una clave privada, construye una solicitud de firma de certificado y la envía al broker por mTLS usando el certificado de identidad obtenido durante el registro. El broker valida la solicitud contra la política, emite o devuelve un certificado en caché de Let’s Encrypt, y el agente escribe el certificado, la cadena y la cadena completa en las rutas configuradas. Si hay un reload_command configurado para esa entrada de certificado, el agente lo ejecuta tras escribir los archivos.

​
Inicia el agente

Ejecuta el siguiente comando en el host registrado: 
certplane-agent run --config /etc/certplane/agent.yml
El agente registra logs en stderr en formato text a nivel info por defecto. Puedes anular ambos con logging.format y logging.level en agent.yml.
El agente registra logs en stderr por defecto (logging.destination: stderr, logging.format: text, logging.level: info). Cuando se ejecuta bajo systemd, stderr es capturado automáticamente por el journal; no se necesita configuración de log adicional.

​
Qué ocurre en la primera ejecución

Cuando el agente arranca y aún no existe un certificado en la ruta cert configurada, lo trata como inmediatamente listo para renovar y procede con el flujo completo de emisión:
  1. Generación de clave — el agente genera una nueva clave privada y la escribe en certificates[].key.
  2. Creación del CSR — se construye una solicitud de firma de certificado a partir de los dns_names y profile configurados.
  3. Solicitud mTLS al broker — el CSR se envía al broker. El agente se autentica con su certificado de identidad (identity.cert / identity.key) sobre TLS mutuo.
  4. El broker emite el certificado — el broker valida la solicitud contra la entrada de política del host y solicita un certificado a Let’s Encrypt (o devuelve uno en caché si todavía es válido).
  5. Archivos escritos — el agente escribe el certificado firmado en cert, la cadena intermedia en chain y la cadena completa en fullchain.
  6. Comando de recarga — si reload_command está definido, el agente lo ejecuta dentro de reload_timeout segundos.
Define reload_command con el comando que indica a tu servicio que recargue su configuración TLS sin un reinicio completo. Por ejemplo:
certificates:
  - name: edge-wildcard
    # ...
    reload_command: "systemctl reload nginx"
    reload_timeout: 30s
Otros ejemplos comunes: systemctl reload traefik, systemctl reload vault.

​
Comportamiento en régimen permanente

Tras la emisión inicial, el agente ejecuta un bucle de comprobación de renovación. En cada tick compara la validez restante de cada certificado con el valor renew_before del certificado. Cuando la validez restante cae por debajo de ese umbral, el agente repite el mismo flujo de emisión descrito arriba. El broker almacena en caché el certificado más recientemente emitido para cada perfil. Si el certificado en caché todavía tiene más del umbral de renovación propio del broker, el broker devuelve el paquete en caché en lugar de crear una nueva orden ACME. Esto evita solicitudes innecesarias a Let’s Encrypt.

​
Ejecutar como servicio systemd

Para uso en producción, gestiona el agente con systemd para que se inicie al arrancar y se reinicie ante fallos. Crea /etc/systemd/system/certplane-agent.service: 
[Unit]
Description=Certplane agent renewal loop
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/certplane-agent run --config /etc/certplane/agent.yml
Restart=on-failure
RestartSec=10s
# Ejecuta como un usuario dedicado si tu despliegue crea uno.
# User=certplane
# Group=certplane

[Install]
WantedBy=multi-user.target
Habilita e inicia el servicio: 
systemctl daemon-reload
systemctl enable --now certplane-agent.service
systemctl status certplane-agent.service
Consulta el journal para ver la salida del agente: 
journalctl -u certplane-agent.service -f
Para una referencia completa de cada campo de configuración aceptado por el agente, consulta Configuración del agente.