Installing Invictus Framework

1. 1

   Prerequisites

   obtain access SharedSame for both Dashboard and Framework. Can be skipped if done already.

   Request access to the Invictus Framework resources from Codit Software.

   Important considerations SharedSame for both Dashboard and Framework. Can be skipped if done already.

   • Container revisions: the deployment uses Multiple Revision mode in its Container App deployments. This means that older revisions could clutter the Container App Environment. You can use this clean-up script to remove them.
   • Lingering role assignments: if a failed install or clean-up deleted resources from the target resource group before this deployment, Azure can leave orphaned role assignments behind. These block the Bicep deployment with a "role assignment already exists" error. Remove orphaned role assignments on the target resource group before you start.

   Include VNET support SharedSame for both Dashboard and Framework. Can be skipped if done already.

   Invictus includes network infrastructure to run resources within an Azure Virtual Network (VNET). Add these required resources to your environment before you deploy Invictus for Azure:

   An Azure Virtual Network

   • Including two subnets, one each for
     • Private Endpoints
     • Container App Environment
   • The subnets must have these 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

   Azure DevOps agent

   Install this software on the self-hosted agent that runs the deployment pipeline:

   • 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

   Add installation script to your repository SharedSame for both Dashboard and Framework. Can be skipped if done already.

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

   Add installation variables to variable group SharedSame for both Dashboard and Framework. Can be skipped if done already.

   You need secrets to pull the installation sources. Codit Software provides these for you. Create a variable group for them:

   • **{'{prefix}'}.Invictus.Installation**
     • Invictus.Installation.StorageAccount.Name: invictusreleases
     • Invictus.Installation.StorageAccount.Container.Dashboard.Name: dashboard-v2
     • Invictus.Installation.StorageAccount.Container.Framework.Name: framework
     • 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

   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 '$(Invictus.Installation.StorageAccount.Container.Framework.Name)'
             -SaveLocation '$(Build.ArtifactStagingDirectory)'
             -UseBeta ${{ parameters.useBeta }}
             -Version ${{ parameters.version }}
                 
       - task: PublishPipelineArtifact@1
         inputs:
           TargetPath: $(Build.ArtifactStagingDirectory)
           ArtifactName: framework
           publishLocation: 'pipeline'

3. 3

   Deploy

   Create environment variable groups SharedSame for both Dashboard and Framework. Can be skipped if done already.

   Create a variable group (like: {prefix}.Invictus.{env}) for each environment. 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. It acts as 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.

   Large request consumption

   Processing large requests can quickly consume the container app's available RAM. Size your container app's memoryResources allocation according to the largest request payloads your installation needs to handle.

   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. container app character limit Azure Container Apps enforce a resource name limit. Keep this prefix to 3 or less characters.
   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).

   Optional Parameters

   Argument name	Default value	Description
   acrEnvironment v6.3 Feature included since Invictus v6.3.	prod	The environment from where the script pulls the Invictus artifacts. (prod, beta or staging).
   additionalTemplateParameters	[]	Custom named parameters for the Bicep template you wish to override. More on this below.
   artifactsPath	$PSScriptRoot	Path on the Azure DevOps agent that stores the downloaded Invictus artifacts (publish and download build artifacts)
   enableVnetSupport	False	Deploys Invictus into a VNET.
   resourceGroupLocation	West Europe	In case no resource group is available with the name resourceGroupName, the deployment uses this location to create such resource group.
   translateBicepOutput	False	If set to True, translates the Bicep outputs (_ becomes .) before placing them in an Azure DevOps variable group.
   validateOnly	False	If set to True, the Bicep deployment only validates the template and doesn't deploy any resources.
   version	latest	Version of the published Invictus artifacts that the deployment should download and deploy on the client environment.
   useBeta v6.3 Feature deprecated since Invictus v6.3. undefined	$null	Indicates the environment of the Azure Container App registry where the deployment gets its container images.

   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

   Use arrow keys to navigate rows. Press Enter or Space to expand a row with sub-properties. Press / to focus the search field.

   Press / to filter