Worker Auto Enrollment

Auto enrollment lets you bootstrap external workers without copying API keys by hand. The server issues an API key the first time a worker connects with the shared secret, then the worker caches its credentials locally. Use this flow to scale fleets quickly, then disable it again once provisioning is complete.

Requirements

• A licensed deployment. Community Edition supports only the built-in worker, so external worker enrollment is unavailable.
• Admin access to the server UI.
• A secure channel for distributing the enrollment secret (VPN, secrets manager, or trusted configuration system). Treat it like a root password.

Configure auto-enrollment on the server

1. Sign in to the server UI as an admin.
2. Navigate to Settings → Security.
3. Under Auto-enrollment, enable it and set an enrollment secret (generate a random value of at least 32 characters).
4. Save. The secret is write-only and will not be shown again.

Bootstrap a worker

1. On the worker host, set the URL, a unique name, and the enrollment secret:

   export LYFTDATA_URL=https://lyftdata.example.com
   export LYFTDATA_WORKER_NAME=ingest-us-east-01
   export LYFTDATA_AUTO_ENROLLMENT_KEY=<enrollment-secret>
   export LYFTDATA_JOBS_DIR=/var/lib/lyftdata-worker
   
   lyftdata-worker

2. Confirm the worker joined the fleet in the Workers UI (or via lyftdata workers list).
3. After the first successful enrollment, remove LYFTDATA_AUTO_ENROLLMENT_KEY from the worker’s service configuration. The worker will reuse its cached identity and API key from LYFTDATA_JOBS_DIR on restart.

Rotate or disable enrollment

• Disable auto-enrollment in Settings → Security once provisioning is finished to block unexpected workers.
• Rotate the secret if you suspect exposure.
• To force a specific worker to enroll again, start it with a fresh LYFTDATA_JOBS_DIR (or delete the existing directory after confirming you no longer need the cached identity), then restart it with the current secret.

Runtime authorization and repair

Auto-enrollment only bootstraps the worker identity and API key. After a worker is online, external-worker runtime authorization still depends on signed, time-bounded leases from the server.

If a worker is online but Provider Pack or deployment readiness reports runtime blockers, start with the runtime-requirements report for that deployment or Provider Pack. It can distinguish worker-auth trust issues, missing job bindings, and worker database ACL gaps from ordinary connectivity problems.

Use product repair paths such as worker auth trust reset, worker settings, or runtime-requirements repair proposals. Do not edit server or worker SQLite state files directly to repair enrollment, worker-auth, or worker database settings.

Troubleshooting

Symptom	Where to look	Likely cause
Worker exits immediately	Worker logs (journalctl -u lyftdata-worker)	Secret missing, worker name unset, or cached ID/API key mismatch
Worker shows auth/enrollment errors	Worker + server logs	Auto-enrollment disabled, secret mismatch, or the worker cannot reach the server URL
External workers don’t work	License screen / server logs	Instance is running Community Edition; external workers require a license
Worker never appears in the UI	Worker + server logs	Wrong LYFTDATA_URL scheme/host, TLS trust issues, or firewall rules blocking access
Worker is online but a Provider Pack says the target job is not serviceable	Runtime-requirements report, job status, worker settings	Target job deployment state, job binding, worker-auth lease, or worker database ACL issue

Best practices

• Use auto enrollment only on trusted networks and only for the time it takes to bring new workers online. Disable it afterwards.
• Store the secret in a secrets manager and inject it as an environment variable rather than baking it into images.
• Monitor /api/workers for unexpected entries and alert when workers appear with unfamiliar names.
• Combine enrollment with automation: Terraform/Ansible can start new nodes and immediately disable auto-enrollment once the fleet is provisioned.

With these safeguards in place, auto enrollment speeds up provisioning without sacrificing traceability or control.