Installing Invictus Framework

1. 1

   Prerequisites

   obtain access Shared

   To access the resources stored on Azure Storage and Azure Container Registry you have to request an SAS-token and Azure Container Registry password from coditproducts@codit.eu.

   Container revisions

   We use Multiple Revision mode in our Container App deployments, which means that older revisions could clutter the Container App Environment. We provide a clean-up script that should be run after logging in on the correct subscription, but can be ran in Azure DevOps Pipelines as well.

   Include VNET support Shared

   Invictus includes network infrastructure which allows all its resources to run within an Azure Virtual Network (VNET).

   Required deployment

   • An Azure Virtual Network

     • Including two subnets, one each for:
       • Private Endpoints
       • Container App Environment
     • The subnets must have the following services enabled
       • Microsoft.AzureCosmosDB
       • Microsoft.EventHub
       • Microsoft.KeyVault
       • Microsoft.ServiceBus
       • Microsoft.Storage
     • The Container App subnet must also have the delegation Microsoft.App/environments

   • Private DNS Zones (Bicep template)

     • privatelink.azurecr.io
     • privatelink.blob.core.windows.net
     • privatelink.file.core.windows.net
     • privatelink.mongo.cosmos.azure.com
     • privatelink.queue.core.windows.net
     • privatelink.servicebus.windows.net
     • privatelink.table.core.windows.net
     • privatelink.table.cosmos.azure.com
     • privatelink.vaultcore.azure.net
     • privatelink.{regionName}.azurecontainerapps.io

   • To be able to deploy the app code from an Azure DevOps pipeline you require a self hosted agent running on the same VNET with the following software installed:

   • PowerShell
   • Azure PowerShell
   • Bicep CLI

   Required role assignment

   If the Invictus resources and the VNET are on different resource groups, then you need to assign the role of Network Contributor to the Invictus resource group onto the VNET resource group.

