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.

Esta guía te lleva paso a paso por la configuración del broker de Certplane para obtener certificados de confianza pública desde Let’s Encrypt usando el desafío dns-01. El desafío dns-01 demuestra la propiedad del dominio creando un registro DNS TXT; funciona incluso para servidores no accesibles desde internet y es necesario para certificados wildcard.
Let’s Encrypt aplica límites de tasa estrictos en su entorno de producción. Valida siempre tu configuración contra el entorno de staging antes de pasar a producción.
1

Obtén tu token de API de Cloudflare

En el panel de Cloudflare, crea un token de API con permiso Zone → DNS → Edit acotado a la zona (o zonas) que quieres que gestione Certplane. No uses una Global API Key: un token acotado limita el radio de impacto si la credencial llegara a quedar expuesta.Una vez que tengas el token, anota su valor. Lo almacenarás en el siguiente paso.
2

Almacena el token

El enfoque más sencillo es el proveedor de secretos env. Exporta el token como variable de entorno antes de iniciar el broker:
export CLOUDFLARE_DNS_API_TOKEN="your-token-here"
Si prefieres leer el token desde un archivo o desde HashiCorp Vault, consulta la guía Secretos en Vault y define secrets.provider en consecuencia. El valor de acme.credentials en policy.yml es el nombre interpretado por el proveedor que configures.
Genera tu clave de cuenta ACME antes de continuar. Certplane lee esta clave para firmar las solicitudes ACME: no es un certificado, y debes guardarla en una ubicación segura y con copia de seguridad:
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out /etc/certplane/acme/account.key
3

Configura el broker

Edita tu broker.yml para apuntar el bloque issuer al directorio staging de Let’s Encrypt y configurar el proveedor DNS de Cloudflare. Empieza con staging para confirmar que todo funciona sin gastar los límites de tasa de producción.
issuer:
  provider: acme
  acme:
    directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /etc/certplane/acme/account.key
    dns_provider: cloudflare

secrets:
  provider: env
El account_key debe ser la ruta a la clave privada EC que generaste arriba. El account_email es la dirección que Let’s Encrypt usa para enviar advertencias de expiración; no necesita coincidir con ningún registro DNS.
4

Crea un perfil wildcard en policy.yml

Añade un perfil que solicite un certificado wildcard usando el desafío dns-01. El valor credentials es el nombre del secreto interpretado por tu proveedor de secretos configurado: para el proveedor env, este es el nombre de la variable de entorno.
profiles:
  public_wildcard:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h
Luego permite que el host correspondiente solicite este perfil:
hosts:
  web01:
    identity: web01.internal.example.com
    profiles:
      - public_wildcard
Let’s Encrypt ignora el campo ttl en el momento de la emisión y siempre emite certificados válidos durante 90 días. El valor renew_before controla cuándo renueva Certplane de forma proactiva: el predeterminado de 720h (30 días) es un buen punto de partida.
5

Prueba con staging y luego cambia a producción

Reinicia el broker y dispara una solicitud de certificado desde un agente. Los certificados de staging están firmados por una CA falsa que los navegadores no confían, pero son estructuralmente idénticos a los de producción: cualquier error de configuración aparecerá aquí.Una vez que el certificado de staging se emita correctamente, cambia el broker al directorio de producción:
issuer:
  provider: acme
  acme:
    directory_url: https://acme-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /etc/certplane/acme/account.key
    dns_provider: cloudflare
Reinicia el broker. El siguiente ciclo de renovación (o una solicitud forzada) obtendrá un certificado de producción confiado por todos los principales navegadores y sistemas operativos.