pulsix_manager

The pulsix_manager role deploys the Pulsix manager, its database (TimescaleDB) and any number of local workers as one compose project in pulsix_manager_dir (/opt/pulsix). Workers on other hosts use pulsix_worker.

What it does

• Checks the settings first: the database password (32 or more characters), the master key (64 hex characters), a public URL with a host name, and unique, valid worker names.
• Writes the secrets to .env with mode 0600 (never logged) and the compose file, then starts the project.
• Waits until the manager has stayed up, so a manager that crashes on start fails the run.
• Reads the setup state. While the setup wizard is not completed, it prints the setup link and token (pulsix_manager_print_setup_token).
• Enrolls the local workers through the manager CLI once the first organization exists.
• With pulsix_manager_host set, adds Traefik labels for the web interface on the shared network.

Key variables

Variable	Default	Meaning
pulsix_manager_db_password	required	Database password. Generate with openssl rand -hex 32.
pulsix_manager_master_key	required	64 hex characters. Encrypts secrets and backups.
pulsix_manager_public_url	required	URL users reach the web interface at. Must use a host name.
pulsix_manager_version	pinned release	Image tag of the manager and worker images, without a leading v.
pulsix_manager_host	empty	Host name Traefik routes to the web interface. Empty adds no route.
pulsix_manager_trusted_proxies	empty	Proxies whose X-Forwarded-For the manager believes.
pulsix_manager_grpc_bind	[]	Host addresses that publish the worker endpoint 8444 for remote workers.
pulsix_manager_http_bind	[]	Host addresses that publish the web interface 8080.
pulsix_manager_workers	one worker, worker-1	Local workers.
pulsix_manager_extra_env	{}	Further manager environment variables.

All variables: pulsix_manager in the reference.

Local workers

Each entry of pulsix_manager_workers is a dict with these keys:

Key	Meaning
name	Required. 1 to 63 lowercase letters, digits or hyphens; unique.
zone	Zone of the worker. Default default.
org	Organization passed to the enrollment command.
max_concurrent	Sets PULSIX_MAX_CONCURRENT, the jobs the worker runs at once.
claim_interval	Sets PULSIX_CLAIM_INTERVAL.
play_uid	UID that runs playbooks. Default 65533; an empty string runs them as the worker.

Example

- hosts: control
  become: true
  roles:
    - noixdev.infra.docker
    - noixdev.infra.traefik
    - role: noixdev.infra.pulsix_manager
      vars:
        pulsix_manager_db_password: "{{ vault_pulsix_db_password }}"
        pulsix_manager_master_key: "{{ vault_pulsix_master_key }}"
        pulsix_manager_public_url: https://pulsix.example.com
        pulsix_manager_host: pulsix.example.com
        pulsix_manager_trusted_proxies: 172.31.255.254
        pulsix_manager_grpc_bind: [192.0.2.5]
        pulsix_manager_workers:
          - { name: ctl-1 }
          - { name: ctl-2, max_concurrent: 4 }

172.31.255.254 is the fixed address Traefik has on the shared network by default.

Setting it up

1. Run the play. The run prints the setup link and token while the wizard is not completed.
2. Open the link and finish the wizard in the browser. It creates the first organization.
3. Run the play again. The local workers enroll as soon as the first organization exists.

Gotchas

• Losing pulsix_manager_master_key makes every backup unreadable. Keep it in a vault, and keep a copy outside the backups.
• pulsix_manager_public_url needs a host name, not an IP address. Passkeys need a domain; the role refuses an IP.
• The worker endpoint is closed by default. With pulsix_manager_grpc_bind empty, only the local workers can reach port 8444. For remote workers, bind it to a private address and keep it off the public internet. The endpoint uses mTLS.
• Every worker must use the same endpoint name. pulsix_manager_grpc_server_name is the name in the endpoint certificate; set the same value as pulsix_worker_server_name on remote workers.
• Keep the TimescaleDB image on the version the Pulsix release names (pulsix_manager_db_image).
• Set pulsix_manager_trusted_proxies to your proxy’s address when the manager sits behind Traefik, or client addresses in the logs will be the proxy’s.