Installing the Teams Connector using a blue-green deployment/upgrade strategy

The Teams Connector deployment/upgrade process supports a blue-green deployment strategy. This approach allows you to create separate environments where one environment (blue) is running the current application version and another environment (green) is running the new application version. This means that you can test both of these deployments separately, and switch between them.

This is different from the regular deployment and upgrade strategy that involves deploying a single Teams Connector environment that is destructively replaced during the upgrade process.

This topic covers:

Benefits of using a blue-green strategy

We recommend using a blue-green deployment strategy, where you have two Teams Connector environments deployed in parallel, as it:

  • Provides a non-destructive upgrade path.
  • Increases application availability during the upgrade process.
  • Enables upgrade activities to be done in business hours when access to required service administrators/owners are more readily available, before a planned "switch over" window.
  • Reduces time-pressure and risk if there are delays due to Azure resources not being available.
  • Reduces deployment risk by simplifying the rollback process if a deployment fails.

Advantages over alternative strategies

An alternative upgrade strategy that also enables you to maintain a working production environment while upgrading to a new software version would be to deploy a brand new Teams Connector for every software release and then switch to using that system when it is tested and ready.

This would work but the drawbacks to this approach are that for every upgrade you would need to involve all of the service administrators/owners and have to go through all of the other installation steps every time, such as creating DNS records, possibly issuing a new certificate, obtaining Azure permissions, creating a new API app etc. Whereas with a blue-green strategy you plan ahead and set up two systems at the time of the initial deployment, and keep and re-use the same resources — you just switch back and forth between the two environments.

How it works

The main difference between the blue-green deployment and upgrade strategy described here compared to the regular deployment is that you deploy two Teams Connectors (one called "blue" and another called "green") and switch between them as you upgrade from one version of Teams Connector software to the next. Whereas with the regular deployment you only maintain one Teams Connector which you replace at every upgrade cycle.

