Workers are responsible for managing one or more instances of the Alteryx engine. A single-machine install of Alteryx Analytics Hub (AAH) includes one worker, and you can install workers on remote machines. This article describes engine worker installation, licensing, configuration, and license troubleshooting. Here's a flowchart that shows the process.
Use the same installer you used to install AAH or download the Analytics Hub installer from the Alteryx Downloads and Licenses portal. Follow these steps:
- Go to the Alteryx Downloads and Licenses portal at licenses.alteryx.com.
- Sign in or select Don’t have an account? Create one now. If you’re creating a new account register with the email address associated with your Alteryx License.
- Under Product Downloads, select Alteryx Analytics Hub.
- On the Download Products page, select the version of the product you want to download. The latest version is available on the New Versions tab. Access previous versions on the Previous Versions tab.
- On the Downloads page, select the plus icon next to Alteryx Analytics Hub to display a description of the product.
- Select the link for Analytics Hub in the File Name column to download the file.
Enter Engine Worker License
Sign into Analytics Hub as a platform admin. Go to Platform Admin > Licenses > Engine Workers > Activate Licenses. Enter the email address associated with the license and the License Key. Up to 9 additional workers can be installed per Alteryx Analytics Hub license. If you don't need to complete the steps in the next section because you're using certificates issued by a Certificate Authority, restart the Alteryx Engine Worker service now. To do so, open the Services application. and select Alteryx Engine Worker > Restart.
Set Up the Analytics Hub Certificate
This section describes how to create a self-signed certificate and PFX file. You don’t have to do this if you’re using certificates issued by a Certificate Authority.
On the machine where AAH is installed, open Windows PowerShell and run these commands:
- Change directory
cd "INSTALL_LOCATION\Alteryx Analytics Hub"
- Important: If you already have a Root CA certificate, don’t create a new one. Doing so may break connectivity for existing Designer users. Skip to Step 4. If you don’t already have a Root CA certificate, create one with this step.
The first argument
"C:\Program Files"is the location where certificates will be stored. The second argument
"YOUR_MACHINE_NAME"is the hostname to which we issue these certificates. The third argument
"YOUR_DESIRED_PASSWORD"is the password to protect these certificates.
.\ayxhub.ps1 -https generate-selfsigned "C:\Program Files" "YOUR_MACHINE_NAME" "YOUR_DESIRED_PASSWORD"
- Restart all services.
- Generate certificates for the engine worker.
.\ayxhub.ps1 -https generate-worker-selfsigned "C:\Program Files" "YOUR_WORKER_NAME" "YOUR_DESIRED_PASSWORD"
- Note the password for and file path of the CRT and PFX files to use in the next section.
Install an Engine Worker
These steps describe the process of installing and using a self-signed certificate.
- On the machine where you’re installing the engine worker, run the Alteryx Analytics Hub installer.
- Select Worker Only.
- Select an Installation Path. Install in a location with enough storage space for staging assets, workflows, and temporary data for workflow execution.
- To get your installation key, log in to Analytics Hub as a platform admin. Go to Platform Admin > Engine Workers > Worker Status and select Get Installer Key. Select Copy.
- Paste your Installation Key.
- For Choose Certificate Location, select Self-signed Certificate. Or choose Certificate if using certificates from a certificate authority.
- Copy your CRT and PFX files from the AAH machine to this machine (engine worker machine).
- For Please provide path to certificate file, browse to the path of the PFX file you copied to this machine.
- For Please provide path to root certificate file, browse to the path of the CRT file you copied to this machine.
- For Password and Confirm Password fields, enter the password you set for your PFX certificate.
- Enter the Analytics Hub machine for Hub Hostname (for example, machinename.somedomain.com). Enter the hostname of this machine for Worker Hostname. Leave ports as default.
- Select Test to verify that the host and port are accessible. Select Next.
The installer installs all necessary drivers and worker software. This takes 10-15 minutes. Once the install completes, the worker service starts and the engine worker begins taking jobs.
Name Engine Worker
By default, engine worker names are a long string of numbers. You can change the name to something more recognizable. To do so, go to Engine Workers > Worker Status and select an engine worker in the table. Select the default name on the Engine Worker details page to edit the name.
Configure Engine Worker Tags
You can configure engine workers to run specifically tagged jobs. This is helpful if you want to allocate workers for certain job types or priorities, certain sites, or region-specific data processing.
To add tags, go to Platform Admin > Engine Workers > Job Tags > + Add Tag. Enter a tag name and description to help users know when to apply the tag.
To assign tags to workers, go to Engine Workers > Worker Status and select an engine worker in the table. Select a job tag in the Job Tag drop-down menu. Users assign tags to workflows during the Run or Schedule process.
We recommend that you assign tags to 2 engine workers for redundancy, and allow 1 engine worker to take untagged jobs.
Run Metadata Loaders
To execute and sync metadata loaders on engine workers, configure the Postgres database to allow access for connections from a remote client. Make sure your firewall on the machine where AAH is installed allows connection to the Postgres database on port 5432 (default).
An example Postgres configuration (pg_hba.conf) to allow connections from remote clients:
More details are available on the Postgres help site at this link.
To run metadata loaders on a remote worker, set the POSTGRES_HOST or Postgres:hostname variable in Settings.yml (Default Location: C:\Program Files\Alteryx\Alteryx Analytics Hub). When you create a schedule for a metadata loader, AAH adds metadata information to the schedule. One piece of metadata is the ConnectURL, which is the IP address of the server hosting the database. AAH obtains this IP address in the following way:
- AAH searches for the environment variable POSTGRES_HOST and uses its value.
- If the variable from Step 1 is not set, AAH checks the Settings.yml file and the value of variable Postgres:hostname.
- If this variable is not set, AAH sets the address to "localhost."
When you change the POSTGRES_HOST variable or address in Settings.yml, this change is not propagated to existing loader schedules. You have to let users know to delete and recreate schedules.
Metadata Loaders Tag
Analytics Hub has a pre-installed system tag called Loaders. The purpose of this tag is to identify workers that can create a connection to the AAH database. To make sure that loaders only get executed on the local worker, assign this system tag to the workers that can connect to the AAH database. AAH uses the worker with the Loaders tag for running and scheduling metadata loaders. If this tag is not attached to any worker, AAH will use any available worker to run metadata loaders.
To assign the Loaders tag, go to Platform Admin > Engine Workers > Worker Status. Select the engine worker you want to tag from the table, then select Job Tags > Loaders.
Check Worker Status
Easily check the status of workers from Analytics Hub. To see Status, Worker ID, Hostname, and Port, login to AAH as a platform admin and go to Platform Admin > Workers.
Worker statuses are:
- Stopped—If a worker doesn’t check in for 60 seconds, it’s considered stopped. A status of Stopped also displays for decommissioned engine workers.
Some reasons you might need to shut down a worker include changing settings, investigating an issue, or performing maintenance. There are 2 ways to shutdown workers with an API. There is a shutdown endpoint and a kill endpoint. Shutdown shuts down the worker gracefully after it finishes the jobs in progress. Kill immediately stops the worker regardless if any jobs are running on it. To learn more, go to API docs at this address: [YourBaseAddress]/api-docs
Worker Maintenance Script
Similar to the ayxhub.ps1 script, there is a script, ayxworker.ps1, for maintaining and controlling Analytics Hub engine workers.
To use the script:
- Launch Windows Powershell as an Administrator
- Navigate to the Alteryx Analytics Hub folder, for example:
cd 'C:\INSTALL_LOCATION\Alteryx\Alteryx Analytics Hub'
- Input the script file and relevant command. For example, to display a list of commands:
The commands available in this script are:
.\ayxworker.ps1 -set-certs <pfxfile> <password> <encryption-key-location> <rootcertificate>
- Change the settings for HTTPS certificates used to connect the worker and hub, where:
- <PFX_FILE>: Location of the PFX file to be used.
- <PASSWORD>: Password to protect the certificate on the engine worker.
- <ENCRYPTION_KEY_LOCATION>: Location to store the encryption key on the worker.
- <ROOT_CERTIFICATE>: Location of the root certificate file to be used.
- Change the settings for HTTPS certificates used to connect the worker and hub, where:
- Disable HTTPS connection on the engine worker.
- Restart the engine worker service.
Troubleshoot License Errors
Some Reasons for Engine Worker License Errors
- Entered License Key Is Not an Alteryx Engine Worker Product
- License Key Is Expired
- License Key Is Invalid
- Cutlass (Alteryx Service) Fails to Validate the License Key
- There Aren’t Enough Seats on the License Key
Ways to Resolve the Error State
- Go to http://licenses.alteryx.com/ to
- See which License Keys are associated with which Product
- See how many seats are on each License Key
- See which machines have activated which License Key
- Revoke/deactivate License Keys from machines
- Refresh FNO Licensing Context
- Restart Cutlass and Alteryx License Service.
- Replace License
- Go to Platform Admin > Licenses > Replace Licenses
- Enter a new License Key
- Restart the Cutlass service on the engine worker machine.