2. 2

   Download

   Save installation script to your repository Shared

   The Invictus-GetSources.ps1 script pulls the latest Invictus resources needed to deploy the Framework.

   Add variables to variable group Shared

   Invictus installation requires secrets for authentication. Codit Software provides these for you. Create a variable group for them:

   • **{'{prefix}'}.Invictus.Installation**
     • Invictus.Installation.StorageAccount.Name: invictusreleases
     • Invictus.Installation.StorageAccount.Dashboard.SasToken: value provided by Codit Software (if you're also deploying the Dashboard)
     • Invictus.Installation.StorageAccount.Framework.SasToken: value provided by Codit Software
     • Infra.Environment.ACRUsername: value provided by Codit Software
     • Infra.Environment.ACRPassword: value provided by Codit Software

   YAML Pipeline

   Next step is to add YAML pipelines to build the Invictus for Azure Framework. Change the following example file according to your needs, for example change the trigger path:

     paths:
       include:
       - /src/customer.azure.invictus

   Full YAML build pipeline example

   pr: none
   trigger:
     branches:
       include:
       - main
       - feature/*
     paths:
       include:
       - /src/customer.azure.invictus
   
   parameters:
   - name: Version
     displayName: Invictus Version
     type: string
     default: '*'
   - name: useBeta
     displayName: Use Beta
     type: string
     default: $False
   
   pool:
     vmImage: 'windows-latest'
   
   stages:
   - stage: Package
     displayName: Package
     dependsOn: []
     variables:
     - group: prefix.invictus.installation
     jobs:
     - job: publish
       displayName: Build and Publish Framework
       steps:
       - checkout: self
         clean: true
         persistCredentials: true
   
       - task: PowerShell@2
         displayName: 'Pull Invictus sources'
         inputs:
           targetType: filePath
           filePath: './scripts/Invictus-GetSources.ps1'
           arguments: >
             -StorageAccountName '$(Invictus.Installation.StorageAccount.Name)'
             -StorageSasToken '$(Invictus.Installation.StorageAccount.Framework.SasToken)'
             -StorageContainerName 'framework'
             -SaveLocation '$(Build.ArtifactStagingDirectory)'
             -UseBeta ${{ parameters.useBeta }}
             -Version ${{ parameters.version }}
                 
       - task: PublishPipelineArtifact@1
         inputs:
           TargetPath: $(Build.ArtifactStagingDirectory)
           ArtifactName: framework
           publishLocation: 'pipeline'

3. 3

   Deploy

   Create variable group Shared

   Create a variable group (recommended: {prefix}.Invictus.{env}) for each the environments. The deployment uses this variable group and edits/adds variables based on the Bicep deployment output.

   permit build service access to variable groups

   Make sure the Project Collection Build Service has Administrator access to these variable groups (Pipelines > Library > Security)

   Use Deploy.ps1 script for deployment

   The Deploy.ps1 PowerShell script is available in the downloaded Invictus sources and is the central point of contact for deploying Invictus products.

   Least-privileged Azure role assignments for the deploying identity

   The identity running the Bicep deployment (the service principal used by your Azure DevOps service connection) needs the following least-privileged roles assigned on the target resource group or subscription:

   Role	Why It's Needed
   Container Apps Contributor	Create/update Container Apps environments, apps, authentication configurations and job definitions.
   Azure Event Hubs Owner	Create/update Event Hubs namespaces, hubs and network rule sets.
   Container Registry Contributor	Create/update Azure Container Registry instances, locks, and network settings.
   DocumentDB Account Contributor	Create/update Cosmos DB accounts, MongoDB databases and collections.
   Managed Identity Contributor	Create/update user-assigned managed identities for Container Apps and functions.
   Key Vault Administrator	Create/update Key Vaults, access policies and network ACLs.
   Log Analytics Contributor	Create/update Log Analytics workspaces and list workspace keys.
   Monitoring Contributor	Create/update Application Insights components and associated locks.
   Network Contributor	Create/update private endpoints, VNET subnets and private DNS zone groups.
   Reader	Read existing Private DNS zones when linking DNS zone groups for private endpoints.
   Service Bus Data Owner	Create/update Service Bus namespaces, queues and network rule sets.
   Storage Account Contributor	Create/update storage accounts, file shares, blob, and table services.
   User Access Administrator	Create role assignments (Microsoft.Authorization/roleAssignments) and resource locks.

   Mandatory Parameters

   Argument name	Description
   arcName	The name of the Azure Container Registry name to deploy the container images to. (Make sure to override also the containerRegistryName BICEP parameter if you want a custom name.)
   arcPath	The Azure Container App registry base path to form the source image location of the container images.
   arcUsername	The username credential to authenticate the Docker CLI.
   arcPassword	The password credential to authenticate into the Docker CLI.
   resourcePrefix	An abbreviation to include in all the Azure resource names that Invictus deploys, often an environment name.
   resourceGroupName	The name of the Azure resource group where the main Invictus components deploys to.
   variableGroupName	DevOps variable group to write the Bicep outputs to (ex. Invictus_CosmosDb_DbName).
   useBeta	Indicates the environment of the Azure Container App registry where the deployment gets its container images.

   Optional Parameters

   Argument name	Default value	Description
   artifactsPath	$PSScriptRoot	Path on the Azure DevOps agent that stores the downloaded Invictus artifacts (publish and download build artifacts)
   resourceGroupLocation	'West Europe'	In case no resource group is available with the name resourceGroupName, the deployment uses this location to create such resource group.
   additionalTemplateParameters	[]	Custom named parameters for the Bicep template you wish to override. More on this below.
   version	latest	Version of the published Invictus artifacts that the deployment should download and deploy on the client environment.

   Full YAML task example

   - task: AzureCLI@2
     displayName: 'Azure CLI'
     env:
       SYSTEM_ACCESSTOKEN: $(System.AccessToken)
     inputs:
       azureSubscription: '[YOUR_SERVICE_CONNECTION]'
       scriptType: 'pscore'
       scriptLocation: 'inlineScript'
       inlineScript: |
   
         # Determine where the the provided Invictus 'Deploy.ps1' script is located
         $artifactsPath = ${{ variables['Pipeline.Workspace'] }} + '/_build/framework' 
         $scriptPath = $artifactsPath + '/Deploy.ps1'
   
         & $scriptPath `
           -artifactsPath $artifactsPath `
           -version ${{parameters.Version}} `
           -useBeta false `
           -acrPath "invictusreleases.azurecr.io" `
           -acrUsername 'admin' `
           -acrPassword '<password>' `
           -resourcePrefix 'dev' `
           -resourceGroupName 'my-client-dev-rg' `
           -variableGroupName 'My.Client.Dev' `
           -identityProviderApplicationId '<app-id>' `
           -identityProviderClientSecret '<secret>' `

   Full YAML release pipeline example

   pr: none
   trigger: none
   
   resources:
     pipelines:
       # Name of the pipeline resource inside this workflow. Used to reference the pipeline resources later on (e.g. download artifacts).
     - pipeline: _build
       # Name of the pipeline in Azure Pipelines
       source: 'customer.azure.invictus.framework.build' 
       trigger: true
   
   parameters:
     - name: "Version"
       type: string
       default: "latest"
     - name: "UseBeta"
       type: string
       default: "$false"
   
   pool:
     vmImage: 'ubuntu-latest'
   
   stages: 
   - stage: deploy_dev
     displayName: 'Deploy to Development'
     variables:
     - group: infra.dev
     - group: prefix.invictus.dev
     - group: prefix.invictus.installation
     jobs:
     - deployment: deploy_development
       displayName: 'Deploy to Development'
       environment: Development
       strategy:
         runOnce:
           deploy:
             steps:
             - download: '_build'
               displayName: Download Artifact
             - task: AzureCLI@2
               env:
                 SYSTEM_ACCESSTOKEN: $(System.AccessToken)
               inputs:
                 azureSubscription: 'NameOfYourServiceConnection'
                 scriptType: 'pscore'
                 scriptLocation: 'scriptPath'
                 ScriptPath: '$(Pipeline.Workspace)/_build/framework/Deploy.ps1'
                 ScriptArguments: '-version ${{parameters.Version}} -location "West Europe" -useBeta ${{parameters.UseBeta}} -acrPath "invictusreleases.azurecr.io" -acrUsername $(Infra.Environment.ACRUsername) -acrPassword $(Infra.Environment.ACRPassword) -resourcePrefix $(Infra.Environment.ResourcePrefix) -artifactsPath $(Pipeline.Workspace)/_build/framework -resourceGroupName $(Infra.Environment.ResourceGroup) -variableGroupName invictus.$(Infra.Environment.ShortName) -devOpsObjectId "$(Infra.DevOps.Object.Id)" -identityProviderApplicationId "$(Infra.AzAD.Client.IdentityProviderApplicationId)"  -identityProviderClientSecret "$(Infra.AzAD.Client.IdentityProviderClientSecret)" -containerAppsEnvironmentLocation "$(Infra.Environment.ContainerAppsEnvironmentLocation)"'
   
   - stage: deploy_prd
     displayName: 'Deploy to Production'
     dependsOn: deploy_acc
     variables:
     - group: infra.prd
     - group: prefix.invictus.prd
     - group: prefix.invictus.installation
     jobs:
     - deployment: deploy_prd
       displayName: 'Deploy to Production'
       environment: Production
       strategy:
         runOnce:
           deploy:
             steps:
             - download: '_build'
               displayName: Download Artifact
             - task: AzureCLI@2
               env:
                 SYSTEM_ACCESSTOKEN: $(System.AccessToken)
               inputs:
                 azureSubscription: 'NameOfYourServiceConnection'
                 scriptType: 'pscore'
                 scriptLocation: 'scriptPath'
                 ScriptPath: '$(Pipeline.Workspace)/_build/framework/Deploy.ps1'
                 ScriptArguments: '-version ${{parameters.Version}} -location "West Europe" -useBeta ${{parameters.UseBeta}} -acrPath "invictusreleases.azurecr.io" -acrUsername $(Infra.Environment.ACRUsername) -acrPassword $(Infra.Environment.ACRPassword) -resourcePrefix $(Infra.Environment.ResourcePrefix) -artifactsPath $(Pipeline.Workspace)/_build/framework -resourceGroupName $(Infra.Environment.ResourceGroup) -variableGroupName invictus.$(Infra.Environment.ShortName) -devOpsObjectId "$(Infra.DevOps.Object.Id)" -identityProviderApplicationId "$(Infra.AzAD.Client.IdentityProviderApplicationId)"  -identityProviderClientSecret "$(Infra.AzAD.Client.IdentityProviderClientSecret)" -containerAppsEnvironmentLocation "$(Infra.Environment.ContainerAppsEnvironmentLocation)"'

   Bicep Template Parameters

   Press / to filter

   Showing 72 parameters

   Type	Name	Description
   	acaIdentityName default: invictus-${resourcePrefix}-aca-identity	The name of the user-assigned identity that pulls the container images from the Azure Container Registry.
   	aiResourcesLocation default: swedencentralnew since v6.3	Location where the Framework deploys the Azure AI Foundray services.
   	aiServicesSubnets new since v6.3	A list of subnet names to form the network rules for the Azure AI Foundry resource, useful for VNET deployments.
   	allowStorageAccountSharedKeyAccess default: null	Indicates whether the shared Azure Storage Account allows authentication via a shared key access.
   	appInsightsName default: invictus-${resourcePrefix}-appins	The name of the Azure Application Insights resource that tracks the general telemetry of the Framework components.
   	appInsightsSamplingPercentage default: 1	The sampling percentage for the Azure Application Insights that tracks the general telemetry of the Framework components.
   	approvedMessageSizeInBytes default: 200000	The maximum byte threshold where the PubSub component applies the claim-check functionality.
   	autoResubmitDeferredMessages default: false	Indicates whether the PubSub component should automatically resubmit/recover an Azure Service Bus message older than the deferral time limit.
   	blobContainerPrefix default: invictus	An custom abbreviation to include in the claim-check Azure Blob Storage container name, used by the PubSub component.
   	caeVnetInfraRgName default: invictus-${resourcePrefix}-cae-infra	The name of the Azure Container Apps infrastructure resource group (when VNET is enabled).
   	containerAppEnvironmentSubnetName	The name of the subnet to form the network rules of the Azure Container App environment, useful for VNET deployments.
   	containerAppEnvironmentSubnets	A list of subnet names to form the network rules of all the Azure Container App resources, useful for VNET deployments.
   	containerAppsEnvironmentLocation default: resourceGroup().location	The Azure location for the Azure Container Apps and their environment.
   	containerAppsEnvironmentName default: invictus-${resourcePrefix}-cae	The name of the Azure Container App environment.
   	containerRegistryName	The name of the Azure Container Apps registry that hosts the Framework components' container images.
   	containerRegistryUrl default: ${resourcePrefix}.acr.azurecr.io	The server URL of the Azure Container Apps registry that hosts the Framework components' container images.
   	customApplicationIds default: []	A list of additional IDs referring to custom Microsoft Entra ID applications that should also be able to access the Azure Container Apps hosting the Framework components.
   	customTags default: {}	A set of Azure resource tags to apply to all to the deployed Invictus resources.
   	deferralMessageThresholdInMinutes default: 30new since v6.2	The PubSub component will try to recover Azure Service Bus messages older than this time limit that were stuck in deferral.
   	devOpsObjectId default: deployer().objectId	The object ID associated with the service principal of the enterprise application that the Azure DevOps service connection is created for.
   	disableStorageAccountPublicNetworkAccess default: false	Indicates whether the shared Azure Storage Account should disable public network access. If true, only private endpoints or VNET integration are allowed.
   	dnsZoneResourceGroupName default: resourceGroup().name	The name of the Azure resource group where the private DNS zone deploys to.
   	dnsZoneSubscriptionId default: subscription().subscriptionId	The Azure subscription ID to control the private DNS zone throughout, useful for VNET deployments.
   	enableVnetSupport default: false	Feature flag to control whether the Framework deploys within a VNET.
   	exceptionHandlerFunctionName default: inv-${resourcePrefix}-exceptionhandler	The name of the Azure Container App deployed for the Exception Handler component.
   	exceptionHandlerScaling	The Azure Container App scaling options of the Exception Handler component.
   	identityProviderApplicationId	The application ID of the Microsoft Entra ID app registration that facilitates managed identity authentication for the Azure Container Apps, hosting the Framework components.
   	identityProviderClientSecret	The client secret of the Microsoft Entra ID app registration that facilitates managed identity authentication for the Azure Container Apps, hosting the Framework components.
   	invictusExceptionHandlerFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the Exception Handler component.
   	invictusPubSubV2FunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the PubSub component.
   	invictusRegexTranslatorFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the Regex Translator component.
   	invictusSequenceControllerFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the Sequence Controller component.
   	invictusTimeSequencerFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the Time Sequencer component.
   	invictusTranscoV2FunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the Transco component.
   	invictusUserManagedIdentityName default: invictus-user-managed-identity	The name of the Azure user managed identity that has access to all the deployed Azure Container App components.
   	invictusXmlJsonConverterFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the XML-JSON Converter component.
   	invictusXsdValidatorFunctionLocalContainerImage	The URL that navigates to the Azure Container App image of the XSD Validator component.
   	keyVaultEnablePurgeProtection default: false	Indicates whether the shared Azure Key Vault should be protected against purging.
   	keyVaultName default: invictus-${resourcePrefix}-vlt	The name of the shared Azure Key Vault, used by all Framework components.
   	keyVaultSubnets	A list of subnet names to form the Azure Key Vault resource, useful for VNET deployments.
   	location default: resourceGroup().location	The main Azure location where Invictus deploys its resources, some advanced resources can be configured with their own location.
   	LogAnalyticsWorkspaceAppInsightsName default: invictus-${resourcePrefix}-loganalytics-appinsights	The name of the Azure Log Analytics workspace that collects all Azure Application Insights resources deployed.
   	messageStatusCacheDeleteAfterDays default: 30	The time period (in days) after which the storage policy deletes the message status Azure Storage Account table.
   	pubSubSubscriptionLockTimeoutInMinutes default: 1	The amount of time in minutes the PubSub component locks an Azure Service Bus message received on a topic subscription.
   	pubsubV2FunctionName default: inv-${resourcePrefix}-pubsub-v2	The name of the Azure Container App deployed for the PubSub component.
   	pubSubV2Scaling	The Azure Container App scaling options of the PubSub component.
   	pubSubV2TopicName default: pubsubv2router	The name of the Azure Service Bus topic, used by the PubSub component to send/receive messages from.
   	regexTranslatorFunctionName default: inv-${resourcePrefix}-regextranslator	The name of the Azure Container App deployed for the Regex Translator component.
   	regexTranslatorScaling	The Azure Container App scaling options of the Regex Translator component.
   	resourcePrefix required	An abbreviation to include in all the Azure resource names that Invictus deploys, often an environment name.
   	sequenceControllerFunctionName default: inv-${resourcePrefix}-seqcontroller	The name of the Azure Container App deployed for the Sequence Controller component.
   	sequenceControllerScaling	The Azure Container App scaling options of the Sequence Controller component.
   	serviceBusMessageTimeToLiveMinutes default: 43200	The time limit of the send Azure Service Bus messages by the PubSub component, see Microsoft's messages expiration for more details.
   	serviceBusNamespaceName default: invictus-${resourcePrefix}-sbs	The name of the Azure Service Bus namespace resource where the PubSub component controls its messages.
   	serviceBusSkuName default: enableVnetSupport ? Premium : Standard	The pricing tier of the Azure Service Bus, used by the PubSub component.
   	serviceBusSubnets	A list of subnet names to form the Azure Service Bus namespace resource, useful for VNET deployments.
   	storageAccountMinimumTLSVersion default: TLS1_2	The minimum allowed TLS version of the shared Azure Storage Account, used by all Framework components.
   	storageAccountName default: invictus${resourcePrefix}store	The name of the shared Azure Storage Account, used by all Framework components.
   	storageAccountSubnets	A list of subnet names to form the Azure Storage Account resource, useful for VNET deployments.
   	storageAccountType default: Standard_LRS	The pricing tier of the shared Azure Storage Account, used by all Framework components.
   	timesequencerFunctionName default: inv-${resourcePrefix}-timesequencer	The name of the Azure Container App deployed for the Time Sequencer component.
   	timeSequencerScaling	The Azure Container App scaling options of the Time Sequencer component.
   	transcoV2FunctionName default: inv-${resourcePrefix}-transco-v2	The name of the Azure Container App deployed for the Transco component.
   	transcoV2Scaling	The Azure Container App scaling options of the Transco component.
   	useOpenAPI default: falsenew since v6.3	Feature flag to control whether the Framework components deploys with OpenAPI/Swagger specifications
   	useResourceLocks default: true	Feature flag to control whether the deployed Azure resources have resource locks.
   	vnetName	The name of the Azure Virtual Network (VNET) resource that forms the base for all network-related rules and subnets throughout.
   	vnetResourceGroupName default: resourceGroup().name	The name of the Azure resource group where the VNET network rules deploys to.
   	xmlJsonConverterFunctionName default: inv-${resourcePrefix}-xmljsonconverter	The name of the Azure Container App deployed for the XML-JSON Converter component.
   	xmlJsonConverterScaling	The Azure Container App scaling options of the XML-JSON Converter component.
   	xsdValidatorFunctionName default: inv-${resourcePrefix}-xsdvalidator	The name of the Azure Container App deployed for the XML-JSON Converter component.
   	xsdValidatorScaling	The Azure Container App scaling options of the XSD Validator component.

   ↑↓ navigate↑↑ expand/ filterEsc clear