6.0.0 Migration Guide

6.0.0 Migration Guide

Overview

ga4gh-tes 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: ga4gh-tes will no longer publish service images on mcr.microsoft.com. All previous images will be removed by September 2025. Instead, TES deployments (including updates) will create an ACR in your resource group or use an existing one you specify.

• 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 tes image 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: Must have outbound access to api.github.com.
• ACR: Must have outbound access to mcr.microsoft.com and Ubuntu distro binary repositories. 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 "New or Updated Deployments Maintaining Your Own ACR" route.

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.

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 TES 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 to the empty string 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 the Dockerfile from the src directory, push the resulting images to your ACR, and pass the path to the deployer using the TesImageName option.

build-push-acr Usage

The build-push-acr tool has command-line help (--help or -?). It supports two build-type modes (Tes 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 the image needed for TES and return the docker tag value for the TES image (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 TES, that tool will need to be invoked once:

• az acr build --registry $ACR_NAME --image ga4gh/tes:$TAG --file /path/to/source-root/src/Dockerfile-Tes /path/to/source-root/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).