Saltar al contenido principal
Certplane incluye dos roles de Ansible en el directorio ansible/ del repositorio:
  • certplane_broker — instala el binario del broker, prepara la configuración y el material TLS, despliega la política y gestiona el servicio de systemd.
  • certplane_agent — instala el binario del agente, despliega bundles de CA y configuración, hace el registro inicial con un token y gestiona el timer de systemd.
Ambos roles soportan Debian Bookworm y Ubuntu Jammy/Noble out of the box.

​
Layout

Añade los roles a tu repositorio de control (roles/ enlazado o vendoreado). Play mínimo:
site.yml
- name: Certplane broker
  hosts: certplane_broker
  become: true
  roles:
    - certplane_broker

- name: Certplane agents
  hosts: certplane_agents
  become: true
  roles:
    - certplane_agent

​
Role certplane_broker

​
Variables obligatorias

group_vars/certplane_broker.yml
certplane_broker_binary: /ruta/en/host-control/certplane-broker
certplane_broker_tls_cert_src: files/broker/broker.crt
certplane_broker_tls_key_src: files/broker/broker.key
certplane_broker_agent_ca_bundle_src: files/ca/agent-identity-ca-bundle.crt
certplane_broker_policy_src: files/broker/policy.yml

certplane_broker_acme_directory_url: https://acme-v02.api.letsencrypt.org/directory
certplane_broker_acme_account_email: admin@example.com
certplane_broker_acme_dns_provider: cloudflare
# certplane_broker_acme_account_key_src: files/broker/account.key   # opcional

​
Variables útiles (con sus defaults)

certplane_broker_user: certplane
certplane_broker_group: certplane
certplane_broker_binary_dest: /usr/local/bin/certplane-broker
certplane_broker_config_dir: /etc/certplane
certplane_broker_state_dir: /var/lib/certplane

certplane_broker_listen: ":8443"
certplane_broker_tls_min_version: "1.2"
certplane_broker_read_header_timeout: 5s
certplane_broker_read_timeout: 10s
certplane_broker_write_timeout: 60s
certplane_broker_idle_timeout: 120s

certplane_broker_policy_path: /etc/certplane/policy.yml
certplane_broker_policy_watch: false

certplane_broker_secrets_provider: env       # env | file | vault | openbao
certplane_broker_vault_mount_path: secret
certplane_broker_vault_kv_version: 2
certplane_broker_vault_key: value
certplane_broker_vault_timeout: 10s

certplane_broker_store_driver: sqlite
certplane_broker_store_path: /var/lib/certplane/broker.db

certplane_broker_audit_enabled: true
certplane_broker_audit_failure_mode: fail_open
certplane_broker_audit_mirror_to_log: false

certplane_broker_rate_limit_per_identity_per_hour: 50
certplane_broker_rate_limit_per_identity_profile_per_hour: 20

certplane_broker_log_level: info
certplane_broker_log_format: json
certplane_broker_log_destination: stdout
Con certplane_broker_secrets_provider = vault/openbao, define además certplane_broker_vault_address y uno entre certplane_broker_vault_token / certplane_broker_vault_token_file.

​
Qué hace el role

  1. Crea el grupo y usuario de sistema certplane.
  2. Copia el binario del broker a certplane_broker_binary_dest.
  3. Crea /etc/certplane, /etc/certplane/tls, /etc/certplane/ca, /var/lib/certplane y /var/lib/certplane/acme.
  4. Despliega TLS cert/key, bundle de CA de agentes, clave de cuenta ACME (si se pasa) y el archivo de política.
  5. Renderiza broker.yml desde templates/broker.yml.j2.
  6. Instala y arranca certplane-broker.service. Cambios en TLS, política o configuración disparan reinicio.

​
Role certplane_agent

​
Variables obligatorias

host_vars/edge01.yml
certplane_agent_binary: /ruta/en/host-control/certplane-agent
certplane_agent_identity_name: edge01.h.int.example.com
certplane_agent_issuer_ca_bundle_src: files/ca/agent-identity-ca-bundle.crt
certplane_agent_broker_ca_bundle_src: files/ca/broker-server-ca-bundle.crt
certplane_agent_broker_url: https://certplane-broker.int.example.com:8443

certplane_agent_step_ca_url: https://ca.int.example.com
# Una de las dos
certplane_agent_step_ca_fingerprint: "sha256:aabbcc..."
# certplane_agent_step_ca_root_ca_bundle_src: files/ca/step-ca-root.crt

# Por host, solo se usa hasta el primer registro
certplane_agent_bootstrap_token: "{{ lookup('pipe', 'step ca token ' + certplane_agent_identity_name) }}"

certplane_agent_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
    reload_command: "systemctl reload traefik"
    reload_timeout: 30s
    renew_before: 720h

​
Variables útiles (con sus defaults)

certplane_agent_user: certplane
certplane_agent_group: certplane
certplane_agent_binary_dest: /usr/local/bin/certplane-agent
certplane_agent_config_dir: /etc/certplane
certplane_agent_state_dir: /var/lib/certplane/agent

certplane_agent_identity_cert: /var/lib/certplane/agent/identity.crt
certplane_agent_identity_key: /var/lib/certplane/agent/identity.key
certplane_agent_identity_renew_before: 8h
certplane_agent_identity_warn_before: 24h

certplane_agent_step_ca_timeout: 10s
certplane_agent_broker_timeout: 30s

certplane_agent_bootstrap_token_path: /etc/certplane/bootstrap-token

certplane_agent_timer_on_boot_sec: 1min
certplane_agent_timer_on_active_sec: 6h
certplane_agent_timer_randomized_delay: 5min

certplane_agent_log_level: info
certplane_agent_log_format: text
certplane_agent_log_destination: stderr

​
Qué hace el role

  1. Crea grupo y usuario certplane.
  2. Instala el binario en certplane_agent_binary_dest.
  3. Despliega el bundle de CA del emisor, el bundle de CA del broker y opcionalmente la raíz de step-ca.
  4. Renderiza agent.yml desde templates/agent.yml.j2.
  5. Registra el host una vez. Si no existe identity.crt y certplane_agent_bootstrap_token está definido, escribe el token (no_log: true) y ejecuta certplane-agent ... enroll como usuario certplane. Tras el éxito, el binario borra el token.
  6. Instala certplane-agent.service (oneshot, check y luego run) y certplane-agent.timer (1min tras boot, cada 6h con jitter de 5min).
  7. Habilita y arranca el timer.
El registro es idempotente: una vez existe identity.crt, las siguientes ejecuciones saltan ambos pasos.

​
Manejo recomendado de secretos

  • Pasa certplane_agent_bootstrap_token desde inventario con Ansible Vault o un lookup en tiempo de ejecución (step ca token).
  • Nunca commitees tokens crudos — son single-use, pero igual.
  • Para los tokens DNS que consume el broker, usa secrets.provider: vault. Ver Secretos en Vault y OpenBao.