Comenzar con Certplane

Esta guía recorre toda la configuración de Certplane: ejecutar el broker, definir una política, registrar un host con su certificado de identidad e iniciar el bucle de renovación del agente. Al terminar, tu host tendrá un certificado TLS de confianza pública que se renueva automáticamente.

¿Prefieres Ansible? Salta a la guía de roles de Ansible — los roles certplane_broker y certplane_agent automatizan todo lo que aparece en esta página.

Requisitos previos

Antes de empezar:

step-ca — Una instancia de step-ca accesible desde tus hosts. Es la CA interna que emite los certificados de identidad de los agentes.
Acceso a Let’s Encrypt — El broker usa ACME para obtener certificados públicos. Necesitas un correo válido para la cuenta ACME.
Un proveedor DNS soportado para dns-01 — Actualmente cloudflare o httpreq. Los perfiles wildcard requieren dns-01.
Los binarios de Certplane — certplane-broker en el host del broker y certplane-agent en cada host gestionado. Se compilan con make desde el repositorio fuente.

Despliega el broker

Crea /etc/certplane/broker.yml (refleja examples/config/broker.yml):

broker.yml

server:
  address: ":8443"
  tls:
    cert: /etc/certplane/broker/broker.crt
    key: /etc/certplane/broker/broker.key
    min_version: "1.2"
  mtls:
    agent_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
  read_header_timeout: 5s
  read_timeout: 10s
  write_timeout: 60s
  idle_timeout: 120s

policy:
  path: /etc/certplane/policy.yml
  watch: false

issuer:
  provider: acme
  acme:
    directory_url: https://acme-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /var/lib/certplane/acme/account.key
    dns_provider: cloudflare

secrets:
  provider: env

store:
  driver: sqlite
  path: /var/lib/certplane/broker.db

audit:
  enabled: true
  failure_mode: fail_open
  mirror_to_log: true

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20

logging:
  level: info
  format: json
  destination: stdout

server.mtls.agent_ca_bundle debe ser el bundle de CA que firma los certificados de identidad de tus agentes — normalmente la raíz o intermedia de step-ca.Inicia el broker:

certplane-broker -c /etc/certplane/broker.yml serve

El broker escucha en :8443 y exige mTLS a todo agente conectado. Referencia completa en Configuración del broker.

Crea el archivo de política

Crea /etc/certplane/policy.yml:

policy.yml

version: 1

profiles:
  public_edge_main:
    type: wildcard
    dns_names:
      - "*.example.com"
    acme:
      challenge: dns-01
      credentials: cloudflare/example-com
    renew_before: 720h

hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main

profiles — Cada perfil define type (wildcard o multi_san), dns_names permitidos, opciones ACME (acme.challenge y acme.credentials) y un renew_before opcional.
hosts — Cada entrada mapea una etiqueta a una identity (el CN del certificado emitido por step-ca) y lista los profiles que ese host puede solicitar. Las peticiones a otros perfiles se rechazan.

Valida antes de desplegar:

certplane-broker -c /etc/certplane/broker.yml policy validate --policy /etc/certplane/policy.yml

Referencia completa en Resumen de política.

Registra tu primer host

El registro entrega al host su certificado de identidad. El agente contacta step-ca una vez con un token de arranque corto, genera un par ECDSA localmente y guarda identity.crt.Genera un token de arranque en step-ca:

step ca token edge01.h.int.example.com

Escribe el token en el host en la ruta indicada por la configuración del agente (p. ej. /etc/certplane/bootstrap-token, modo 0600).Crea la configuración del agente en /etc/certplane/agent.yml (refleja examples/config/agent.yml):

agent.yml

state_dir: /var/lib/certplane/agent

identity:
  name: edge01.h.int.example.com
  provider: step-ca
  cert: /var/lib/certplane/agent/identity.crt
  key: /var/lib/certplane/agent/identity.key
  issuer_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
  bootstrap_token: /etc/certplane/bootstrap-token
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s

broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/ca/broker-server-ca-bundle.crt
  timeout: 30s

logging:
  level: info
  format: text
  destination: stderr

certificates:
  - name: edge-wildcard
    profile: public_edge_main
    dns_names:
      - "*.example.com"
    key:       /var/lib/certplane/agent/service.key
    cert:      /var/lib/certplane/agent/service.crt
    chain:     /var/lib/certplane/agent/service.chain.crt
    fullchain: /var/lib/certplane/agent/service.fullchain.crt
    renew_before: 720h
    reload_command: "systemctl reload traefik"
    reload_timeout: 30s

Ejecuta el registro:

certplane-agent -c /etc/certplane/agent.yml enroll

El agente genera identity.key localmente, construye un CSR y lo envía a step-ca junto con el token. Si todo va bien, identity.crt se escribe y el archivo del token se borra.

El token de arranque se consume durante el registro y no es reutilizable. Si falla y necesitas reintentar, genera un token nuevo desde step-ca. Más detalle en Registro del agente.

Ejecuta el agente

Una vez registrado el host, ejecuta el bucle de renovación. El agente es un binario one-shot — programalo con un timer (el role de Ansible incluye uno; consulta Ejecutar el agente para la unidad standalone).

certplane-agent -c /etc/certplane/agent.yml run

En cada ejecución, el agente:

Renueva el certificado de identidad si expira dentro de identity.renew_before.
Para cada entrada en certificates:
- Asegura una clave de servicio ECDSA local en key (la genera si falta, la reutiliza si existe).
- Salta el certificado si el existente es válido y aún no entra en la ventana de renew_before.
- Si no, construye un CSR con los dns_names, llama al broker por mTLS, valida que el bundle devuelto coincide con la clave local y con los DNS solicitados, escribe cert, chain y fullchain, y ejecuta reload_command si está definido.

Valida la configuración y el estado en disco sin cambios:

certplane-agent -c /etc/certplane/agent.yml check

Próximos pasos

Guía de roles de Ansible — despliegue de producción con los roles oficiales.
Configuración del broker y Configuración del agente.
Resumen de política.
Let’s Encrypt + dns-01.

Comenzar

Configuración inicial

Política

Configuración

Guías

Comenzar con Certplane

Próximos pasos

​Próximos pasos

Próximos pasos