Cromwell on Azure

Overview

The DNAstack Cromwell installer uses Microsoft's Cromwell on Azure installer and Terraform to create an installation of Cromwell using Azure Virtual Machines, Container Apps, and Azure Batch, in Azure resource group.

An Azure Container App is used as the ingress for all requests to Cromwell, and calling this service requires an Azure Active Directory token from a pre-configured Azure Application Registration.

Resource Layout

The following represents the layout of resources, where items in italics are created as part of this installation:

• Active Directory Tenant
  • Azure Subscription
    • Resource Group
      • Cromwell deployment (the exact infrastructure used depends on the CromwellOnAzure version and arguments)
      • Storage Account
      • Virtual Network
      • Log Analytics Workspace
      • Container App with external ingress
  • Application Registration (for authentication with ingress)

Prerequisites

To run this script, you must have the following prepared:

1. Pick an existing Azure subscription and find its ID
2. Install the az and terraform command-line tools.
3. Optional: Install jq — this is used in documented commands for testing your installation, and is not required for installing the engine.

Installation

1. Run the CromwellOnAzure script. This will require you to have installed the az client and authenticated with az login.

   Important: depending on the version of and arguments used with the CromwellOnAzure script, you will get different infrastructure generated by the script. This documentation supports Cromwell deployments in virtual machines (the default for versions 3.2.0 and earlier), and Cromwell deployments in an Azure Kubernetes cluster (the default for version 4.0.0 and later). Several of the following steps will depend on which of these approaches you take, so please take note of whether your installation is using a virtual machine or a Kubernetes cluster.

2. Create a file with variable assignments for your installation, cromwell.tfvars, replacing quoted values on the right-hand sides with literal values.

    ```terraform
    subscriptionId            = "$SUBSCRIPTION_ID"
    resourceGroupName         = "$RESOURCE_GROUP"
    logAnalyticsWorkspaceName = "$LOG_ANALYTICS_WORKSPACE"
    virtualNetworkName        = "$VIRTUAL_NETWORK_NAME"
    kubernetesClusterName     = "$KUBERNETES_CLUSTER_NAME"
    storageAccountName        = "$STORAGE_ACCOUNT_NAME"
    ```
   

   Here is how you can find each of these values:

   • $SUBSCRIPTION_ID: use the same ID used when running the Microsoft CromwellOnAzure script.
   • $RESOURCE_GROUP: is generated for you by the Microsoft CromwellOnAzure script; consult the output to find the name.
   • $LOG_ANALYTICS_WORKSPACE: is generated for you by the Microsoft CromwellOnAzure script; consult the output of the CromwellOnAzure script, or run this command using the $SUBSCRIPTION_ID and $RESOURCE_GROUP from the previous points:

     az monitor log-analytics workspace list --subscription $SUBSCRIPTION_ID -g $RESOURCE_GROUP -o json | jq -r '.[].name'

   • $VIRTUAL_NETWORK_NAME: is generated for you by the Microsoft CromwellOnAzure script; consult the output of the CromwellOnAzure script, or run this command using the $SUBSCRIPTION_ID and $RESOURCE_GROUP from the previous points:

     az network vnet list --subscription $SUBSCRIPTION_ID -g $RESOURCE_GROUP -o json | jq -r '.[].name'

   • $KUBERNETES_CLUSTER_NAME (Cromwell in Kubernetes only): is generated for you by the Microsoft CromwellOnAzure script; consult the output of the CromwellOnAzure script, or run this command using the $SUBSCRIPTION_ID and $RESOURCE_GROUP from the previous points:

     az aks list --subscription $SUBSCRIPTION_ID -g $RESOURCE_GROUP -o json | jq -r '.[].name'

   • $STORAGE_ACCOUNT_NAME: is generated for you by the Microsoft CromwellOnAzure script; consult the output fo the script, or run this command using the $SUBSCRIPTION_ID and $RESOURCE_GROUP from the previous points:

     az storage account list --subscription $SUBSCRIPTION_ID -g $RESOURCE_GROUP -o json | jq -r '.[].name'

3. Apply the configuration with your variable assignments:

   terraform apply -var-file=cromwell.tfvars

   Terraform will print out a plan and ask you to type yes before starting. If you are running this for the first time, the plan should only add resources (no changes or removals). Make sure the plan only adds resources before accepting!

Destroying Installation

Destroying an installation requires two steps:

1. Destroy resources created by Terraform:

   terraform destroy -var-file=cromwell.tfvars

2. Delete the resource group containing Cromwell.

Using the Cromwell Installation

Getting Deployment Information

There are two pieces of information you need to start using your new Cromwell installation:

• The ingress URL
• The Azure App Registry credentials (ID and secret)

To get the ingress URL, run:

terraform output --raw ingress_url

To get the Azure App Registry client credentials, run:

terraform output --raw workbench_client_id
terraform output --raw workbench_client_secret

Sending Requests to Cromwell

To send requests to Cromwell, use the App Registration credentials to obtain an OAuth2 access token, and then use that as a bearer token for requests to the Cromwell API.

After running terraform, this command can be used to obtain an access token and assign it to an environment variable:

ACCESS_TOKEN="$(
  curl -X POST "https://login.microsoftonline.com/$(terraform output --raw tenantId)/oauth2/v2.0/token" \
    -u "$(terraform output --raw workbench_client_id):$(terraform output --raw workbench_client_secret)" \
    -d grant_type=client_credentials \
    -d scope="$(terraform output --raw workbench_client_id)/.default" \
    | jq -r '.access_token'
)"

Now you can send an authenticated request to the Cromwell API:

curl "$(terraform output --raw ingress_url)/api/ga4gh/wes/v1/service-info" \
  -H "Authorization: Bearer $ACCESS_TOKEN"