6.0.0 Migration Guide

6.0.0 Migration Guide

CromwellOnAzure has some major changes to its deployment model. If you have not customized your deployment and have not added your own ACR, --Update should work for you mostly transparently, but for everyone else, there are some things you will need to know.

Things you need to know

The CoA project will no longer be publishing service images on mcr.microsoft.com, and the images for all previous releases will be removed around the first of September 2025. Instead, deployment of CoA (including updates) will potentially create an ACR in your CoA's resource group (or optionally utilize an existing one you specify). Further, the specified cromwell image configured will be imported into that ACR, and AKS will be configured to use that ACR for the three CoA service images going forward.

If you have not customized your deployments (such as following examples for private networking, etc.) these changes should be transparent to you. Otherwise, please read on.

If you have already been hosting your own service images (possibly through your own ACR) and wish to continue to do so, there are three ways you can continue (from most work/flexibility to easiest): build and push your own images from the sources, incorporate a new binary tool to build and import your trigger-service and tes images into your current deployment workflow, or register your current ACR with the binary deployment tool and let it take over that workflow.

Requirements for successful use of the deployer tool in private networking scenarios: The deployer must have outbound access that includes (directly or implicitly) api.github.com. The ACR must have outbound access that includes (directly or implicitly) mcr.microsoft.com and the ubuntu distro binary repositories. Note that the mcr.microsoft.com does NOT necessarily require public internet access from inside of Azure Private Networks, but the ubuntu repositories do.

If your networking requirements do not allow for this, then you will need to follow the "ACR you wish to maintain yourself" route.

New deployments and updated deployments without an existing ACR/customized image paths

This is the easiest. Simply run the new deployment binary tool as before. It will create a new ACR in your resource group, configure your existing User Managed Identity for pull request access, download the sources for the service images from GitHub and upload them to the ACR which will build and push them, and import your Crowell image in that ACR for you.

Note that there is no requirement for any outside agent to access either the deployer tool or the ACR, so inbound access rules can be completely private.

New or updated deployments where you have an ACR you wish the deployer tool to use going forward

The binary deployer has a new configuration option: AcrId which is the resource id of the ACR you wish to use. The credentials of the deploying agent (user or service principal running the deployer tool) must have permission to add role assignments to that ACR and that ACR must be in the same subscription as the CoA deployment. This will do all the things as the previous section, except with the specified ACR instead of creating a new one.

If you are updating an existing deployment where you customized the service image paths, you will need to set TesImageName and TriggerServiceImageName to the empty string in order to remove the customizations. Otherwise, the deployer tool will either warn you that the images won't be upgraded or will assume you already upgraded the images yourself, possibly leading to a broken deployment.

New or updated deployments where you have an ACR you wish to maintain yourself

If you do not wish to have the deployer tool build and push your service images for you, you can do so yourself, either by using the provided build-push-acr binary tool, a couple az cli command-line run from the scr directories of the source code or by building/publishing the images yourself. The first two approaches require the ACR public internet access mentioned above and the build-push-acr tool may require api.github.com access (depending on the command-line passed). Details of using the build-push-acr tool and the az cli command-lines are provided below.

If you are building images completely yourself, you will need to use docker compose with each of the Dockerfile's (from each of the two src directories) from somewhere with internet access, then push the resulting images to your ACR and pass the resulting paths to the deployer (using the TesImageName and TriggerServiceImageName deployer tool configuration options).

build-push-acr usage

The build-push-acr tool has command-line help (--help with alias of -?). It has two build-type modes (CoA is the applicable one) and two source code modes: github (aka online release) or local source code, such as a clone of the official GitHub repos.

Note that with the online release option, only releases on GitHub (e.g. 6.0.0) can be specified. The local source code option requires providing the directory containing the top-level .sln file corresponding to the build-type.

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 returns to the last line of standard output the docker tag value you should use for both the trigger-service and tes images (prefixed with "Image tag: ").

New deployer tool configuration options

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

• GitHubCommit is one of the following: tag, branch, short commit, or full commit value in the official repo for the deployer tool. Because of the way that GitHub currently works, full commit values should work on code in pull requests even if they are in clones of the original repo.
• SolutionDir is the root of the cloned source repository (e.g. contains the .sln file) for the deployer tool.