Skip to main content

Installing Invictus Framework

  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 functionality 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 will need 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. Download

    Save installation script to your repository Shared​

    The Invictus-GetSources.ps1 script will pull 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. 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:

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

    Mandatory Parameters​

    Argument nameDescription
    arcNameThe 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.)
    arcPathThe Azure Container App registry base path to form the source image location of the container images.
    arcUsernameThe username credential to authenticate the Docker CLI.
    arcPasswordThe password credential to authenticate into the Docker CLI.
    resourcePrefixAn abbreviation to include in all the Azure resource names that Invictus deploys, often an environment name.
    resourceGroupNameThe name of the Azure resource group where the main Invictus components deploys to.
    variableGroupNameDevOps variable group to write the Bicep outputs to (ex. Invictus_CosmosDb_DbName).
    useBetaIndicates the environment of the Azure Container App registry where the deployment gets its container images.

    Optional Parameters​

    Argument nameDefault valueDescription
    artifactsPath$PSScriptRootPath 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.
    versionlatestVersion 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​

    Showing 72 parameters
    NameDescriptionTags
    acaIdentityName
    default: invictus-${resourcePrefix}-aca-identity

    The name of the user-assigned identity that pulls the container images from the Azure Container Registry.

    		container-apps
    aiResourcesLocation
    default: swedencentralnew since v6.3

    Location where the Framework deploys the Azure AI Foundray services.

    		comp:exception-handler
    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.

    		networkingvnet
    allowStorageAccountSharedKeyAccess
    default: null

    Indicates whether the shared Azure Storage Account allows authentication via a shared key access.

    		storagesecurity
    appInsightsName
    default: invictus-${resourcePrefix}-appins

    The name of the Azure Application Insights resource that tracks the general telemetry of the Framework components.

    		monitoring
    appInsightsSamplingPercentage
    default: 1

    The sampling percentage for the Azure Application Insights that tracks the general telemetry of the Framework components.

    		monitoring
    approvedMessageSizeInBytes
    default: 200000

    The maximum byte threshold where the PubSub component applies the claim-check functionality.

    		comp:pubsubmessaging
    autoResubmitDeferredMessages
    default: false

    Indicates whether the PubSub component should automatically resubmit/recover an Azure Service Bus message older than the deferral time limit.

    		comp:pubsubmessaging
    blobContainerPrefix
    default: invictus

    An custom abbreviation to include in the claim-check Azure Blob Storage container name, used by the PubSub component.

    		storage
    caeVnetInfraRgName
    default: invictus-${resourcePrefix}-cae-infra

    The name of the Azure Container Apps infrastructure resource group (when VNET is enabled).

    		container-appsnetworkingvnet
    containerAppEnvironmentSubnetName

    The name of the subnet to form the network rules of the Azure Container App environment, useful for VNET deployments.

    		networkingvnetcontainer-apps
    containerAppEnvironmentSubnets

    A list of subnet names to form the network rules of all the Azure Container App resources, useful for VNET deployments.

    		networkingvnetcontainer-apps
    containerAppsEnvironmentLocation
    default: resourceGroup().location

    The Azure location for the Azure Container Apps and their environment.

    		container-apps
    containerAppsEnvironmentName
    default: invictus-${resourcePrefix}-cae

    The name of the Azure Container App environment.

    		container-apps
    containerRegistryName

    The name of the Azure Container Apps registry that hosts the Framework components' container images.

    		container-apps
    containerRegistryUrl
    default: ${resourcePrefix}.acr.azurecr.io

    The server URL of the Azure Container Apps registry that hosts the Framework components' container images.

    		container-apps
    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.

    		security
    customTags
    default: {}

    A set of Azure resource tags to apply to all to the deployed Invictus resources.

    		governance
    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.

    		comp:pubsubmessaging
    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.

    		security
    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.

    		storagenetworkingsecurityvnet
    dnsZoneResourceGroupName
    default: resourceGroup().name

    The name of the Azure resource group where the private DNS zone deploys to.

    		networkingvnet
    dnsZoneSubscriptionId
    default: subscription().subscriptionId

    The Azure subscription ID to control the private DNS zone throughout, useful for VNET deployments.

    		networkingvnet
    enableVnetSupport
    default: false

    Feature flag to control whether the Framework deploys within a VNET.

    		networkingvnet
    exceptionHandlerFunctionName
    default: inv-${resourcePrefix}-exceptionhandler

    The name of the Azure Container App deployed for the Exception Handler component.

    		comp:exception-handlercontainer-apps
    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.

    		security
    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.

    		security
    invictusExceptionHandlerFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the Exception Handler component.

    		comp:exception-handlercontainer-apps
    invictusPubSubV2FunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the PubSub component.

    		comp:pubsubcontainer-apps
    invictusRegexTranslatorFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the Regex Translator component.

    		comp:regex-translatorcontainer-apps
    invictusSequenceControllerFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the Sequence Controller component.

    		comp:sequence-controllercontainer-apps
    invictusTimeSequencerFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the Time Sequencer component.

    		comp:time-sequencercontainer-apps
    invictusTranscoV2FunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the Transco component.

    		comp:transcocontainer-apps
    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.

    		security
    invictusXmlJsonConverterFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the XML-JSON Converter component.

    		comp:xml-json-convertercontainer-apps
    invictusXsdValidatorFunctionLocalContainerImage

    The URL that navigates to the Azure Container App image of the XSD Validator component.

    		comp:xsd-validatorcontainer-apps
    keyVaultEnablePurgeProtection
    default: false

    Indicates whether the shared Azure Key Vault should be protected against purging.

    		security
    keyVaultName
    default: invictus-${resourcePrefix}-vlt

    The name of the shared Azure Key Vault, used by all Framework components.

    		security
    keyVaultSubnets

    A list of subnet names to form the Azure Key Vault resource, useful for VNET deployments.

    		networkingvnet
    location
    default: resourceGroup().location

    The main Azure location where Invictus deploys its resources, some advanced resources can be configured with their own location.

    		governance
    LogAnalyticsWorkspaceAppInsightsName
    default: invictus-${resourcePrefix}-loganalytics-appinsights

    The name of the Azure Log Analytics workspace that collects all Azure Application Insights resources deployed.

    		monitoring
    messageStatusCacheDeleteAfterDays
    default: 30

    The time period (in days) after which the storage policy deletes the message status Azure Storage Account table.

    		storage
    pubSubSubscriptionLockTimeoutInMinutes
    default: 1

    The amount of time in minutes the PubSub component locks an Azure Service Bus message received on a topic subscription.

    		comp:pubsubmessaging
    pubsubV2FunctionName
    default: inv-${resourcePrefix}-pubsub-v2

    The name of the Azure Container App deployed for the PubSub component.

    		comp:pubsubcontainer-apps
    pubSubV2TopicName
    default: pubsubv2router

    The name of the Azure Service Bus topic, used by the PubSub component to send/receive messages from.

    		comp:pubsubmessaging
    regexTranslatorFunctionName
    default: inv-${resourcePrefix}-regextranslator

    The name of the Azure Container App deployed for the Regex Translator component.

    		comp:regex-translatorcontainer-apps
    resourcePrefix
    required

    An abbreviation to include in all the Azure resource names that Invictus deploys, often an environment name.

    		governance
    sequenceControllerFunctionName
    default: inv-${resourcePrefix}-seqcontroller

    The name of the Azure Container App deployed for the Sequence Controller component.

    		comp:sequence-controllercontainer-apps
    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.

    		comp:pubsubmessaging
    serviceBusNamespaceName
    default: invictus-${resourcePrefix}-sbs

    The name of the Azure Service Bus namespace resource where the PubSub component controls its messages.

    		comp:pubsubmessaging
    serviceBusSkuName
    default: enableVnetSupport ? Premium : Standard

    The pricing tier of the Azure Service Bus, used by the PubSub component.

    		comp:pubsubmessaging
    serviceBusSubnets

    A list of subnet names to form the Azure Service Bus namespace resource, useful for VNET deployments.

    		networkingvnet
    storageAccountMinimumTLSVersion
    default: TLS1_2

    The minimum allowed TLS version of the shared Azure Storage Account, used by all Framework components.

    		storagesecurity
    storageAccountName
    default: invictus${resourcePrefix}store

    The name of the shared Azure Storage Account, used by all Framework components.

    		comp:pubsubcomp:transcocomp:regex-translatorcomp:xsd-validatorcomp:xml-json-convertercomp:time-sequencercomp:sequence-controllerstorage
    storageAccountSubnets

    A list of subnet names to form the Azure Storage Account resource, useful for VNET deployments.

    		networkingvnetstorage
    storageAccountType
    default: Standard_LRS

    The pricing tier of the shared Azure Storage Account, used by all Framework components.

    		storage
    timesequencerFunctionName
    default: inv-${resourcePrefix}-timesequencer

    The name of the Azure Container App deployed for the Time Sequencer component.

    		comp:time-sequencercontainer-apps
    transcoV2FunctionName
    default: inv-${resourcePrefix}-transco-v2

    The name of the Azure Container App deployed for the Transco component.

    		comp:transcocontainer-apps
    useOpenAPI
    default: falsenew since v6.3

    Feature flag to control whether the Framework components deploys with OpenAPI/Swagger specifications

    		monitoring
    useResourceLocks
    default: true

    Feature flag to control whether the deployed Azure resources have resource locks.

    		governance
    vnetName

    The name of the Azure Virtual Network (VNET) resource that forms the base for all network-related rules and subnets throughout.

    		networkingvnet
    vnetResourceGroupName
    default: resourceGroup().name

    The name of the Azure resource group where the VNET network rules deploys to.

    		networkingvnet
    xmlJsonConverterFunctionName
    default: inv-${resourcePrefix}-xmljsonconverter

    The name of the Azure Container App deployed for the XML-JSON Converter component.

    		comp:xml-json-convertercontainer-apps
    xsdValidatorFunctionName
    default: inv-${resourcePrefix}-xsdvalidator

    The name of the Azure Container App deployed for the XML-JSON Converter component.

    		comp:xsd-validatorcontainer-apps