Skip to main content

Migrate from v5.x to Invictus v6

change of endpoints

Invictus v6 uses containerized API instead of Web API or Azure Functions. This means that the endpoints for the Dashboard and the Framework components changes.

removal of v1 Framework components

Invictus v6 no longer supports the PubSub v1, Transco v1 and Matrix v1 components.

Preparing Environment​

Create a new Azure DevOps variable libraries for Invictus for Azure v6

Create a new Azure DevOps variable libraries. This supports the coexistence of both old and new versions in the same environment. It eases the migration from one to the other.

example

If you have a library with the name invictus.{environment}, create a new one with the name invictus.containerized.{environment}. Your pipelines should use these new libraries.

Create an application registration in Microsoft Entra ID

Go to Microsoft Entra ID and create a new application registration for the Invictus API's. Authentication with the Invictus API's happens via this application.

Also, create a new client secret for this application (you will need it later).

Deploying New Version​

⬇️ Download latest version of Invictus-GetSources.ps1

Pipeline/Bicep parameters changes. Please follow the installation guides to see the current supported parameters:

considerations

After Deployment​

Update your Azure Logic Apps parameters files

"invictus": {
    "value": {
        "monitoring": {
            "eventHub": {
                "name": "#{Invictus.Monitoring.EventHub.Name}#",
                "accessRuleId": "#{Invictus.Monitoring.EventHub.AccessRuleId}#"
            }
        },
        "framework": {
            "pubSub": {
-               "v1": {
-                   "definitionUrl": "#{Invictus.Framework.PubSub.V1.DefinitionUrl}#",
-                   "publishUrl": "#{Invictus.Framework.PubSub.V1.PublishUrl}#",
-                   "subscribeUrl": "#{Invictus.Framework.PubSub.V1.SubscribeUrl}#",
-                   "acknowledgeUrl": "#{Invictus.Framework.PubSub.V1.AcknowledgeUrl}#"
-                }
+               "v2": {
+                   "publishUrl": "#{Invictus.Framework.PubSub.V2.Publish.Url}#",
+                   "subscribeUrl": "#{Invictus.Framework.PubSub.V2.Subscribe.Url}#",
+                   "acknowledgeUrl": "#{Invictus.Framework.PubSub.V2.Acknowledge.Url}#"
+			    }   
            },
-           "matrix": {
-               "v1": {
-                   "definitionUrl": "#{Invictus.Framework.Matrix.V1.DefinitionUrl}#",
-                   "matrixUrl": "#{Invictus.Framework.Matrix.V1.MatrixUrl}#",
-                   "basicMatrixUrl": "#{Invictus.Framework.Matrix.V1.BasicMatrixUrl}#"
-               }
-           },
            "transco": {
-               "v1": {
-                   "definitionUrl": "#{Invictus.Framework.Transco.V1.DefinitionUrl}#",
-                   "transcoUrl": "#{Invictus.Framework.Transco.V1.TranscoUrl}#"
-               }
+               "v2": {
+                   "transcoJsonUrl": "#{Invictus.Framework.Transco.V2.TranscoJson.Url}#",
+                   "transcoXmlUrl": "#{Invictus.Framework.Transco.V2.TranscoXml.Url}#",
+                   "basicMatrixUrl": "#{Invictus.Framework.Transco.V2.MatrixBasicPromote.Url}#"
+			    }
            }
        },
+       "authentication": {
+   		"audience": "api://#{Invictus.Containers.Client.Id}#"
+	    }
    }
}

Update your Azure Logic Apps Invictus API authentication

The Invictus API's now requires an access token in the HTTP Authorization header instead of a function key. Add this on the HTTP action in your Logic App:

"authentication": {
    "audience": "[parameters('invictus').authentication.audience]",
    "identity": "[parameters('infra').managedIdentity.id]",
    "type": "ManagedServiceIdentity"
}

This example uses a user assigned managed identity. It uses the application ID from the newly created app registration as the audience.

don't forget

Include the application ID in the customApplicationIds Bicep parameter.

tip

Invictus can auto-create its user assigned managed identity. Keep in mind that Logic Apps only supports a single user assigned managed identity. If you already have one in your environment, keep using that one.

Remove outdated Azure resources

  • invictus-{prefix}-dashboard
  • invictus-{prefix}-dashboardgateway
  • invictus-{prefix}-cacheimportjob
  • invictus-{prefix}-database-storeimportjob
  • invictus-{prefix}-datafactoryreceiver
  • invictus-{prefix}-flowhandlerjob
  • invictus-{prefix}-invictusimportjob
  • invictus-{prefix}-storeimportjob
  • invictus-{prefix}-appplan-linux
  • invictus-{prefix}-importjobappins

After migrating your Azure Logic Apps to Invictus v6, remove the following resources:

  • invictus-{prefix}-matrixapp
  • invictus-{prefix}-pubsubapp
  • invictus-{prefix}-transcoapp
  • invictus-{prefix}-exceptionhandler
  • invictus-{prefix}-genericreceiver
  • invictus-{prefix}-httpreceiver
  • invictus-{prefix}-pubsub-v2
  • invictus-{prefix}-timesequencer
  • invictus-{prefix}-regextranslator
  • invictus-{prefix}-sequencecontroller
  • invictus-{prefix}-transco-v2
  • invictus-{prefix}-xmljsonconverter
  • invictus-{prefix}-xsdvalidator
  • invictus-{prefix}-appplan
  • invictus-{prefix}-consumptionplan

Remove lingering role assignments

The v6 installation results in lingering Unknown role assignments. You can delete them.

Common Migration Issues​

pipeline error: Operating system not supported

You should use a linux agent in your release pipeline, for example vmImage: 'ubuntu-latest'

Pipeline Error: Invalid ContainerApp name....The length must be between 2 and 32 characters inclusive.

If you override the default app names, you've might have made it too long. Azure Container Apps has a name limit lower than for Function Apps.