Adding and Updating an Engine

Workbench does not contain any preconfigured engines and requires you add one prior to submitting any run requests. This guide will walk you through the process of adding an engine to Workbench.

Steps to Add an Engine

To begin, navigate to the Engines page from the Workbench user interface and click on the "Add Engine" button in the top right corner.

You will be navigated to a new page where you can select the engine type you would like to add. Workbench supports engines on Google Cloud Platform, Amazon Web Services (HealthOmics), Microsoft Azure and On-Premises. Select the engine type you would like to add and click on it.

Choosing the Right engine

There is no right answer when it comes to selecting an engine. The engine you choose will depend on your specific project needs and the resources you have available. When selecting an engine, consider the following:

• Supported Regions: Different engines have different regions where they are available. Make sure the engine you choose is available in the region you need both from a compliance and data locality perspective.

• Egress Reduction: Data can exist in different regions and cloud environments. Moving data between regions and clouds can incur costs. Make sure you choose an engine that can access the data you need without incurring additional costs.

• Cost: Different engines have different costs associated with them. Make sure you understand the pricing model of the engine you choose.

• WDL Language Support: Some engines may have better support for specific WDL features. For example, Cromwell currently only supports WDL 1.0, whereas miniWDL (and by extension HealthOmics) supports up to WDL 1.2

When adding an engine, there is some metadata required that will help make your interaction with it in Workbench easier

1. Name:

   • Provide your engine with a meaningful name so that you can easily locate it in the future

2. ID:

   • The engine ID is a unique identifier for the engine and can only contain letters, numbers underscores and dashes. When you type in the name, the ID will be automatically generated based on the name you provide, however you can provide a custom ID if you wish.

   • The engine ID is the primary way to reference the engine in the CLI and API

3. Provider:

   • The cloud / on-premises provider that the engine is hosted on. This is used to determine the engine type and the configuration options available, as well as helping to optimize data locality and egress costs

   • Depending on the Engine type you choose, the provider may be prepopulated

4. Region:

   • The region where the engine is hosted specific to the provider

5. Configuration:

   • The configuration options available will depend on the engine type you choose. For example, if you choose an AWS engine, you will need to provide an access key and secret key. If you choose a GCP engine, you will need to provide a service account key. For more information on the configuration options for each engine, see the relevant engine configuration guide

Once you have filled in all the metadata and engine configuration, click the "Save" button in the bottom left hand corner. When you click save the engine configuration will be validated and connectivity checks will be performed to ensure the engine is online and available. See below for more information on the engine state.

Steps to Update an Engine

To update an engine, navigate to the Engines page and select the engine you would like to update. This will bring you to the edit engine page where you can update the engine name and engine configuration. You cannot change the engine type or ID of an engine once it has been created.

Updating the engine is very similar to adding an engine, presents the same form used. Simply update the relevant fields and click the "Save" button in the bottom left hand corner when you are done.

The Engine State

The current state of the engine is displayed on the engine state card to the right of the configuration options with a timestamp of the last time a state check was performed. The overall state can be either ONLINE or OFFLINE.

The card has a list of each check that was performed and the result of that check. If a check fails, a helpful error message will be displayed to help you diagnose and hopefully solve the issue. Additionally, the last time the check was successfully performed is displayed to help you understand when the issue may have started.

For more information on how to troubleshoot engine issues, see each engine's configuration guide.