Specifically, the differences between the two methods are:

  • For blue-green you deploy two Teams Connectors. Each Teams Connector needs a unique DNS name and a TLS certificate that matches that identity. You use different names for the $PxVmssRegion variable to create specific, separate Azure resources for the two deployments (you use a separate variables script for each deployment).
  • For blue-green each deployment requires its own API app. However, the two deployments can both use the same CVI app and you only need to perform one app authorization process (per tenant). You also only need one Azure bot.
  • With the regular deployment procedure:

    • You simply replace your existing single deployment every time you upgrade to the next Teams Connector software version. It reuses the existing Azure resources, DNS records and so on.
    • While upgrading you have a period of time when you have no Teams interop service and no ability to separately test the latest version. Typically you have to perform the entire upgrade process during "out-of-hours".
  • With the blue-green procedure:

    • You have one deployment which is currently active (in "production") and one that is dormant. When you upgrade, you upgrade the dormant system, without any interference to the active system. You can then test the new system and switchover to that new system when you are happy it is functioning as expected. The previously active system then becomes dormant until the next upgrade occasion.
    • You have 2 DNS records — one for the "blue" system and one for the "green" system.
    • Within Pexip Infinity we suggest that you configure 2 Teams Connector systems, using one for the active/production system (and this is used by all of your Call Routing Rules) and one for the dormant/test system (that is used by a "test" Call Routing Rule.
    • At each switchover you toggle the addresses of the two Teams Connector systems that are configured in the Pexip Infinity Management Node i.e. they switch between pointing at the "blue" and "green" systems.

Deployment requirements and guidelines

The deployment steps are similar to a regular Teams Connector deployment. However, you should note that:

  • You deploy two Teams Connectors. Each Teams Connector needs a unique DNS name and a TLS certificate that matches that identity. You can use a single certificate for both Teams Connectors; this can either be a wildcard certificate or a certificate that contains the Subject Alternative Name (altNames attribute) entries for both Teams Connectors.
  • You do not need to create a new CVI app or perform any additional app authorizations when deploying the second Teams Connector — only one CVI app registration is required per tenant. However you do need to create a new API app for each new deployment.
  • You do not need to create a new CVI app or API app when upgrading (redeploying) to a new version.
  • Both Teams Connectors can use the same set of Conferencing Nodes (the $PxNodeFqdns variable in the initialization script).
  • You create 2 DNS A-records (one for each deployment), and you need to enable the relevant firewall ports for both Teams Connector deployments while you are testing / switching over.

This guide assumes that this is your first Teams Connector deployment. If you have an existing Teams Connector and want to switch to using a blue-green upgrade strategy then you can still follow the principles explained in this guide by creating a second "green" deployment to use alongside your existing deployment (which in effect becomes your "blue" deployment, using whatever name is currently assigned to $PxVmssRegion in your existing variables script).

Installing the Teams Connectors

As with the regular installation, you deploy Teams Connector through PowerShell ISE commands and scripts.

Perform these steps twice — one time for each deployment, where <version> is either "blue" or "green".

  1. Create a new variable initialization script for your <version> deployment. You should do this by making a copy of the variable initialization script. Save this script to a safe location as it will be needed for future upgrades.
  2. Update the variables in the initialization scripts with the values for your <version>. The variables that must be different for the <version> deployment are:

    • $PxVmssRegion: the short name that identifies the deployment. In this case it refers to the Teams Connector deployment identifier: e.g "blue" or "green". Note that you can combine this with a regional deployment if required, e.g. "eublue".
    • $PxTeamsConnFqdn: the hostname of the Teams Connector, for example "pexip-teamsconn-blue-eu.teams.example.com" or "pexip-teamsconn-green-eu.teams.example.com".
    • $TeamsConnectorApiApplicationId: this must be updated to hold the ID of a new Teams Connector API app for the <version> deployment, and is described later in the process below.
    • $PxExistingVNETResourceId: if you are using private routing, each deployment must use its own non-overlapping VNET.

    All other variables can be identical across both scripts.

  3. Create the static and dynamic resource groups for the <version> deployment and ensure that the person performing the installation has the Owner role for them.

    These steps must be performed by the Owner of the Azure subscription used for the Teams Connector.

    1. Run the following PowerShell command to connect to Azure:

      • In all standard deployments run:

        Connect-AzAccount

      • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

        Connect-AzAccount -EnvironmentName AzureUSGovernment

      Then follow the prompts to sign in to Azure.

    2. Run the variable initialization script for the <version> deployment (to set the required subscription, resource group name and region variables).
    3. Ensure that you are using the Azure subscription for the Teams Connector:

      Set-AzContext -SubscriptionId $PxSubscriptionId

    4. Run the following script to create the resource groups:

      You only need to run the command that creates the resource group for the Azure Bot ($PxBotResourceGroupName) once — it can be shared between all <version> deployments.

      Copy to clipboard
      # Resource group for static resources for the Teams Connector / region
      New-AzResourceGroup -Name $PxTeamsConnStaticResourceGroupName -Location $PxAzureLocation -Force -Tag $tags

      # Resource group for the Teams Connector VMSS (per region)
      New-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -Tag $tags

      # Resource group for the Azure Bot
      New-AzResourceGroup -Name $PxBotResourceGroupName -Location $PxAzureLocation -Tag $tags
    5. Ensure that the person who will perform all of the remaining installation steps has the Azure Owner role for the static and dynamic resource groups, and Contributor role for the Azure Bot resource group you have just created. If the Owner of the Azure subscription will perform all of the remaining installation steps then you can skip to Create the Teams Connector API app. below.

      Otherwise, you must run the following commands to assign the required roles for the resource groups you have just created to the person who will perform all of the remaining installation steps:

      New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnStaticResourceGroupName

      New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnResourceGroupName

      New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Contributor" -ResourceGroupName $PxBotResourceGroupName

      where <email_name> is the email address / user principal name of the person who will perform the remaining steps; for example where alice@example.com will perform the upgrade/redeploy, the SignInName would be -SignInName alice@example.com for the commands listed above.

    Note:

    • Some of these resource groups only need creating once; others need recreating when you upgrade or if you redeploy:

      • The static resource group ($PxTeamsConnStaticResourceGroupName) only has to be created when deploying for the first time — you do not have to repeat this when redeploying or for subsequent upgrades to either deployment.
      • The dynamic resource group ($PxTeamsConnResourceGroupName) has to be recreated whenever you upgrade or redeploy.
    • In the future, if another person were to upgrade or redeploy the Teams Connector, that person would also have to be granted the appropriate roles for these resource groups.
    • You can also use the Azure portal to check/assign permissions by selecting the resource group and using the Access control (IAM) option.
  4. Create the Teams Connector API app.

    You must create an Azure app that is used to secure requests to the Teams Connector APIs.

    Each deployment must have its own Teams Connector API app, and thus the variables initialization script for each deployment must be updated to contain the API App ID for that deployment.

    1. Run the following PowerShell command to connect to Azure:

      • In all standard deployments run:

        Connect-AzAccount

      • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

        Connect-AzAccount -EnvironmentName AzureUSGovernment

      Then follow the prompts to sign in to Azure.

    2. Change directory to the folder into which you extracted the files from the Teams Connector ZIP.
    3. Run the following PowerShell commands to connect to Microsoft Graph:

      Copy to clipboard
      # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
      Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

      # The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
      # By default, these files are blocked to protect the computer from untrusted files.
      Get-ChildItem -Recurse | Unblock-File

      # Import the PexTeamsCviApplication PowerShell module
      Import-Module .\PexTeamsCviApplication.psm1

      # Connect to Graph
      Connect-PexTeamsMsGraph
    4. Run your variable initialization script for the <version> deployment to set the required variables.
    5. Run the following command to create the Teams Connector API app.

      Copy to clipboard
      $teamsConnectorApiApp = New-MgApplication -DisplayName "${PxBaseConnName}-TeamsConn-${PxVmssRegion} Pexip Teams Connector API" -SignInAudience "AzureADMyOrg"

      Please allow one minute for this command to complete and propagate within Azure.

    6. Run the following commands to obtain the Teams Connector API app ID.

      Note that if the New-MgServicePrincipal command fails, this means that you have not waited long enough for the previous command to complete.

      Copy to clipboard
      $teamsConnectorApiSp = New-MgServicePrincipal -AppId $teamsConnectorApiApp.AppId -Tags {WindowsAzureActiveDirectoryIntegratedApp}
      $TeamsConnectorApiApplicationId = $teamsConnectorApiApp.AppId

      Write-Host
      Write-Host
      Write-Host "`n----------------------------------------`n"
      Write-Host
      Write-Host "### Teams Connector API App ID MUST be saved in the variables initialization script ###"
      Write-Host
      Write-Host "`$TeamsConnectorApiApplicationId = `"$($TeamsConnectorApiApplicationId)`""
      Write-Host
      Write-Host "`n----------------------------------------`n"
      Write-Host
      Write-Host
    7. When the command runs, it generates some output that lists the Teams Connector API App ID, similar to this:

    8. Copy the output line that defines the API App ID and paste it into the variable initialization script, replacing the existing line in the script that says:

      $TeamsConnectorApiApplicationId = ""

      (If you will be performing the rest of the deployment, in the same PowerShell session, there is no need to re-run the variable initialization script as the new $TeamsConnectorApiApplicationId variable has been set in the previous steps.)

    9. If somebody else will be completing the deployment, ensure that the person who will perform all of the remaining installation steps has Owner permissions for the API app. See Assigning Owner permissions for the API app for more information.

    Note that:

    • This app does not have to be granted any permissions. It does not have access to any resources in the Microsoft Entra ID tenant. It has no associated credentials.
  5. Install the Teams Connector.

    First/existing installation (blue)

    When performing your first (blue) installation:

    1. You must run the standard installation script to install the <version> Teams Connector deployment.

    Second installation (green)

    When performing the second (green) installation:

    1. You need to update the $AppId and $AppCertificatePath variables in the script below to the values reported for the CVI application from the first installation.
    2. Run the modified installation script that is provided below to install the <version> Teams Connector deployment.

    This script applies to software version 34. If you are using an earlier version you should refer to our previous documentation.

    • Standard deployment
    • GCC High / Azure US Government Cloud deployment
    Copy to clipboard
    # Limited installation script for second/green installation

    # Ensure the correct script and software combination is being used
    try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

    if ($PxConnMajorVersion -ne "34"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 34"}

    # Connect to Microsoft Graph, Azure Resource Manager account and import Pexip CVI module
    # Microsoft Graph commands
    # Connect to Microsoft Graph
    # If AAD/365 admin account is not the same as Azure Resource Manager admin account,
    # the next section is to be run by the AAD admin.
    #
    # IMPORTANT: The output of IDs/credentials here must be saved as it will be required later

    # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

    # The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
    # By default, these files are blocked to protect the computer from untrusted files.
    Get-ChildItem -Recurse | Unblock-File

    # Connect to Azure with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
    Connect-AzAccount

    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Connect to Graph
    Connect-PexTeamsMsGraph

    # Before running the following commands, update the following 2 lines/variables with the CVI App ID and
    # the path to the CVI App certificate file that were output when the first/blue installation script was run
    # You'll be prompted for the CVI App certificate password later.
    $AppId = ""
    $AppCertificatePath = ".\your_cvi_app_certificate.pfx"

    # Change context to the Pexip Subscription
    Set-AzContext -SubscriptionId $PxSubscriptionId

    # Virtual Machine Scale Set (VMSS) creation
    # Provide credentials to be used as local user/password for Pexip Teams Connector VMs
    # Create a password (using the initialization script variables) for the Windows VM
    $PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
    $PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

    # Optionally if you did not want to specify the password as a variable, use Get-Credential
    # $PxWinAdminCred = Get-Credential

    # Deploy the Teams Connector VMs
    # this step can take up to 30 minutes to complete
    .\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

    # supply the PFX Teams Connector TLS certificate file password when prompted

    # Please enter the password for the PFX Teams Connector TLS certificate '.\xxxxxxxx.pfx': ***************

    # supply the PFX CVI app certificate file password when prompted

    # Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

    # Generating the next steps summary (this assumes you are connected to Microsoft Graph and with an authenticated account for use with Azure Resource Manager)
    #
    # Setting subscription
    Set-AzContext -SubscriptionId $PxSubscriptionId

    # Getting IP configurations
    if ($PxUsePrivateRouting) {
        $LB = Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName
        $ExtLB = $LB | Where-Object { $_.Name.EndsWith("-LB") }
        $IntLB = $LB | Where-Object { $_.Name.EndsWith("-INTLB") }
        $LBExtIPID = $ExtLB.FrontendIpConfigurations[0].PublicIpAddress.id
        $LBIntIP = $IntLB.FrontendIpConfigurations[0].PrivateIpAddress
        $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
        $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBExtIPID
        $publicIpAddress = $ConnectorPublicIP[0].IpAddress
        $privateIpAddress = $LBIntIP
    } else {
        $LB = (Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName)[0]
        $LBPublicIPID = $LB.FrontendIpConfigurations[0].PublicIpAddress.id
        $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
        $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBPublicIPID
        $publicIpAddress = $ConnectorPublicIP[0].IpAddress
    }

    # Getting connection string for the newly deployed Event hub
    $eventHub = (Get-AzResource -ResourceGroupName $PxTeamsConnStaticResourceGroupName -ResourceType Microsoft.EventHub/namespaces)[0]
    $eventHubKey = Get-AzEventHubKey -Name "pexip_teams_connector_access" -NamespaceName $eventHub.Name -ResourceGroupName $eventHub.ResourceGroupName

    # Printing next steps
    Write-Host
    Write-Host
    Write-Host "`n--------------------------`n"
    Write-Host
    Write-Host "When the Teams Connector is deployed, you have to create a DNS A record for your hostname,"
    Write-Host "then the Office 365 admin must consent for the CVI App Id to join Teams Meetings"
    Write-Host
    Write-Host "1) Set up a public DNS A record for $($PxTeamsConnFqdn) pointing to the Public IP of "
    Write-Host "   the load balancer ($($publicIpAddress))"
    Write-Host
    Write-Host "2) Giving consent to the CVI app is not required for second installation."
    Write-Host
    Write-Host "3) Update the Management Node setting 'Azure Event Hub connection string' for $($PxTeamsConnFqdn) to:"
    Write-Host "    $($eventHubKey.PrimaryConnectionString)"
    Write-Host
    if ($PxUsePrivateRouting) {
        Write-Host "4) Set up a private DNS A record for $($PxTeamsConnFqdn) pointing to the (private) frontend IP of "
        Write-Host "   the internal load balancer ($($privateIpAddress))"
        Write-Host "   See: https://docs.pexip.com/admin/teams_routing.htm#enabling"
    }
    Write-Host
    Write-Host "`n--------------------------`n"
    Write-Host
    Write-Host
    Copy to clipboard
    # Limited installation script for second/green installation
    # This script only applies to GCC High / Azure US Government Cloud deployments

    # Ensure the correct script and software combination is being used
    try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

    if ($PxConnMajorVersion -ne "34"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 34"}

    # Set VmImage variable to hold the CIS STIG image properties - STIG image is optional but typical
    # In a later step in this script you can choose not to use the STIG image 
    $VmImage = @{
    "sku"       = "cis-windows-server2019-stig-gen1"
    "offer"     = "cis-windows-server"
    "publisher" = "center-for-internet-security-inc"
    "version"   = "latest"}

    # Connect to Microsoft Graph, Azure Resource Manager account and import Pexip CVI module
    # Microsoft Graph commands
    # Connect to Microsoft Graph
    # If AAD/365 admin account is not the same as Azure Resource Manager admin account,
    # the next section is to be run by the AAD admin.
    #
    # IMPORTANT: The output of IDs/credentials here must be saved as it will be required later

    # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

    # The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
    # By default, these files are blocked to protect the computer from untrusted files.
    Get-ChildItem -Recurse | Unblock-File

    # Connect to Azure USGovernment with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
    Connect-AzAccount -EnvironmentName AzureUSGovernment

    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Connect to Graph
    Connect-PexTeamsMsGraph

    # Before running the following commands, update the following 2 lines/variables with the CVI App ID and
    # the path to the CVI App certificate file that were output when the first/blue installation script was run
    # You'll be prompted for the CVI App certificate password later.
    $AppId = ""
    $AppCertificatePath = ".\your_cvi_app_certificate.pfx"

    # Change context to the Pexip Subscription
    Set-AzContext -SubscriptionId $PxSubscriptionId

    # Virtual Machine Scale Set (VMSS) creation
    # Provide credentials to be used as local user/password for Pexip Teams Connector VMs
    # Create a password (using the initialization script variables) for the Windows VM
    $PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
    $PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

    # Optionally if you did not want to specify the password as a variable, use Get-Credential
    # $PxWinAdminCred = Get-Credential

    # Deploy the Teams Connector VMs
    # this step can take up to 30 minutes to complete
    # if you are not using a STIG image then remove the following parameter from this command: -VmImage $VmImage
    .\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -VmImage $VmImage -TeamsEnvironmentName TeamsGCCHigh -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

    # supply the PFX Teams Connector TLS certificate file password when prompted

    # Please enter the password for the PFX Teams Connector TLS certificate '.\xxxxxxxx.pfx': ***************

    # supply the PFX CVI app certificate file password when prompted

    # Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

    # Generating the next steps summary (this assumes you are connected to Microsoft Graph and with an authenticated account for use with Azure Resource Manager)
    #
    # Setting subscription
    Set-AzContext -SubscriptionId $PxSubscriptionId

    # Getting IP configurations
    if ($PxUsePrivateRouting) {
        $LB = Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName
        $ExtLB = $LB | Where-Object { $_.Name.EndsWith("-LB") }
        $IntLB = $LB | Where-Object { $_.Name.EndsWith("-INTLB") }
        $LBExtIPID = $ExtLB.FrontendIpConfigurations[0].PublicIpAddress.id
        $LBIntIP = $IntLB.FrontendIpConfigurations[0].PrivateIpAddress
        $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
        $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBExtIPID
        $publicIpAddress = $ConnectorPublicIP[0].IpAddress
        $privateIpAddress = $LBIntIP
    } else {
        $LB = (Get-AzLoadBalancer -ResourceGroupName $PxTeamsConnResourceGroupName)[0]
        $LBPublicIPID = $LB.FrontendIpConfigurations[0].PublicIpAddress.id
        $PublicIPAddresses = Get-AzPublicIpAddress -ResourceGroupName $PxTeamsConnStaticResourceGroupName
        $ConnectorPublicIP = $PublicIPAddresses | Where-Object Id -eq $LBPublicIPID
        $publicIpAddress = $ConnectorPublicIP[0].IpAddress
    }

    # Getting connection string for the newly deployed Event hub
    $eventHub = (Get-AzResource -ResourceGroupName $PxTeamsConnStaticResourceGroupName -ResourceType Microsoft.EventHub/namespaces)[0]
    $eventHubKey = Get-AzEventHubKey -Name "pexip_teams_connector_access" -NamespaceName $eventHub.Name -ResourceGroupName $eventHub.ResourceGroupName

    # Printing next steps
    Write-Host
    Write-Host
    Write-Host "`n--------------------------`n"
    Write-Host
    Write-Host "When the Teams Connector is deployed, you have to create a DNS A record for your hostname,"
    Write-Host "then the Office 365 admin must consent for the CVI App Id to join Teams Meetings"
    Write-Host
    Write-Host "1) Set up a public DNS A record for $($PxTeamsConnFqdn) pointing to the Public IP of "
    Write-Host "   the load balancer ($($publicIpAddress))"
    Write-Host
    Write-Host "2) Giving consent to the CVI app is not required for second installation."
    Write-Host
    Write-Host "3) Update the Management Node setting 'Azure Event Hub connection string' for $($PxTeamsConnFqdn) to:"
    Write-Host "    $($eventHubKey.PrimaryConnectionString)"
    Write-Host
    if ($PxUsePrivateRouting) {
        Write-Host "4) Set up a private DNS A record for $($PxTeamsConnFqdn) pointing to the (private) frontend IP of "
        Write-Host "   the internal load balancer ($($privateIpAddress))"
        Write-Host "   See: https://docs.pexip.com/admin/teams_routing.htm#enabling"
    }
    Write-Host
    Write-Host "`n--------------------------`n"
    Write-Host
    Write-Host

    Note that this script omits the following steps in the standard installation script that only have to be run once (i.e. they do not need to be performed a second time i.e. when installing the second <version> or if you are re-using another pre-existing CVI application):

    • Creating the CVI application and its associated credentials (but you must run the command to assign the $AppSecurePassword variable if you are still using password-based authentication).
    • Creating the Azure Bot.
    • Deploying the Teams Connector admin consent web page.
  6. Update DNS with the <version> Teams Connector FQDN (DNS name) and IP address. The deployment script should have printed the instructions. Thus, at the end of the process you will have two DNS A-records — one for each <version>.

Post deployment steps

After successful initial deployment and testing of both of these Teams Connectors, you can remove the dynamic resource group ($PxTeamsConnResourceGroupName) of the green deployment so you don't have to pay for the redundant Azure resources while that environment is not in use.

(When you upgrade to the next version you will redeploy the green deployment and you will then have two functioning deployments again — the old version and the new version.)

Pexip Infinity Management Node configuration

This section describes how you configure the two Teams Connectors in the Pexip Infinity Management Node, covering the installation, upgrade and switchover scenarios.

Initial installation

When installing the Teams Connectors you can follow the standard instructions to configure your Pexip Infinity platform (Configuring Pexip Infinity as a Microsoft Teams gateway).

However, as you are configuring two Teams Connectors within Pexip Infinity, we suggest that:

  1. When defining your Teams Connectors (Call control > Microsoft Teams Connectors):

    • Define one Teams Connector for the "blue" deployment that is named, for example, "Production system" and is configured with the address and Event Hub connection details for the first/blue deployment.
    • Define a second Teams Connector for the "green" deployment that is named, for example, "Test system" and is configured with the address and Event Hub connection details for the second/green deployment. You should also then deselect the Enable Azure Event Hub checkbox at this stage to prevent any unnecessary alarms being raised while the test system is not in use.
  2. When defining your Call Routing Rules and system locations:

    • Configure all of your main rules and locations to use the "Production system" Teams Connector.
    • Configure one Call Routing Rule to use for testing purposes. For example, you could configure the rule as follows:

      • Destination alias regex match: teamstesting\.(\d{9,12})(@example\.com)?

        (replace example\.com with your own domain)

      • Destination alias regex replace string: \1
      • Call target: select the "Test system" Teams Connector

      This means whenever you want to use your test system you can dial a prefix of "teamstesting." in front of the ID of the Teams conference you want to join, and the call will then be routed through the test Teams Connector.

Upgrade and test

After you have upgraded your test system to the latest Teams Connector software, you can test the new software without having to make any significant configuration changes within Pexip Infinity — the only configuration change required is to select the Enable Azure Event Hub checkbox on the "Test system" Teams Connector for the duration of the testing period.

  • Assuming "blue" is the current production system, after upgrading the "green" system to the latest software you can test it simply by using the existing "test" rule (that you set up during the initial installation and is configured to use the "Test system" Teams Connector).
  • Your existing production system will continue to work normally (using the other Call Routing Rules and the "Production" Teams Connector).

Pexip Infinity version compatibility

Normally you should ensure that you are running the same software version (including minor releases) of Pexip Infinity and Teams Connector to ensure compatibility between the two platforms.

When testing the new Teams Connector software while also running the existing production version it is likely that, for a period of time, you will have a version mismatch between the two platforms. Typically when upgrading to a new minor release there should not be any incompatibility issues. However when upgrading to a new major version of the Teams Connector there could be compatibility issues, and any new features introduced in that new version may not work as expected, and possibly the interop service may not work at all. You must always read the release notes for any known compatibility issues and upgrade guidelines. In some cases you may need to deploy and use a test Pexip Infinity platform that is also running the same software version as the new Teams Connector.

Switching over to the new Teams Connector software

After you have upgraded and tested the new Teams Connector software, you can switch the configuration of the two deployments (Call control > Microsoft Teams Connectors).

Assuming "blue" is the current production system:

  1. Update the "Production system" Teams Connector to use the address and Event Hub connection details of the "green" deployment.

    You are now live with the new software and any new calls will be routed through the new "green" system (any existing calls will remain connected via the "blue" deployment).

  2. Update the "Test system" Teams Connector with the address and Event Hub connection details of the "blue" deployment. You should then also deselect the Enable Azure Event Hub checkbox again.

    This gets it ready for the next upgrade cycle.

At the next upgrade, just repeat the process of switching the configuration of the two Teams Connectors — this time the "blue" system will go back to being the production environment, and "green" will go back to being the test environment. And then just repeat this toggling process in the future.

The benefit of this approach is that you only have to update the configuration of the two Teams Connectors whenever you want to complete the switchover, rather than potentially having to update lots of Call Routing Rules to switch between the two Teams Connector deployments. However, any process that follows the same principles of toggling between the two deployed Teams Connectors is fine.

If you do need to fallback to the previous system you can just reverse the configuration steps to reinstate the previous blue/green deployment as the production system.

Note that no DNS changes required when switching over (after initially creating the 2 A-records during the installation process).

Upgrading the Teams Connector

When you want to upgrade to the latest Teams Connector version you should:

  1. Redeploy the deployment which is currently not in use. For example, after initially using the blue system you will redeploy the green system. You will then have two functioning deployments again — the old version and the new version.
  2. Test the newly redeployed system.
  3. Switch over to the new system and decommission the old deployment version when the transition is complete.

Upgrades to a new version are performed by following the standard steps outlined in Upgrading the Teams Connector to the latest software. However, when using the blue-green deployment strategy note that:

  • You always upgrade the Teams Connector deployment that is currently not in use. The variable script you use for the redeployment has to match the variable script used to deploy that particular deployment (i.e. blue or green).
  • As with any upgrade of the Teams Connector you need to ensure that the dynamic resource group for that deployment is empty. This means that when redeploying, for example the blue deployment, you need to delete and recreate the $PxTeamsConnResourceGroupName of the blue deployment. Make sure that the name doesn’t change when recreating the resource group — it must stay the same as when used previously for that version.
  • After the deployment finishes, and has been tested, follow the Management Node configuration described above to complete the switchover.
  • When the transition is complete you can optionally decommission the old deployment version by removing the dynamic resource group ($PxTeamsConnResourceGroupName) of the old/previous deployment so you don't have to pay for the redundant Azure resources while that environment is not in use.