pulsix_worker

The pulsix_worker role runs any number of Pulsix workers on a host that is not the manager’s. Each worker keeps its identity and data in a 0700 subdirectory of pulsix_worker_dir (/opt/pulsix-worker).

What it does

Checks the settings: a manager address as host:port, at least one worker, unique and valid worker names.
Creates a data directory per worker, owned by the worker image’s runtime user.
Looks for each worker’s identity. A worker that has none must get a one-time token; the run stops, and names the workers, if a token is missing.
Writes the compose file and starts the workers.
Waits (up to pulsix_worker_enroll_timeout seconds) for new workers to create their identity.

The token carries the manager CA’s fingerprint, so a worker pins the CA before it first connects, and its private key is created on its own host and never leaves it. A worker that already has an identity needs no token.

Key variables

Variable	Default	Meaning
`pulsix_worker_manager_addr`	required	The manager’s worker endpoint, `host:8444`.
`pulsix_worker_server_name`	`pulsix-manager`	The manager’s `PULSIX_GRPC_SERVER_NAME`.
`pulsix_worker_instances`	`[]`	Workers on this host.
`pulsix_worker_enroll_tokens`	`{}`	One-time tokens by worker name. Pass at run time.
`pulsix_worker_version`	pinned release	Worker image tag; keep it on the manager’s version.
`pulsix_worker_enroll_timeout`	`120`	Seconds to wait for a new worker’s identity.

Each entry of pulsix_worker_instances has name (required), max_concurrent, claim_interval and play_uid (default 65533; an empty string runs playbooks as the worker). The zone is part of the enrollment token, not of this list.

All variables: pulsix_worker in the reference.

Example

- hosts: workers
  become: true
  roles:
    - noixdev.infra.docker
    - role: noixdev.infra.pulsix_worker
      vars:
        pulsix_worker_manager_addr: 192.0.2.5:8444
        pulsix_worker_instances:
          - { name: edge-1 }

Enrolling a worker

In Pulsix, open the Workers page, choose Add worker, pick the zone, and use the same name as in pulsix_worker_instances. Copy the token (pxw1.…).
Pass the tokens at run time. They are valid for one hour and work once.
Terminal window
```
ansible-playbook workers.yml -e @tokens.yml
```
with tokens.yml containing:
```
pulsix_worker_enroll_tokens:
  edge-1: pxw1.…
```
Later runs need no token; the worker has an identity.

Gotchas

Never store tokens in your inventory or repository. They are for one use; pass them with -e and leave them out of version control.
Tokens expire after one hour. Create them right before the run.
Removing a worker from the list stops it. Revoke it on the Workers page as well.
Use the same server_name as the manager. A mismatch with the name in the endpoint certificate stops the connection.
Keep the worker on the manager’s version (pulsix_worker_version).