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

   Optional Parameters

   Argument name	Default value	Description
   acrEnvironment	prod	The environment from where the script pulls the Invictus artifacts. (prod, beta or staging). New since v6.3
   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	$null	Indicates the environment of the Azure Container App registry where the deployment gets its container images. Deprecated since v6.3

   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