Saltar al contenido principal
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: 
step ca token edge01.h.int.example.com
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

install -o certplane -g certplane -m 0600 /dev/stdin /etc/certplane/bootstrap-token <<< "$TOKEN"
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: 
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
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    # O root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s
Hay que dar step_ca.fingerprint o step_ca.root_ca_bundle. Esquema completo en Configuración del agente.

​
Ejecuta el registro

certplane-agent -c /etc/certplane/agent.yml enroll
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

certplane-agent -c /etc/certplane/agent.yml check
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.