> ## 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.

# Despliega con los roles de Ansible

> Despliegue de extremo a extremo de certplane-broker y certplane-agent usando los roles oficiales certplane_broker y certplane_agent.

Certplane incluye dos roles de Ansible en el directorio [`ansible/`](https://github.com/TaconeoMental/Certplane/tree/main/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:

```yaml site.yml theme={null}
- 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

```yaml group_vars/certplane_broker.yml theme={null}
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)

```yaml theme={null}
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`](https://github.com/TaconeoMental/Certplane/blob/main/ansible/roles/certplane_broker/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

```yaml host_vars/edge01.yml theme={null}
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)

```yaml theme={null}
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`](https://github.com/TaconeoMental/Certplane/blob/main/ansible/roles/certplane_agent/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](/es/guides/vault-secrets).