6.0.0 Migration Guide

6.0.0 Migration Guide

Overview

CromwellOnAzure has significant changes in its deployment model. If you haven't customized your deployment or added your own ACR, --Update should work seamlessly. For others, please note the following:

Key Changes

• Service Images: CoA will no longer publish service images on mcr.microsoft.com. All previous images will be removed by September 2025. Instead, CoA deployments (including updates) will create an ACR in your resource group or use an existing one you specify. The specified cromwell image will be imported into that ACR, and AKS will be configured to use it for the three CoA service images.

• Customized Deployments: If you haven't customized your deployments (e.g. private networking) these changes should be transparent. Otherwise, read on.

Hosting Your Own Service Images

If you host your own service images and wish to continue, you have three options:

1. Build and Push Your Own Images: From the sources.
2. Use a New Binary Tool: To build and import your trigger-service and tes images into your current deployment workflow.
3. Register Your Current ACR: With the binary deployment tool to take over the deployment workflow.

Requirements for Private Networking

• Deployer tool (and build-push-acr): Must have outbound access to api.github.com.
• ACR: Must have outbound access to mcr.microsoft.com and Ubuntu distro binary repositories, as well as wherever you are currently accessing the cromwell image (by default DockerHub). Note that mcr.microsoft.com does not require public internet access from inside Azure Private Networks, but Ubuntu repositories do.

If your networking requirements do not allow this, follow the "Build and Push Your Own Images" route referenced above.

New Deployments and Updates Without Existing ACR/Customized Image Paths

This is the simplest approach. Run the new deployment binary tool as before. It will:

• Create a new ACR in your resource group.
• Configure your User-Assigned Managed Identity for pull request access.
• Download service image sources from GitHub, upload them to the ACR, build and push them.
• Import your Crowell image into that ACR.

Inbound access can be disabled to both the deployer tool and ACR.

If you use either tool provided by this project, it is highly recommended that you create a PAT in GitHub and you add that to an environment variable named GITHUB_TOKEN.

New or Updated Deployments Using an Existing ACR

The binary deployer has a new configuration option: AcrId, the resource id of the ACR you wish to use. The deploying agent must have permission to add role assignments to that ACR, which be in the same subscription as the CoA deployment. This will perform the same tasks as the previous option, but with the specified ACR.

If updating an existing deployment with customized service image paths, set TesImageName and TriggerServiceImageName to empty strings to remove customizations. Otherwise, the deployer tool may warn you that images won't be upgraded or assume you upgraded them yourself, possibly leading to a broken deployment.

New or Updated Deployments Maintaining Your Own ACR

If you prefer to build and push your service images yourself, you can:

• Use the provided build-push-acr binary tool.
• Run a couple of az cli commands with local source code.
• Build and publish the images yourself.

The first two approaches require ACR outbound access mentioned above and the build-push-acr tool may need api.github.com access. Details for using the build-push-acr tool and the az cli commands are provided below.

If building images yourself, use Docker Compose with each Dockerfile from the src directories, push the resulting images to your ACR, and pass the paths to the deployer using the TesImageName and TriggerServiceImageName options.

build-push-acr Usage

The build-push-acr tool has command-line help (--help or -?). It supports two build-type modes (CoA is applicable) and two source code modes: github (online release) or local source code (e.g. a clone of the official GitHub repos).

For online releases, only GitHub releases (e.g. 6.0.0) can be specified. The local source code option requires the directory containing the top-level .sln file.

The subscription, resource-group, and registry arguments are the subscription guid, resource group name, and registry name of the ACR which will build both images needed for CoA and return the docker tag value for the trigger-service and TES images (the tag is prefixed with "Image tag: " in case you are scripting this tool).

az cli Usage

This page describes the feature of the Azure command-line tool that uses ACR to build and host images. For CoA, that tool will need to be invoked twice:

• az acr build --registry $ACR_NAME --image cromwellonazure/triggerservice:$TAG --file /path/to/source-root/src/Dockerfile-TriggerService /path/to/source-root/src
• az acr build --registry $ACR_NAME --image cromwellonazure/tes:$TAG --file /path/to/source-root/src/ga4gh-tes/src/Dockerfile-Tes /path/to/source-root/src/ga4gh-tes/src

Where /path/to/source-root is the directory containing the top-level .sln file, $TAG is the chosen tag, and $ACR_NAME is the name of the ACR.

New Deployer Tool Configuration Options

The deployer tool provides new configuration options for the managed ACR approach. They are required when deploying unreleased builds of the source tree and are mutually exclusive:

• GitHubCommit: Tag, branch, short commit, or full commit value in the official repo. Because of the way GitHub currently works, full commit values should even in clones (on GitHub) of the original repo.
• SolutionDir: Root of the cloned source repository (contains the .sln file).