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.

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

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.