Skip to main content
El registro se ejecuta una vez por host y produce el par (identity.key, identity.cert) que el agente usa en cada llamada al broker.

​
Qué hace el registro

certplane-agent -c <config> enroll:
  1. Toma un lock en <state_dir>/agent.lock.
  2. Se niega a correr si identity.cert ya existe.
  3. Genera una clave ECDSA P-256 en identity.key (modo 0600) si falta; la reutiliza si existe.
  4. Lee el token de arranque desde identity.bootstrap_token.
  5. Construye un CSR con CN = identity.name y lo envía a step-ca en identity.step_ca.url, verificando el servidor con identity.step_ca.fingerprint o identity.step_ca.root_ca_bundle.
  6. Escribe el certificado devuelto en identity.cert y borra el archivo del token.
El lock y la comprobación de existencia hacen seguro enroll desde Ansible — reintentar sobre un host ya registrado falla rápido.

​
Genera un token de arranque

En el host de step-ca:
El CN debe coincidir con identity.name en la configuración del agente. Los tokens son de un solo uso y de corta duración.

​
Coloca el token en el host

El role de Ansible hace esto con no_log: true solo si falta el certificado de identidad.

​
Configuración de identidad del agente

Campos mínimos para el registro:
Hay que dar step_ca.fingerprint o step_ca.root_ca_bundle. Esquema completo en Configuración del agente.

​
Ejecuta el registro

Si todo va bien, el agente escribe identity.crt y borra el token. El host queda listo para el bucle de renovación.

​
Valida la configuración sin registrar

check valida el YAML, aplica defaults, ejecuta la misma lógica Validate() que usa el agente al arrancar y confirma que los archivos existen. No contacta step-ca ni al broker.

​
Solución de problemas

El registro es one-shot. Para repetirlo, borra identity.cert y identity.key, genera un token nuevo y vuelve a ejecutar enroll.
Falta el archivo de token en identity.bootstrap_token. En Ansible, suele significar que no se definió certplane_agent_bootstrap_token para este host.
El archivo existe pero solo contiene espacios. Regenera con step ca token ....
El TLS de step-ca no es de confianza. Define identity.step_ca.fingerprint con el SHA-256 de la raíz, o identity.step_ca.root_ca_bundle con un PEM que la contenga.
El server.mtls.agent_ca_bundle del broker debe confiar en la CA que firmó identity.cert. Si rotaste la intermedia de step-ca tras desplegar el broker, redespliega el bundle.

​
Siguiente: ejecutar el agente

Ejecutar el agente cubre el subcomando run, el timer de systemd y el modelo de renovación.