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 registro es el proceso único que establece la identidad de máquina de un host dentro de Certplane. Durante el registro, el agente contacta con tu instancia step-ca con un token de arranque de corta duración, obtiene un certificado de identidad de larga duración y escribe el certificado y la clave privada en las rutas configuradas. Cada interacción posterior entre el agente y el broker se autentica con ese certificado de identidad por mTLS. Solo necesitas ejecutar el registro una vez por host.
Genera un token de arranque
El token de arranque se emite desde el lado de la CA por un operador con acceso a tu instancia step-ca. Generarlo queda fuera del alcance de esta página; consulta la documentación de step-ca para saber cómo crear un token de un solo uso para el provisioner elegido.El token es un JWT firmado que step-ca aceptará exactamente una vez para emitir un certificado de identidad. Escribe el token de arranque en el host
Copia el token de arranque al host que ejecutará el agente y escríbelo en un archivo. La ruta debe coincidir con identity.bootstrap_token en tu agent.yml (ver el siguiente paso).echo "YOUR_BOOTSTRAP_TOKEN" > /etc/certplane/agent/bootstrap-token
chmod 600 /etc/certplane/agent/bootstrap-token
Trata el token de arranque como un secreto. Otorga acceso único a tu CA interna. Restringe los permisos del archivo al usuario que ejecutará certplane-agent y elimina el archivo una vez completado el registro.
Crea agent.yml
Crea /etc/certplane/agent.yml con el siguiente contenido. Cada campo mostrado corresponde a una clave de configuración real.# agent.yml
# Directorio donde el agente almacena su estado en tiempo de ejecución.
# Por defecto /var/lib/certplane/agent.
state_dir: /var/lib/certplane/agent
identity:
# Nombre único para la identidad de este host. Normalmente el FQDN del host.
# Este valor debe coincidir con la identidad registrada en tu archivo de política.
name: pvvl-edge01.h.int.example.com
# Proveedor de CA de identidad. Solo se admite "step-ca".
provider: step-ca
# Ruta donde el agente escribe y lee su certificado de identidad (PEM).
cert: /var/lib/certplane/agent/identity.crt
# Ruta donde el agente escribe y lee su clave privada de identidad (PEM).
key: /var/lib/certplane/agent/identity.key
# Ruta al bundle de CA (PEM) que emitió los certificados de identidad del agente.
# El broker usa esta CA para verificar las conexiones mTLS de este agente.
issuer_ca_bundle: /var/lib/certplane/agent-ca.crt
# Ruta al archivo del token de arranque escrito en el paso anterior.
# Solo se requiere durante el registro inicial. Se puede borrar después.
bootstrap_token: /etc/certplane/agent/bootstrap-token
# Renueva el certificado de identidad cuando queda menos de este tiempo antes de la expiración.
# Por defecto 8h.
renew_before: 8h
# Emite un log de advertencia cuando queda menos de este tiempo antes de la expiración.
# Debe ser mayor que renew_before. Por defecto 24h.
warn_before: 24h
step_ca:
# URL de tu API step-ca.
url: https://ca.int.example.com
# Huella digital SHA256 del certificado raíz de step-ca.
fingerprint: "sha256-fingerprint-of-your-root-ca"
# Ruta al certificado raíz de step-ca (PEM).
# Obligatorio si no se proporciona la huella; opcional si la huella está definida.
root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
broker:
# URL de la API de certplane-broker.
url: https://certplane-broker.int.example.com:8443
# Ruta al bundle de CA (PEM) usado para verificar el certificado TLS del broker.
server_ca_bundle: /etc/certplane/ca/broker-ca.crt
# Tiempo de espera para las llamadas a la API del broker. Por defecto 30s.
timeout: 30s
logging:
# Nivel de log: debug | info | warn | error. Por defecto info.
level: info
# Formato de log: json | text. Por defecto text para el agente.
format: text
# Destino del log. Por defecto stderr.
destination: stderr
certificates:
- # Nombre único para esta entrada de certificado. Se usa en logs y seguimiento de estado.
name: edge-wildcard
# Perfil de certificado a solicitar. Debe estar listado para este host en policy.yml.
profile: public_edge_main
# Nombres DNS a incluir en el SAN del certificado.
dns_names:
- "*.example.com"
# Ruta donde el agente escribe la clave privada de servicio (PEM).
key: /var/lib/certplane/agent/service.key
# Ruta donde el agente escribe el certificado de servicio (PEM).
cert: /var/lib/certplane/agent/service.crt
# Ruta donde el agente escribe la cadena intermedia (PEM).
chain: /var/lib/certplane/agent/service.chain.crt
# Ruta donde el agente escribe la cadena completa del certificado (PEM).
fullchain: /var/lib/certplane/agent/service.fullchain.crt
# Solicita un nuevo certificado cuando queda menos de este tiempo antes de la expiración.
# Por defecto 720h (30 días).
renew_before: 720h
# Comando de shell a ejecutar después de escribir o renovar el certificado.
# Déjalo vacío para omitir. Consulta configuration/agent para más detalles.
reload_command: ""
# Tiempo de espera para reload_command. Por defecto 30s.
reload_timeout: 30s
Ejecuta el registro
Con el archivo de configuración en su sitio, ejecuta el comando de registro:certplane-agent enroll --config /etc/certplane/agent.yml
identity.bootstrap_token, contacta con tu instancia step-ca y obtiene un certificado de identidad firmado. El registro se completa cuando el comando termina con estado 0. Verifica que el certificado de identidad se haya escrito
Tras un registro correcto, el agente escribe dos archivos en las rutas configuradas bajo identity:ls -l /var/lib/certplane/agent/
# identity.crt — el certificado de identidad de máquina firmado
# identity.key — la clave privada correspondiente
enroll para más detalles.El archivo del token de arranque (identity.bootstrap_token) se consume una vez por step-ca y queda inválido tras el registro. Puedes eliminarlo de forma segura del host:rm /etc/certplane/agent/bootstrap-token
